crypto/openssl/doc/apps/verify.pod

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