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