aboutsummaryrefslogtreecommitdiff
path: root/crypto/openssl/doc/apps/verify.pod
diff options
context:
space:
mode:
Diffstat (limited to 'crypto/openssl/doc/apps/verify.pod')
-rw-r--r--crypto/openssl/doc/apps/verify.pod328
1 files changed, 0 insertions, 328 deletions
diff --git a/crypto/openssl/doc/apps/verify.pod b/crypto/openssl/doc/apps/verify.pod
deleted file mode 100644
index ea5c29c15021..000000000000
--- a/crypto/openssl/doc/apps/verify.pod
+++ /dev/null
@@ -1,328 +0,0 @@
-=pod
-
-=head1 NAME
-
-verify - Utility to verify certificates.
-
-=head1 SYNOPSIS
-
-B<openssl> B<verify>
-[B<-CApath directory>]
-[B<-CAfile file>]
-[B<-purpose purpose>]
-[B<-untrusted file>]
-[B<-help>]
-[B<-issuer_checks>]
-[B<-verbose>]
-[B<->]
-[certificates]
-
-
-=head1 DESCRIPTION
-
-The B<verify> command verifies certificate chains.
-
-=head1 COMMAND OPTIONS
-
-=over 4
-
-=item B<-CApath directory>
-
-A directory of trusted certificates. The certificates should have names
-of the form: hash.0 or have symbolic links to them of this
-form ("hash" is the hashed certificate subject name: see the B<-hash> option
-of the B<x509> utility). Under Unix the B<c_rehash> script will automatically
-create symbolic links to a directory of certificates.
-
-=item B<-CAfile file>
-
-A file of trusted certificates. The file should contain multiple certificates
-in PEM format concatenated together.
-
-=item B<-untrusted file>
-
-A file of untrusted certificates. The file should contain multiple certificates
-
-=item B<-purpose purpose>
-
-the intended use for the certificate. Without this option no chain verification
-will be done. Currently accepted uses are B<sslclient>, B<sslserver>,
-B<nssslserver>, B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION>
-section for more information.
-
-=item B<-help>
-
-prints out a usage message.
-
-=item B<-verbose>
-
-print extra information about the operations being performed.
-
-=item B<-issuer_checks>
-
-print out diagnostics relating to searches for the issuer certificate
-of the current certificate. This shows why each candidate issuer
-certificate was rejected. However the presence of rejection messages
-does not itself imply that anything is wrong: during the normal
-verify process several rejections may take place.
-
-=item B<->
-
-marks the last option. All arguments following this are assumed to be
-certificate files. This is useful if the first certificate filename begins
-with a B<->.
-
-=item B<certificates>
-
-one or more certificates to verify. If no certificate filenames are included
-then an attempt is made to read a certificate from standard input. They should
-all be in PEM format.
-
-
-=back
-
-=head1 VERIFY OPERATION
-
-The B<verify> program uses the same functions as the internal SSL and S/MIME
-verification, therefore this description applies to these verify operations
-too.
-
-There is one crucial difference between the verify operations performed
-by the B<verify> program: wherever possible an attempt is made to continue
-after an error whereas normally the verify operation would halt on the
-first error. This allows all the problems with a certificate chain to be
-determined.
-
-The verify operation consists of a number of separate steps.
-
-Firstly a certificate chain is built up starting from the supplied certificate
-and ending in the root CA. It is an error if the whole chain cannot be built
-up. The chain is built up by looking up the issuers certificate of the current
-certificate. If a certificate is found which is its own issuer it is assumed
-to be the root CA.
-
-The process of 'looking up the issuers certificate' itself involves a number
-of steps. In versions of OpenSSL before 0.9.5a the first certificate whose
-subject name matched the issuer of the current certificate was assumed to be
-the issuers certificate. In OpenSSL 0.9.6 and later all certificates
-whose subject name matches the issuer name of the current certificate are
-subject to further tests. The relevant authority key identifier components
-of the current certificate (if present) must match the subject key identifier
-(if present) and issuer and serial number of the candidate issuer, in addition
-the keyUsage extension of the candidate issuer (if present) must permit
-certificate signing.
-
-The lookup first looks in the list of untrusted certificates and if no match
-is found the remaining lookups are from the trusted certificates. The root CA
-is always looked up in the trusted certificate list: if the certificate to
-verify is a root certificate then an exact match must be found in the trusted
-list.
-
-The second operation is to check every untrusted certificate's extensions for
-consistency with the supplied purpose. If the B<-purpose> option is not included
-then no checks are done. The supplied or "leaf" certificate must have extensions
-compatible with the supplied purpose and all other certificates must also be valid
-CA certificates. The precise extensions required are described in more detail in
-the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility.
-
-The third operation is to check the trust settings on the root CA. The root
-CA should be trusted for the supplied purpose. For compatibility with previous
-versions of SSLeay and OpenSSL a certificate with no trust settings is considered
-to be valid for all purposes.
-
-The final operation is to check the validity of the certificate chain. The validity
-period is checked against the current system time and the notBefore and notAfter
-dates in the certificate. The certificate signatures are also checked at this
-point.
-
-If all operations complete successfully then certificate is considered valid. If
-any operation fails then the certificate is not valid.
-
-=head1 DIAGNOSTICS
-
-When a verify operation fails the output messages can be somewhat cryptic. The
-general form of the error message is:
-
- server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit)
- error 24 at 1 depth lookup:invalid CA certificate
-
-The first line contains the name of the certificate being verified followed by
-the subject name of the certificate. The second line contains the error number
-and the depth. The depth is number of the certificate being verified when a
-problem was detected starting with zero for the certificate being verified itself
-then 1 for the CA that signed the certificate and so on. Finally a text version
-of the error number is presented.
-
-An exhaustive list of the error codes and messages is shown below, this also
-includes the name of the error code as defined in the header file x509_vfy.h
-Some of the error codes are defined but never returned: these are described
-as "unused".
-
-=over 4
-
-=item B<0 X509_V_OK: ok>
-
-the operation was successful.
-
-=item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
-
-the issuer certificate could not be found: this occurs if the issuer certificate
-of an untrusted certificate cannot be found.
-
-=item B<3 X509_V_ERR_UNABLE_TO_GET_CRL unable to get certificate CRL>
-
-the CRL of a certificate could not be found. Unused.
-
-=item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature>
-
-the certificate signature could not be decrypted. This means that the actual signature value
-could not be determined rather than it not matching the expected value, this is only
-meaningful for RSA keys.
-
-=item B<5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature>
-
-the CRL signature could not be decrypted: this means that the actual signature value
-could not be determined rather than it not matching the expected value. Unused.
-
-=item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key>
-
-the public key in the certificate SubjectPublicKeyInfo could not be read.
-
-=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
-
-the signature of the certificate is invalid.
-
-=item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
-
-the signature of the certificate is invalid. Unused.
-
-=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
-
-the certificate is not yet valid: the notBefore date is after the current time.
-
-=item B<10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired>
-
-the certificate has expired: that is the notAfter date is before the current time.
-
-=item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
-
-the CRL is not yet valid. Unused.
-
-=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
-
-the CRL has expired. Unused.
-
-=item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
-
-the certificate notBefore field contains an invalid time.
-
-=item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field>
-
-the certificate notAfter field contains an invalid time.
-
-=item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field>
-
-the CRL lastUpdate field contains an invalid time. Unused.
-
-=item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field>
-
-the CRL nextUpdate field contains an invalid time. Unused.
-
-=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory>
-
-an error occurred trying to allocate memory. This should never happen.
-
-=item B<18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate>
-
-the passed certificate is self signed and the same certificate cannot be found in the list of
-trusted certificates.
-
-=item B<19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain>
-
-the certificate chain could be built up using the untrusted certificates but the root could not
-be found locally.
-
-=item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
-
-the issuer certificate of a locally looked up certificate could not be found. This normally means
-the list of trusted certificates is not complete.
-
-=item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
-
-no signatures could be verified because the chain contains only one certificate and it is not
-self signed.
-
-=item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
-
-the certificate chain length is greater than the supplied maximum depth. Unused.
-
-=item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked>
-
-the certificate has been revoked. Unused.
-
-=item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate>
-
-a CA certificate is invalid. Either it is not a CA or its extensions are not consistent
-with the supplied purpose.
-
-=item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
-
-the basicConstraints pathlength parameter has been exceeded.
-
-=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
-
-the supplied certificate cannot be used for the specified purpose.
-
-=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
-
-the root CA is not marked as trusted for the specified purpose.
-
-=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected>
-
-the root CA is marked to reject the specified purpose.
-
-=item B<29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
-
-the current candidate issuer certificate was rejected because its subject name
-did not match the issuer name of the current certificate. Only displayed when
-the B<-issuer_checks> option is set.
-
-=item B<30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch>
-
-the current candidate issuer certificate was rejected because its subject key
-identifier was present and did not match the authority key identifier current
-certificate. Only displayed when the B<-issuer_checks> option is set.
-
-=item B<31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch>
-
-the current candidate issuer certificate was rejected because its issuer name
-and serial number was present and did not match the authority key identifier
-of the current certificate. Only displayed when the B<-issuer_checks> option is set.
-
-=item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing>
-
-the current candidate issuer certificate was rejected because its keyUsage extension
-does not permit certificate signing.
-
-=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
-
-an application specific error. Unused.
-
-=back
-
-=head1 BUGS
-
-Although the issuer checks are a considerably improvement over the old technique they still
-suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that
-trusted certificates with matching subject name must either appear in a file (as specified by the
-B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only
-the certificates in the file will be recognised.
-
-Previous versions of OpenSSL assume certificates with matching subject name are identical and
-mishandled them.
-
-=head1 SEE ALSO
-
-L<x509(1)|x509(1)>
-
-=cut