159191Skris=pod 259191Skris 359191Skris=head1 NAME 459191Skris 5325337Sjkimopenssl-verify, 668651Skrisverify - Utility to verify certificates. 759191Skris 859191Skris=head1 SYNOPSIS 959191Skris 1059191SkrisB<openssl> B<verify> 1159191Skris[B<-CApath directory>] 1259191Skris[B<-CAfile file>] 1359191Skris[B<-purpose purpose>] 14238405Sjkim[B<-policy arg>] 15238405Sjkim[B<-ignore_critical>] 16290207Sjkim[B<-attime timestamp>] 17290207Sjkim[B<-check_ss_sig>] 18331638Sjkim[B<-CRLfile file>] 19290207Sjkim[B<-crl_download>] 20238405Sjkim[B<-crl_check>] 21238405Sjkim[B<-crl_check_all>] 22238405Sjkim[B<-policy_check>] 23238405Sjkim[B<-explicit_policy>] 24238405Sjkim[B<-inhibit_any>] 25238405Sjkim[B<-inhibit_map>] 26238405Sjkim[B<-x509_strict>] 27238405Sjkim[B<-extended_crl>] 28238405Sjkim[B<-use_deltas>] 29238405Sjkim[B<-policy_print>] 30284283Sjkim[B<-no_alt_chains>] 31306195Sjkim[B<-allow_proxy_certs>] 3259191Skris[B<-untrusted file>] 3359191Skris[B<-help>] 3468651Skris[B<-issuer_checks>] 35290207Sjkim[B<-trusted file>] 3659191Skris[B<-verbose>] 3759191Skris[B<->] 3859191Skris[certificates] 3959191Skris 4059191Skris 4159191Skris=head1 DESCRIPTION 4259191Skris 4359191SkrisThe B<verify> command verifies certificate chains. 4459191Skris 4559191Skris=head1 COMMAND OPTIONS 4659191Skris 4759191Skris=over 4 4859191Skris 4959191Skris=item B<-CApath directory> 5059191Skris 5159191SkrisA directory of trusted certificates. The certificates should have names 5259191Skrisof the form: hash.0 or have symbolic links to them of this 5359191Skrisform ("hash" is the hashed certificate subject name: see the B<-hash> option 5459191Skrisof the B<x509> utility). Under Unix the B<c_rehash> script will automatically 5559191Skriscreate symbolic links to a directory of certificates. 5659191Skris 5759191Skris=item B<-CAfile file> 5859191SkrisA file of trusted certificates. The file should contain multiple certificates 5959191Skrisin PEM format concatenated together. 6059191Skris 61290207Sjkim=item B<-attime timestamp> 62290207Sjkim 63290207SjkimPerform validation checks using time specified by B<timestamp> and not 64290207Sjkimcurrent system time. B<timestamp> is the number of seconds since 65290207Sjkim01.01.1970 (UNIX time). 66290207Sjkim 67290207Sjkim=item B<-check_ss_sig> 68290207Sjkim 69290207SjkimVerify the signature on the self-signed root CA. This is disabled by default 70290207Sjkimbecause it doesn't add any security. 71290207Sjkim 72331638Sjkim=item B<-CRLfile file> 73290207Sjkim 74290207SjkimFile containing one or more CRL's (in PEM format) to load. 75290207Sjkim 76290207Sjkim=item B<-crl_download> 77290207Sjkim 78290207SjkimAttempt to download CRL information for this certificate. 79290207Sjkim 80290207Sjkim=item B<-crl_check> 81290207Sjkim 82290207SjkimChecks end entity certificate validity by attempting to look up a valid CRL. 83290207SjkimIf a valid CRL cannot be found an error occurs. 84290207Sjkim 8559191Skris=item B<-untrusted file> 8659191Skris 8759191SkrisA file of untrusted certificates. The file should contain multiple certificates 88246772Sjkimin PEM format concatenated together. 8959191Skris 9059191Skris=item B<-purpose purpose> 9159191Skris 92246772SjkimThe intended use for the certificate. If this option is not specified, 93246772SjkimB<verify> will not consider certificate purpose during chain verification. 94246772SjkimCurrently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>, 95246772SjkimB<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> section for more 96246772Sjkiminformation. 9759191Skris 9859191Skris=item B<-help> 9959191Skris 100246772SjkimPrint out a usage message. 10159191Skris 10259191Skris=item B<-verbose> 10359191Skris 104246772SjkimPrint extra information about the operations being performed. 10559191Skris 10668651Skris=item B<-issuer_checks> 10768651Skris 108246772SjkimPrint out diagnostics relating to searches for the issuer certificate of the 109246772Sjkimcurrent certificate. This shows why each candidate issuer certificate was 110246772Sjkimrejected. The presence of rejection messages does not itself imply that 111246772Sjkimanything is wrong; during the normal verification process, several 112246772Sjkimrejections may take place. 11368651Skris 114238405Sjkim=item B<-policy arg> 115238405Sjkim 116246772SjkimEnable policy processing and add B<arg> to the user-initial-policy-set (see 117246772SjkimRFC5280). The policy B<arg> can be an object name an OID in numeric form. 118246772SjkimThis argument can appear more than once. 119238405Sjkim 120238405Sjkim=item B<-policy_check> 121238405Sjkim 122238405SjkimEnables certificate policy processing. 123238405Sjkim 124238405Sjkim=item B<-explicit_policy> 125238405Sjkim 126246772SjkimSet policy variable require-explicit-policy (see RFC5280). 127238405Sjkim 128238405Sjkim=item B<-inhibit_any> 129238405Sjkim 130246772SjkimSet policy variable inhibit-any-policy (see RFC5280). 131238405Sjkim 132238405Sjkim=item B<-inhibit_map> 133238405Sjkim 134246772SjkimSet policy variable inhibit-policy-mapping (see RFC5280). 135238405Sjkim 136284283Sjkim=item B<-no_alt_chains> 137284283Sjkim 138284283SjkimWhen building a certificate chain, if the first certificate chain found is not 139284283Sjkimtrusted, then OpenSSL will continue to check to see if an alternative chain can 140284283Sjkimbe found that is trusted. With this option that behaviour is suppressed so that 141284283Sjkimonly the first chain found is ever used. Using this option will force the 142284283Sjkimbehaviour to match that of previous OpenSSL versions. 143284283Sjkim 144306195Sjkim=item B<-allow_proxy_certs> 145306195Sjkim 146306195SjkimAllow the verification of proxy certificates. 147306195Sjkim 148290207Sjkim=item B<-trusted file> 149290207Sjkim 150290207SjkimA file of additional trusted certificates. The file should contain multiple 151290207Sjkimcertificates in PEM format concatenated together. 152290207Sjkim 153238405Sjkim=item B<-policy_print> 154238405Sjkim 155246772SjkimPrint out diagnostics related to policy processing. 156238405Sjkim 157238405Sjkim=item B<-crl_check> 158238405Sjkim 159246772SjkimChecks end entity certificate validity by attempting to look up a valid CRL. 160238405SjkimIf a valid CRL cannot be found an error occurs. 161238405Sjkim 162238405Sjkim=item B<-crl_check_all> 163238405Sjkim 164238405SjkimChecks the validity of B<all> certificates in the chain by attempting 165246772Sjkimto look up valid CRLs. 166238405Sjkim 167238405Sjkim=item B<-ignore_critical> 168238405Sjkim 169238405SjkimNormally if an unhandled critical extension is present which is not 170246772Sjkimsupported by OpenSSL the certificate is rejected (as required by RFC5280). 171246772SjkimIf this option is set critical extensions are ignored. 172238405Sjkim 173238405Sjkim=item B<-x509_strict> 174238405Sjkim 175246772SjkimFor strict X.509 compliance, disable non-compliant workarounds for broken 176246772Sjkimcertificates. 177238405Sjkim 178238405Sjkim=item B<-extended_crl> 179238405Sjkim 180238405SjkimEnable extended CRL features such as indirect CRLs and alternate CRL 181238405Sjkimsigning keys. 182238405Sjkim 183238405Sjkim=item B<-use_deltas> 184238405Sjkim 185238405SjkimEnable support for delta CRLs. 186238405Sjkim 187205128Ssimon=item B<-check_ss_sig> 188205128Ssimon 189205128SsimonVerify the signature on the self-signed root CA. This is disabled by default 190205128Ssimonbecause it doesn't add any security. 191205128Ssimon 19259191Skris=item B<-> 19359191Skris 194246772SjkimIndicates the last option. All arguments following this are assumed to be 19559191Skriscertificate files. This is useful if the first certificate filename begins 19659191Skriswith a B<->. 19759191Skris 19859191Skris=item B<certificates> 19959191Skris 200246772SjkimOne or more certificates to verify. If no certificates are given, B<verify> 201246772Sjkimwill attempt to read a certificate from standard input. Certificates must be 202246772Sjkimin PEM format. 20359191Skris 20459191Skris=back 20559191Skris 20659191Skris=head1 VERIFY OPERATION 20759191Skris 20859191SkrisThe B<verify> program uses the same functions as the internal SSL and S/MIME 20959191Skrisverification, therefore this description applies to these verify operations 21059191Skristoo. 21159191Skris 21259191SkrisThere is one crucial difference between the verify operations performed 21359191Skrisby the B<verify> program: wherever possible an attempt is made to continue 21459191Skrisafter an error whereas normally the verify operation would halt on the 21559191Skrisfirst error. This allows all the problems with a certificate chain to be 21659191Skrisdetermined. 21759191Skris 21859191SkrisThe verify operation consists of a number of separate steps. 21959191Skris 22059191SkrisFirstly a certificate chain is built up starting from the supplied certificate 22159191Skrisand ending in the root CA. It is an error if the whole chain cannot be built 22268651Skrisup. The chain is built up by looking up the issuers certificate of the current 22368651Skriscertificate. If a certificate is found which is its own issuer it is assumed 22468651Skristo be the root CA. 22568651Skris 22668651SkrisThe process of 'looking up the issuers certificate' itself involves a number 22768651Skrisof steps. In versions of OpenSSL before 0.9.5a the first certificate whose 22868651Skrissubject name matched the issuer of the current certificate was assumed to be 22968651Skristhe issuers certificate. In OpenSSL 0.9.6 and later all certificates 23068651Skriswhose subject name matches the issuer name of the current certificate are 23168651Skrissubject to further tests. The relevant authority key identifier components 23268651Skrisof the current certificate (if present) must match the subject key identifier 23368651Skris(if present) and issuer and serial number of the candidate issuer, in addition 23468651Skristhe keyUsage extension of the candidate issuer (if present) must permit 23568651Skriscertificate signing. 23668651Skris 23759191SkrisThe lookup first looks in the list of untrusted certificates and if no match 23859191Skrisis found the remaining lookups are from the trusted certificates. The root CA 23959191Skrisis always looked up in the trusted certificate list: if the certificate to 24059191Skrisverify is a root certificate then an exact match must be found in the trusted 24159191Skrislist. 24259191Skris 24359191SkrisThe second operation is to check every untrusted certificate's extensions for 24459191Skrisconsistency with the supplied purpose. If the B<-purpose> option is not included 24559191Skristhen no checks are done. The supplied or "leaf" certificate must have extensions 24659191Skriscompatible with the supplied purpose and all other certificates must also be valid 24759191SkrisCA certificates. The precise extensions required are described in more detail in 24859191Skristhe B<CERTIFICATE EXTENSIONS> section of the B<x509> utility. 24959191Skris 25059191SkrisThe third operation is to check the trust settings on the root CA. The root 25159191SkrisCA should be trusted for the supplied purpose. For compatibility with previous 25259191Skrisversions of SSLeay and OpenSSL a certificate with no trust settings is considered 25359191Skristo be valid for all purposes. 25459191Skris 25559191SkrisThe final operation is to check the validity of the certificate chain. The validity 25659191Skrisperiod is checked against the current system time and the notBefore and notAfter 25759191Skrisdates in the certificate. The certificate signatures are also checked at this 25859191Skrispoint. 25959191Skris 26059191SkrisIf all operations complete successfully then certificate is considered valid. If 26159191Skrisany operation fails then the certificate is not valid. 26259191Skris 26359191Skris=head1 DIAGNOSTICS 26459191Skris 26559191SkrisWhen a verify operation fails the output messages can be somewhat cryptic. The 26659191Skrisgeneral form of the error message is: 26759191Skris 26859191Skris server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit) 26959191Skris error 24 at 1 depth lookup:invalid CA certificate 27059191Skris 27159191SkrisThe first line contains the name of the certificate being verified followed by 27259191Skristhe subject name of the certificate. The second line contains the error number 27359191Skrisand the depth. The depth is number of the certificate being verified when a 27459191Skrisproblem was detected starting with zero for the certificate being verified itself 27559191Skristhen 1 for the CA that signed the certificate and so on. Finally a text version 27659191Skrisof the error number is presented. 27759191Skris 27859191SkrisAn exhaustive list of the error codes and messages is shown below, this also 27959191Skrisincludes the name of the error code as defined in the header file x509_vfy.h 28059191SkrisSome of the error codes are defined but never returned: these are described 28159191Skrisas "unused". 28259191Skris 28359191Skris=over 4 28459191Skris 28559191Skris=item B<0 X509_V_OK: ok> 28659191Skris 28759191Skristhe operation was successful. 28859191Skris 28959191Skris=item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> 29059191Skris 291205128Ssimonthe issuer certificate of a looked up certificate could not be found. This 292205128Ssimonnormally means the list of trusted certificates is not complete. 29359191Skris 294194206Ssimon=item B<3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> 29559191Skris 296238405Sjkimthe CRL of a certificate could not be found. 29759191Skris 29859191Skris=item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> 29959191Skris 30059191Skristhe certificate signature could not be decrypted. This means that the actual signature value 30159191Skriscould not be determined rather than it not matching the expected value, this is only 30259191Skrismeaningful for RSA keys. 30359191Skris 30459191Skris=item B<5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> 30559191Skris 30659191Skristhe CRL signature could not be decrypted: this means that the actual signature value 30759191Skriscould not be determined rather than it not matching the expected value. Unused. 30859191Skris 30959191Skris=item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> 31059191Skris 31159191Skristhe public key in the certificate SubjectPublicKeyInfo could not be read. 31259191Skris 31359191Skris=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> 31459191Skris 31559191Skristhe signature of the certificate is invalid. 31659191Skris 31759191Skris=item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> 31859191Skris 319238405Sjkimthe signature of the certificate is invalid. 32059191Skris 32159191Skris=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> 32259191Skris 32359191Skristhe certificate is not yet valid: the notBefore date is after the current time. 32459191Skris 32589837Skris=item B<10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> 32659191Skris 32789837Skristhe certificate has expired: that is the notAfter date is before the current time. 32859191Skris 32989837Skris=item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> 33059191Skris 331238405Sjkimthe CRL is not yet valid. 33259191Skris 33359191Skris=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> 33459191Skris 335238405Sjkimthe CRL has expired. 33659191Skris 33759191Skris=item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> 33859191Skris 33959191Skristhe certificate notBefore field contains an invalid time. 34059191Skris 34159191Skris=item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> 34259191Skris 34359191Skristhe certificate notAfter field contains an invalid time. 34459191Skris 34559191Skris=item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field> 34659191Skris 347238405Sjkimthe CRL lastUpdate field contains an invalid time. 34859191Skris 34959191Skris=item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field> 35059191Skris 351238405Sjkimthe CRL nextUpdate field contains an invalid time. 35259191Skris 35359191Skris=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory> 35459191Skris 35559191Skrisan error occurred trying to allocate memory. This should never happen. 35659191Skris 35759191Skris=item B<18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> 35859191Skris 35959191Skristhe passed certificate is self signed and the same certificate cannot be found in the list of 36059191Skristrusted certificates. 36159191Skris 36259191Skris=item B<19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> 36359191Skris 36459191Skristhe certificate chain could be built up using the untrusted certificates but the root could not 36559191Skrisbe found locally. 36659191Skris 36759191Skris=item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> 36859191Skris 369205128Ssimonthe issuer certificate could not be found: this occurs if the issuer 370205128Ssimoncertificate of an untrusted certificate cannot be found. 37159191Skris 37259191Skris=item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> 37359191Skris 37459191Skrisno signatures could be verified because the chain contains only one certificate and it is not 37559191Skrisself signed. 37659191Skris 37759191Skris=item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> 37859191Skris 37959191Skristhe certificate chain length is greater than the supplied maximum depth. Unused. 38059191Skris 38159191Skris=item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked> 38259191Skris 383238405Sjkimthe certificate has been revoked. 38459191Skris 38559191Skris=item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate> 38659191Skris 38759191Skrisa CA certificate is invalid. Either it is not a CA or its extensions are not consistent 38859191Skriswith the supplied purpose. 38959191Skris 39059191Skris=item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> 39159191Skris 39259191Skristhe basicConstraints pathlength parameter has been exceeded. 39359191Skris 39459191Skris=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> 39559191Skris 39659191Skristhe supplied certificate cannot be used for the specified purpose. 39759191Skris 39859191Skris=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> 39959191Skris 40059191Skristhe root CA is not marked as trusted for the specified purpose. 40159191Skris 40259191Skris=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected> 40359191Skris 40459191Skristhe root CA is marked to reject the specified purpose. 40559191Skris 40668651Skris=item B<29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> 40768651Skris 40868651Skristhe current candidate issuer certificate was rejected because its subject name 40968651Skrisdid not match the issuer name of the current certificate. Only displayed when 41068651Skristhe B<-issuer_checks> option is set. 41168651Skris 41268651Skris=item B<30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch> 41368651Skris 41468651Skristhe current candidate issuer certificate was rejected because its subject key 41568651Skrisidentifier was present and did not match the authority key identifier current 41668651Skriscertificate. Only displayed when the B<-issuer_checks> option is set. 41768651Skris 41868651Skris=item B<31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch> 41968651Skris 42068651Skristhe current candidate issuer certificate was rejected because its issuer name 42168651Skrisand serial number was present and did not match the authority key identifier 42268651Skrisof the current certificate. Only displayed when the B<-issuer_checks> option is set. 42368651Skris 42468651Skris=item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing> 42568651Skris 42668651Skristhe current candidate issuer certificate was rejected because its keyUsage extension 42768651Skrisdoes not permit certificate signing. 42868651Skris 42959191Skris=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> 43059191Skris 43159191Skrisan application specific error. Unused. 43259191Skris 43359191Skris=back 43459191Skris 43568651Skris=head1 BUGS 43668651Skris 437267256SjkimAlthough the issuer checks are a considerable improvement over the old technique they still 43868651Skrissuffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that 43968651Skristrusted certificates with matching subject name must either appear in a file (as specified by the 44068651SkrisB<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only 44168651Skristhe certificates in the file will be recognised. 44268651Skris 44368651SkrisPrevious versions of OpenSSL assume certificates with matching subject name are identical and 44468651Skrismishandled them. 44568651Skris 446205128SsimonPrevious versions of this documentation swapped the meaning of the 447205128SsimonB<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and 448205128SsimonB<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes. 449205128Ssimon 45059191Skris=head1 SEE ALSO 45159191Skris 45259191SkrisL<x509(1)|x509(1)> 45359191Skris 454284283Sjkim=head1 HISTORY 455284283Sjkim 456290207SjkimThe -no_alt_chains options was first added to OpenSSL 1.0.2b. 457284283Sjkim 45859191Skris=cut 459