| =pod |
| |
| =head1 NAME |
| |
| verify - Utility to verify certificates. |
| |
| =head1 SYNOPSIS |
| |
| B<openssl> B<verify> |
| [B<-CAfile file>] |
| [B<-CApath directory>] |
| [B<-attime timestamp>] |
| [B<-check_ss_sig>] |
| [B<-crlfile file>] |
| [B<-crl_check>] |
| [B<-crl_check_all>] |
| [B<-explicit_policy>] |
| [B<-extended_crl>] |
| [B<-help>] |
| [B<-ignore_critical>] |
| [B<-inhibit_any>] |
| [B<-inhibit_map>] |
| [B<-issuer_checks>] |
| [B<-partial_chain>] |
| [B<-policy arg>] |
| [B<-policy_check>] |
| [B<-policy_print>] |
| [B<-purpose purpose>] |
| [B<-suiteB_128>] |
| [B<-suiteB_128_only>] |
| [B<-suiteB_192>] |
| [B<-trusted_first>] |
| [B<-untrusted file>] |
| [B<-use_deltas>] |
| [B<-verbose>] |
| [B<-verify_depth num>] |
| [B<-verify_email email>] |
| [B<-verify_hostname hostname>] |
| [B<-verify_ip ip>] |
| [B<-verify_name name>] |
| [B<-x509_strict>] |
| [B<->] |
| [certificates] |
| |
| |
| =head1 DESCRIPTION |
| |
| The B<verify> command verifies certificate chains. |
| |
| =head1 COMMAND OPTIONS |
| |
| =over 4 |
| |
| =item B<-CAfile file> |
| |
| A file of trusted certificates. The file should contain multiple certificates |
| in PEM format concatenated together. |
| |
| =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<-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_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<-explicit_policy> |
| |
| Set policy variable require-explicit-policy (see RFC5280). |
| |
| =item B<-extended_crl> |
| |
| Enable extended CRL features such as indirect CRLs and alternate CRL |
| signing keys. |
| |
| =item B<-help> |
| |
| Print out a usage message. |
| |
| =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<-inhibit_any> |
| |
| Set policy variable inhibit-any-policy (see RFC5280). |
| |
| =item B<-inhibit_map> |
| |
| Set policy variable inhibit-policy-mapping (see RFC5280). |
| |
| =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<-partial_chain> |
| |
| Allow partial certificate chain if at least one certificate is in trusted store. |
| |
| =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<-policy_print> |
| |
| Print out diagnostics related to policy processing. |
| |
| =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<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192> |
| |
| enable the Suite B mode operation at 128 bit Level of Security, 128 bit or |
| 192 bit, or only 192 bit Level of Security respectively. |
| See RFC6460 for details. In particular the supported signature algorithms are |
| reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves |
| P-256 and P-384. |
| |
| =item B<-trusted_first> |
| |
| Use certificates in CA file or CA directory before certificates in untrusted |
| file when building the trust chain to verify certificates. |
| This is mainly useful in environments with Bridge CA or Cross-Certified CAs. |
| |
| =item B<-untrusted file> |
| |
| A file of untrusted certificates. The file should contain multiple certificates |
| in PEM format concatenated together. |
| |
| =item B<-use_deltas> |
| |
| Enable support for delta CRLs. |
| |
| =item B<-verbose> |
| |
| Print extra information about the operations being performed. |
| |
| =item B<-verify_depth num> |
| |
| Limit the maximum depth of the certificate chain to B<num> certificates. |
| |
| =item B<-verify_email email> |
| |
| Verify if the B<email> matches the email address in Subject Alternative Name or |
| the email in the subject Distinguished Name. |
| |
| =item B<-verify_hostname hostname> |
| |
| Verify if the B<hostname> matches DNS name in Subject Alternative Name or |
| Common Name in the subject certificate. |
| |
| =item B<-verify_ip ip> |
| |
| Verify if the B<ip> matches the IP address in Subject Alternative Name of |
| the subject certificate. |
| |
| =item B<-verify_name name> |
| |
| Use default verification options like trust model and required certificate |
| policies identified by B<name>. |
| Supported usages include: default, pkcs7, smime_sign, ssl_client, ssl_server. |
| |
| =item B<-x509_strict> |
| |
| For strict X.509 compliance, disable non-compliant workarounds for broken |
| certificates. |
| |
| =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)> |
| |
| =cut |
