verify.pod revision 306195
1=pod 2 3=head1 NAME 4 5verify - Utility to verify certificates. 6 7=head1 SYNOPSIS 8 9B<openssl> B<verify> 10[B<-CApath directory>] 11[B<-CAfile file>] 12[B<-purpose purpose>] 13[B<-policy arg>] 14[B<-ignore_critical>] 15[B<-attime timestamp>] 16[B<-check_ss_sig>] 17[B<-crlfile file>] 18[B<-crl_download>] 19[B<-crl_check>] 20[B<-crl_check_all>] 21[B<-policy_check>] 22[B<-explicit_policy>] 23[B<-inhibit_any>] 24[B<-inhibit_map>] 25[B<-x509_strict>] 26[B<-extended_crl>] 27[B<-use_deltas>] 28[B<-policy_print>] 29[B<-no_alt_chains>] 30[B<-allow_proxy_certs>] 31[B<-untrusted file>] 32[B<-help>] 33[B<-issuer_checks>] 34[B<-trusted file>] 35[B<-verbose>] 36[B<->] 37[certificates] 38 39 40=head1 DESCRIPTION 41 42The B<verify> command verifies certificate chains. 43 44=head1 COMMAND OPTIONS 45 46=over 4 47 48=item B<-CApath directory> 49 50A directory of trusted certificates. The certificates should have names 51of the form: hash.0 or have symbolic links to them of this 52form ("hash" is the hashed certificate subject name: see the B<-hash> option 53of the B<x509> utility). Under Unix the B<c_rehash> script will automatically 54create symbolic links to a directory of certificates. 55 56=item B<-CAfile file> 57A file of trusted certificates. The file should contain multiple certificates 58in PEM format concatenated together. 59 60=item B<-attime timestamp> 61 62Perform validation checks using time specified by B<timestamp> and not 63current system time. B<timestamp> is the number of seconds since 6401.01.1970 (UNIX time). 65 66=item B<-check_ss_sig> 67 68Verify the signature on the self-signed root CA. This is disabled by default 69because it doesn't add any security. 70 71=item B<-crlfile file> 72 73File containing one or more CRL's (in PEM format) to load. 74 75=item B<-crl_download> 76 77Attempt to download CRL information for this certificate. 78 79=item B<-crl_check> 80 81Checks end entity certificate validity by attempting to look up a valid CRL. 82If a valid CRL cannot be found an error occurs. 83 84=item B<-untrusted file> 85 86A file of untrusted certificates. The file should contain multiple certificates 87in PEM format concatenated together. 88 89=item B<-purpose purpose> 90 91The intended use for the certificate. If this option is not specified, 92B<verify> will not consider certificate purpose during chain verification. 93Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>, 94B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> section for more 95information. 96 97=item B<-help> 98 99Print out a usage message. 100 101=item B<-verbose> 102 103Print extra information about the operations being performed. 104 105=item B<-issuer_checks> 106 107Print out diagnostics relating to searches for the issuer certificate of the 108current certificate. This shows why each candidate issuer certificate was 109rejected. The presence of rejection messages does not itself imply that 110anything is wrong; during the normal verification process, several 111rejections may take place. 112 113=item B<-policy arg> 114 115Enable policy processing and add B<arg> to the user-initial-policy-set (see 116RFC5280). The policy B<arg> can be an object name an OID in numeric form. 117This argument can appear more than once. 118 119=item B<-policy_check> 120 121Enables certificate policy processing. 122 123=item B<-explicit_policy> 124 125Set policy variable require-explicit-policy (see RFC5280). 126 127=item B<-inhibit_any> 128 129Set policy variable inhibit-any-policy (see RFC5280). 130 131=item B<-inhibit_map> 132 133Set policy variable inhibit-policy-mapping (see RFC5280). 134 135=item B<-no_alt_chains> 136 137When building a certificate chain, if the first certificate chain found is not 138trusted, then OpenSSL will continue to check to see if an alternative chain can 139be found that is trusted. With this option that behaviour is suppressed so that 140only the first chain found is ever used. Using this option will force the 141behaviour to match that of previous OpenSSL versions. 142 143=item B<-allow_proxy_certs> 144 145Allow the verification of proxy certificates. 146 147=item B<-trusted file> 148 149A file of additional trusted certificates. The file should contain multiple 150certificates in PEM format concatenated together. 151 152=item B<-policy_print> 153 154Print out diagnostics related to policy processing. 155 156=item B<-crl_check> 157 158Checks end entity certificate validity by attempting to look up a valid CRL. 159If a valid CRL cannot be found an error occurs. 160 161=item B<-crl_check_all> 162 163Checks the validity of B<all> certificates in the chain by attempting 164to look up valid CRLs. 165 166=item B<-ignore_critical> 167 168Normally if an unhandled critical extension is present which is not 169supported by OpenSSL the certificate is rejected (as required by RFC5280). 170If this option is set critical extensions are ignored. 171 172=item B<-x509_strict> 173 174For strict X.509 compliance, disable non-compliant workarounds for broken 175certificates. 176 177=item B<-extended_crl> 178 179Enable extended CRL features such as indirect CRLs and alternate CRL 180signing keys. 181 182=item B<-use_deltas> 183 184Enable support for delta CRLs. 185 186=item B<-check_ss_sig> 187 188Verify the signature on the self-signed root CA. This is disabled by default 189because it doesn't add any security. 190 191=item B<-> 192 193Indicates the last option. All arguments following this are assumed to be 194certificate files. This is useful if the first certificate filename begins 195with a B<->. 196 197=item B<certificates> 198 199One or more certificates to verify. If no certificates are given, B<verify> 200will attempt to read a certificate from standard input. Certificates must be 201in PEM format. 202 203=back 204 205=head1 VERIFY OPERATION 206 207The B<verify> program uses the same functions as the internal SSL and S/MIME 208verification, therefore this description applies to these verify operations 209too. 210 211There is one crucial difference between the verify operations performed 212by the B<verify> program: wherever possible an attempt is made to continue 213after an error whereas normally the verify operation would halt on the 214first error. This allows all the problems with a certificate chain to be 215determined. 216 217The verify operation consists of a number of separate steps. 218 219Firstly a certificate chain is built up starting from the supplied certificate 220and ending in the root CA. It is an error if the whole chain cannot be built 221up. The chain is built up by looking up the issuers certificate of the current 222certificate. If a certificate is found which is its own issuer it is assumed 223to be the root CA. 224 225The process of 'looking up the issuers certificate' itself involves a number 226of steps. In versions of OpenSSL before 0.9.5a the first certificate whose 227subject name matched the issuer of the current certificate was assumed to be 228the issuers certificate. In OpenSSL 0.9.6 and later all certificates 229whose subject name matches the issuer name of the current certificate are 230subject to further tests. The relevant authority key identifier components 231of the current certificate (if present) must match the subject key identifier 232(if present) and issuer and serial number of the candidate issuer, in addition 233the keyUsage extension of the candidate issuer (if present) must permit 234certificate signing. 235 236The lookup first looks in the list of untrusted certificates and if no match 237is found the remaining lookups are from the trusted certificates. The root CA 238is always looked up in the trusted certificate list: if the certificate to 239verify is a root certificate then an exact match must be found in the trusted 240list. 241 242The second operation is to check every untrusted certificate's extensions for 243consistency with the supplied purpose. If the B<-purpose> option is not included 244then no checks are done. The supplied or "leaf" certificate must have extensions 245compatible with the supplied purpose and all other certificates must also be valid 246CA certificates. The precise extensions required are described in more detail in 247the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility. 248 249The third operation is to check the trust settings on the root CA. The root 250CA should be trusted for the supplied purpose. For compatibility with previous 251versions of SSLeay and OpenSSL a certificate with no trust settings is considered 252to be valid for all purposes. 253 254The final operation is to check the validity of the certificate chain. The validity 255period is checked against the current system time and the notBefore and notAfter 256dates in the certificate. The certificate signatures are also checked at this 257point. 258 259If all operations complete successfully then certificate is considered valid. If 260any operation fails then the certificate is not valid. 261 262=head1 DIAGNOSTICS 263 264When a verify operation fails the output messages can be somewhat cryptic. The 265general form of the error message is: 266 267 server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit) 268 error 24 at 1 depth lookup:invalid CA certificate 269 270The first line contains the name of the certificate being verified followed by 271the subject name of the certificate. The second line contains the error number 272and the depth. The depth is number of the certificate being verified when a 273problem was detected starting with zero for the certificate being verified itself 274then 1 for the CA that signed the certificate and so on. Finally a text version 275of the error number is presented. 276 277An exhaustive list of the error codes and messages is shown below, this also 278includes the name of the error code as defined in the header file x509_vfy.h 279Some of the error codes are defined but never returned: these are described 280as "unused". 281 282=over 4 283 284=item B<0 X509_V_OK: ok> 285 286the operation was successful. 287 288=item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> 289 290the issuer certificate of a looked up certificate could not be found. This 291normally means the list of trusted certificates is not complete. 292 293=item B<3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> 294 295the CRL of a certificate could not be found. 296 297=item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> 298 299the certificate signature could not be decrypted. This means that the actual signature value 300could not be determined rather than it not matching the expected value, this is only 301meaningful for RSA keys. 302 303=item B<5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> 304 305the CRL signature could not be decrypted: this means that the actual signature value 306could not be determined rather than it not matching the expected value. Unused. 307 308=item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> 309 310the public key in the certificate SubjectPublicKeyInfo could not be read. 311 312=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> 313 314the signature of the certificate is invalid. 315 316=item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> 317 318the signature of the certificate is invalid. 319 320=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> 321 322the certificate is not yet valid: the notBefore date is after the current time. 323 324=item B<10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> 325 326the certificate has expired: that is the notAfter date is before the current time. 327 328=item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> 329 330the CRL is not yet valid. 331 332=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> 333 334the CRL has expired. 335 336=item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> 337 338the certificate notBefore field contains an invalid time. 339 340=item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> 341 342the certificate notAfter field contains an invalid time. 343 344=item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field> 345 346the CRL lastUpdate field contains an invalid time. 347 348=item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field> 349 350the CRL nextUpdate field contains an invalid time. 351 352=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory> 353 354an error occurred trying to allocate memory. This should never happen. 355 356=item B<18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> 357 358the passed certificate is self signed and the same certificate cannot be found in the list of 359trusted certificates. 360 361=item B<19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> 362 363the certificate chain could be built up using the untrusted certificates but the root could not 364be found locally. 365 366=item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> 367 368the issuer certificate could not be found: this occurs if the issuer 369certificate of an untrusted certificate cannot be found. 370 371=item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> 372 373no signatures could be verified because the chain contains only one certificate and it is not 374self signed. 375 376=item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> 377 378the certificate chain length is greater than the supplied maximum depth. Unused. 379 380=item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked> 381 382the certificate has been revoked. 383 384=item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate> 385 386a CA certificate is invalid. Either it is not a CA or its extensions are not consistent 387with the supplied purpose. 388 389=item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> 390 391the basicConstraints pathlength parameter has been exceeded. 392 393=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> 394 395the supplied certificate cannot be used for the specified purpose. 396 397=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> 398 399the root CA is not marked as trusted for the specified purpose. 400 401=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected> 402 403the root CA is marked to reject the specified purpose. 404 405=item B<29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> 406 407the current candidate issuer certificate was rejected because its subject name 408did not match the issuer name of the current certificate. Only displayed when 409the B<-issuer_checks> option is set. 410 411=item B<30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch> 412 413the current candidate issuer certificate was rejected because its subject key 414identifier was present and did not match the authority key identifier current 415certificate. Only displayed when the B<-issuer_checks> option is set. 416 417=item B<31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch> 418 419the current candidate issuer certificate was rejected because its issuer name 420and serial number was present and did not match the authority key identifier 421of the current certificate. Only displayed when the B<-issuer_checks> option is set. 422 423=item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing> 424 425the current candidate issuer certificate was rejected because its keyUsage extension 426does not permit certificate signing. 427 428=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> 429 430an application specific error. Unused. 431 432=back 433 434=head1 BUGS 435 436Although the issuer checks are a considerable improvement over the old technique they still 437suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that 438trusted certificates with matching subject name must either appear in a file (as specified by the 439B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only 440the certificates in the file will be recognised. 441 442Previous versions of OpenSSL assume certificates with matching subject name are identical and 443mishandled them. 444 445Previous versions of this documentation swapped the meaning of the 446B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and 447B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes. 448 449=head1 SEE ALSO 450 451L<x509(1)|x509(1)> 452 453=head1 HISTORY 454 455The -no_alt_chains options was first added to OpenSSL 1.0.2b. 456 457=cut 458