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