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