diff options
Diffstat (limited to 'openssl/doc/apps/verify.pod')
| -rw-r--r-- | openssl/doc/apps/verify.pod | 457 |
1 files changed, 457 insertions, 0 deletions
diff --git a/openssl/doc/apps/verify.pod b/openssl/doc/apps/verify.pod new file mode 100644 index 0000000..b376732 --- /dev/null +++ b/openssl/doc/apps/verify.pod @@ -0,0 +1,457 @@ +=pod + +=head1 NAME + +verify - Utility to verify certificates. + +=head1 SYNOPSIS + +B<openssl> B<verify> +[B<-CApath directory>] +[B<-CAfile file>] +[B<-purpose purpose>] +[B<-policy arg>] +[B<-ignore_critical>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-crlfile file>] +[B<-crl_download>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-policy_check>] +[B<-explicit_policy>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-x509_strict>] +[B<-extended_crl>] +[B<-use_deltas>] +[B<-policy_print>] +[B<-no_alt_chains>] +[B<-allow_proxy_certs>] +[B<-untrusted file>] +[B<-help>] +[B<-issuer_checks>] +[B<-trusted file>] +[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<-attime timestamp> + +Perform validation checks using time specified by B<timestamp> and not +current system time. B<timestamp> is the number of seconds since +01.01.1970 (UNIX time). + +=item B<-check_ss_sig> + +Verify the signature on the self-signed root CA. This is disabled by default +because it doesn't add any security. + +=item B<-crlfile file> + +File containing one or more CRL's (in PEM format) to load. + +=item B<-crl_download> + +Attempt to download CRL information for this certificate. + +=item B<-crl_check> + +Checks end entity certificate validity by attempting to look up a valid CRL. +If a valid CRL cannot be found an error occurs. + +=item B<-untrusted file> + +A file of untrusted certificates. The file should contain multiple certificates +in PEM format concatenated together. + +=item B<-purpose purpose> + +The intended use for the certificate. If this option is not specified, +B<verify> will not consider certificate purpose during chain verification. +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> + +Print 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. The presence of rejection messages does not itself imply that +anything is wrong; during the normal verification process, several +rejections may take place. + +=item B<-policy arg> + +Enable policy processing and add B<arg> to the user-initial-policy-set (see +RFC5280). The policy B<arg> can be an object name an OID in numeric form. +This argument can appear more than once. + +=item B<-policy_check> + +Enables certificate policy processing. + +=item B<-explicit_policy> + +Set policy variable require-explicit-policy (see RFC5280). + +=item B<-inhibit_any> + +Set policy variable inhibit-any-policy (see RFC5280). + +=item B<-inhibit_map> + +Set policy variable inhibit-policy-mapping (see RFC5280). + +=item B<-no_alt_chains> + +When building a certificate chain, if the first certificate chain found is not +trusted, then OpenSSL will continue to check to see if an alternative chain can +be found that is trusted. With this option that behaviour is suppressed so that +only the first chain found is ever used. Using this option will force the +behaviour to match that of previous OpenSSL versions. + +=item B<-allow_proxy_certs> + +Allow the verification of proxy certificates. + +=item B<-trusted file> + +A file of additional trusted certificates. The file should contain multiple +certificates in PEM format concatenated together. + +=item B<-policy_print> + +Print out diagnostics related to policy processing. + +=item B<-crl_check> + +Checks end entity certificate validity by attempting to look up a valid CRL. +If a valid CRL cannot be found an error occurs. + +=item B<-crl_check_all> + +Checks the validity of B<all> certificates in the chain by attempting +to look up valid CRLs. + +=item B<-ignore_critical> + +Normally if an unhandled critical extension is present which is not +supported by OpenSSL the certificate is rejected (as required by RFC5280). +If this option is set critical extensions are ignored. + +=item B<-x509_strict> + +For strict X.509 compliance, disable non-compliant workarounds for broken +certificates. + +=item B<-extended_crl> + +Enable extended CRL features such as indirect CRLs and alternate CRL +signing keys. + +=item B<-use_deltas> + +Enable support for delta CRLs. + +=item B<-check_ss_sig> + +Verify the signature on the self-signed root CA. This is disabled by default +because it doesn't add any security. + +=item B<-> + +Indicates 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 certificates are given, B<verify> +will attempt to read a certificate from standard input. Certificates must 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 of a looked up certificate could not be found. This +normally means the list of trusted certificates is not complete. + +=item B<3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> + +the CRL of a certificate could not be found. + +=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. + +=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. + +=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> + +the CRL has expired. + +=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. + +=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. + +=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 could not be found: this occurs if the issuer +certificate of an untrusted certificate cannot be found. + +=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. + +=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 considerable 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. + +Previous versions of this documentation swapped the meaning of the +B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and +B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes. + +=head1 SEE ALSO + +L<x509(1)|x509(1)> + +=head1 HISTORY + +The -no_alt_chains options was first added to OpenSSL 1.0.2b. + +=cut |