doc/man3/X509_STORE_CTX_get_error.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509_STORE_CTX_get_error, X509_STORE_CTX_set_error,
   6 X509_STORE_CTX_get_error_depth, X509_STORE_CTX_set_error_depth,
   7 X509_STORE_CTX_get_current_cert, X509_STORE_CTX_set_current_cert,
   8 X509_STORE_CTX_get0_cert, X509_STORE_CTX_get1_chain,
   9 X509_verify_cert_error_string - get or set certificate verification status
  10 information
  11
  12 =head1 SYNOPSIS
  13
  14  #include <openssl/x509.h>
  15
  16  int   X509_STORE_CTX_get_error(const X509_STORE_CTX *ctx);
  17  void  X509_STORE_CTX_set_error(X509_STORE_CTX *ctx, int s);
  18  int   X509_STORE_CTX_get_error_depth(const X509_STORE_CTX *ctx);
  19  void  X509_STORE_CTX_set_error_depth(X509_STORE_CTX *ctx, int depth);
  20  X509 *X509_STORE_CTX_get_current_cert(const X509_STORE_CTX *ctx);
  21  void  X509_STORE_CTX_set_current_cert(X509_STORE_CTX *ctx, X509 *x);
  22  X509 *X509_STORE_CTX_get0_cert(const X509_STORE_CTX *ctx);
  23
  24  STACK_OF(X509) *X509_STORE_CTX_get1_chain(const X509_STORE_CTX *ctx);
  25
  26  const char *X509_verify_cert_error_string(long n);
  27
  28 =head1 DESCRIPTION
  29
  30 These functions are typically called after X509_verify_cert() has indicated
  31 an error or in a verification callback to determine the nature of an error.
  32
  33 X509_STORE_CTX_get_error() returns the error code of B<ctx>, see
  34 the B<ERROR CODES> section for a full description of all error codes.
  35
  36 X509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. For example
  37 it might be used in a verification callback to set an error based on additional
  38 checks.
  39
  40 X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a
  41 nonnegative integer representing where in the certificate chain the error
  42 occurred. If it is zero it occurred in the end entity certificate, one if
  43 it is the certificate which signed the end entity certificate and so on.
  44
  45 X509_STORE_CTX_set_error_depth() sets the error B<depth>.
  46 This can be used in combination with X509_STORE_CTX_set_error() to set the
  47 depth at which an error condition was detected.
  48
  49 X509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which
  50 caused the error or B<NULL> if no certificate is relevant.
  51
  52 X509_STORE_CTX_set_current_cert() sets the certificate B<x> in B<ctx> which
  53 caused the error.
  54 This value is not intended to remain valid for very long, and remains owned by
  55 the caller.
  56 It may be examined by a verification callback invoked to handle each error
  57 encountered during chain verification and is no longer required after such a
  58 callback.
  59 If a callback wishes the save the certificate for use after it returns, it
  60 needs to increment its reference count via L<X509_up_ref(3)>.
  61 Once such a I<saved> certificate is no longer needed it can be freed with
  62 L<X509_free(3)>.
  63
  64 X509_STORE_CTX_get0_cert() retrieves an internal pointer to the
  65 certificate being verified by the B<ctx>.
  66
  67 X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous
  68 call to X509_verify_cert() is successful. If the call to X509_verify_cert()
  69 is B<not> successful the returned chain may be incomplete or invalid. The
  70 returned chain persists after the B<ctx> structure is freed, when it is
  71 no longer needed it should be free up using:
  72
  73  sk_X509_pop_free(chain, X509_free);
  74
  75 X509_verify_cert_error_string() returns a human readable error string for
  76 verification error B<n>.
  77
  78 =head1 RETURN VALUES
  79
  80 X509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code.
  81
  82 X509_STORE_CTX_get_error_depth() returns a nonnegative error depth.
  83
  84 X509_STORE_CTX_get_current_cert() returns the certificate which caused the
  85 error or B<NULL> if no certificate is relevant to the error.
  86
  87 X509_verify_cert_error_string() returns a human readable error string for
  88 verification error B<n>.
  89
  90 =head1 ERROR CODES
  91
  92 A list of error codes and messages is shown below.  Some of the
  93 error codes are defined but currently never returned: these are described as
  94 "unused".
  95
  96 =over 4
  97
  98 =item B<X509_V_OK: ok>
  99
 100 The operation was successful.
 101
 102 =item B<X509_V_ERR_UNSPECIFIED: unspecified certificate verification error>
 103
 104 Unspecified error; should not happen.
 105
 106 =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
 107
 108 The issuer certificate of a locally looked up certificate could not be found.
 109 This normally means the list of trusted certificates is not complete.
 110 To allow any certificate (not only a self-signed one) in the trust store
 111 to terminate the chain the B<X509_V_FLAG_PARTIAL_CHAIN> flag may be set.
 112
 113 =item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
 114
 115 The CRL of a certificate could not be found.
 116
 117 =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE:
 118 unable to decrypt certificate's signature>
 119
 120 The certificate signature could not be decrypted. This means that the actual
 121 signature value could not be determined rather than it not matching the
 122 expected value, this is only meaningful for RSA keys.
 123
 124 =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE:
 125 unable to decrypt CRL's signature>
 126
 127 The CRL signature could not be decrypted: this means that the actual signature
 128 value could not be determined rather than it not matching the expected value.
 129 Unused.
 130
 131 =item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY:
 132 unable to decode issuer public key>
 133
 134 The public key in the certificate C<SubjectPublicKeyInfo> field could
 135 not be read.
 136
 137 =item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
 138
 139 The signature of the certificate is invalid.
 140
 141 =item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
 142
 143 The signature of the certificate is invalid.
 144
 145 =item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
 146
 147 The certificate is not yet valid: the C<notBefore> date is after the
 148 current time.
 149
 150 =item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired>
 151
 152 The certificate has expired: that is the C<notAfter> date is before the
 153 current time.
 154
 155 =item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
 156
 157 The CRL is not yet valid.
 158
 159 =item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
 160
 161 The CRL has expired.
 162
 163 =item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD:
 164 format error in certificate's notBefore field>
 165
 166 The certificate B<notBefore> field contains an invalid time.
 167
 168 =item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD:
 169 format error in certificate's notAfter field>
 170
 171 The certificate B<notAfter> field contains an invalid time.
 172
 173 =item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD:
 174 format error in CRL's lastUpdate field>
 175
 176 The CRL B<lastUpdate> field contains an invalid time.
 177
 178 =item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD:
 179 format error in CRL's nextUpdate field>
 180
 181 The CRL B<nextUpdate> field contains an invalid time.
 182
 183 =item B<X509_V_ERR_OUT_OF_MEM: out of memory>
 184
 185 An error occurred trying to allocate memory.
 186
 187 =item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self-signed certificate>
 188
 189 The passed certificate is self-signed and the same certificate cannot be found
 190 in the list of trusted certificates.
 191
 192 =item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN:
 193 self-signed certificate in certificate chain>
 194
 195 The certificate chain could be built up using the untrusted certificates
 196 but no suitable trust anchor (which typically is a self-signed root certificate)
 197 could be found in the trust store.
 198
 199 =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY:
 200 unable to get local issuer certificate>
 201
 202 The issuer certificate could not be found: this occurs if the issuer certificate
 203 of an untrusted certificate cannot be found.
 204
 205 =item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE:
 206 unable to verify the first certificate>
 207
 208 No signatures could be verified because the chain contains only one certificate
 209 and it is not self-signed and the B<X509_V_FLAG_PARTIAL_CHAIN> flag is not set.
 210
 211 =item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
 212
 213 The certificate chain length is greater than the supplied maximum depth. Unused.
 214
 215 =item B<X509_V_ERR_CERT_REVOKED: certificate revoked>
 216
 217 The certificate has been revoked.
 218
 219 =item B<X509_V_ERR_INVALID_CA: invalid CA certificate>
 220
 221 A CA certificate is invalid. Either it is not a CA or its extensions are not
 222 consistent with the supplied purpose.
 223
 224 =item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
 225
 226 The basicConstraints path-length parameter has been exceeded.
 227
 228 =item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
 229
 230 The target certificate cannot be used for the specified purpose.
 231
 232 =item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
 233
 234 The root CA is not marked as trusted for the specified purpose.
 235
 236 =item B<X509_V_ERR_CERT_REJECTED: certificate rejected>
 237
 238 The root CA is marked to reject the specified purpose.
 239
 240 =item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
 241
 242 The current candidate issuer certificate was rejected because its subject name
 243 did not match the issuer name of the current certificate.
 244
 245 =item B<X509_V_ERR_AKID_SKID_MISMATCH:
 246 authority and subject key identifier mismatch>
 247
 248 The current candidate issuer certificate was rejected because its subject key
 249 identifier was present and did not match the authority key identifier current
 250 certificate.
 251 Not used as of OpenSSL 1.1.0.
 252
 253 =item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH:
 254 authority and issuer serial number mismatch>
 255
 256 The current candidate issuer certificate was rejected because its issuer name
 257 and serial number was present and did not match the authority key identifier of
 258 the current certificate.
 259 Not used as of OpenSSL 1.1.0.
 260
 261 =item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:
 262 key usage does not include certificate signing>
 263
 264 The current candidate issuer certificate was rejected because its B<keyUsage>
 265 extension does not permit certificate signing.
 266 Not used as of OpenSSL 1.1.0.
 267
 268 =item B<X509_V_ERR_INVALID_EXTENSION:
 269 invalid or inconsistent certificate extension>
 270
 271 A certificate extension had an invalid value (for example an incorrect
 272 encoding) or some value inconsistent with other extensions.
 273
 274 =item B<X509_V_ERR_INVALID_POLICY_EXTENSION:
 275 invalid or inconsistent certificate policy extension>
 276
 277 A certificate policies extension had an invalid value (for example an incorrect
 278 encoding) or some value inconsistent with other extensions. This error only
 279 occurs if policy processing is enabled.
 280
 281 =item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy>
 282
 283 The verification flags were set to require and explicit policy but none was
 284 present.
 285
 286 =item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: different CRL scope>
 287
 288 The only CRLs that could be found did not match the scope of the certificate.
 289
 290 =item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature>
 291
 292 Some feature of a certificate extension is not supported. Unused.
 293
 294 =item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation>
 295
 296 A name constraint violation occurred in the permitted subtrees.
 297
 298 =item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation>
 299
 300 A name constraint violation occurred in the excluded subtrees.
 301
 302 =item B<X509_V_ERR_SUBTREE_MINMAX:
 303 name constraints minimum and maximum not supported>
 304
 305 A certificate name constraints extension included a minimum or maximum field:
 306 this is not supported.
 307
 308 =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE:
 309 unsupported name constraint type>
 310
 311 An unsupported name constraint type was encountered. OpenSSL currently only
 312 supports directory name, DNS name, email and URI types.
 313
 314 =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX:
 315 unsupported or invalid name constraint syntax>
 316
 317 The format of the name constraint is not recognised: for example an email
 318 address format of a form not mentioned in RFC3280. This could be caused by
 319 a garbage extension or some new feature not currently supported.
 320
 321 =item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error>
 322
 323 An error occurred when attempting to verify the CRL path. This error can only
 324 happen if extended CRL checking is enabled.
 325
 326 =item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
 327
 328 An application specific error. This will never be returned unless explicitly
 329 set by an application callback.
 330
 331 =item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER: unable to get CRL issuer certificate>
 332
 333 Unable to get CRL issuer certificate.
 334
 335 =item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION: unhandled critical extension>
 336
 337 Unhandled critical extension.
 338
 339 =item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN: key usage does not include CRL signing>
 340
 341 Key usage does not include CRL signing.
 342
 343 =item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION: unhandled critical CRL extension>
 344
 345 Unhandled critical CRL extension.
 346
 347 =item B<X509_V_ERR_INVALID_NON_CA: invalid non-CA certificate (has CA markings)>
 348
 349 Invalid non-CA certificate has CA markings.
 350
 351 =item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED: proxy path length constraint exceeded>
 352
 353 Proxy path length constraint exceeded.
 354
 355 =item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE: key usage does not include digital signature>
 356
 357 Key usage does not include digital signature, and therefore cannot sign
 358 certificates.
 359
 360 =item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED: proxy certificates not allowed, please set the appropriate flag>
 361
 362 Proxy certificates not allowed unless the  B<-allow_proxy_certs> option is used.
 363
 364 =item B<X509_V_ERR_UNNESTED_RESOURCE: RFC 3779 resource not subset of parent's resources>
 365
 366 See RFC 3779 for details.
 367
 368 =item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX: unsupported or invalid name syntax>
 369
 370 Unsupported or invalid name syntax.
 371
 372 =item B<X509_V_ERR_PATH_LOOP: path loop>
 373
 374 Path loop.
 375
 376 =item B<X509_V_ERR_HOSTNAME_MISMATCH: hostname mismatch>
 377
 378 Hostname mismatch.
 379
 380 =item B<X509_V_ERR_EMAIL_MISMATCH: email address mismatch>
 381
 382 Email address mismatch.
 383
 384 =item B<X509_V_ERR_IP_ADDRESS_MISMATCH: IP address mismatch>
 385
 386 IP address mismatch.
 387
 388 =item B<X509_V_ERR_DANE_NO_MATCH: no matching DANE TLSA records>
 389
 390 DANE TLSA authentication is enabled, but no TLSA records matched the
 391 certificate chain.
 392 This error is only possible in L<openssl-s_client(1)>.
 393
 394 =item B<X509_V_ERR_EE_KEY_TOO_SMALL: EE certificate key too weak>
 395
 396 EE certificate key too weak.
 397
 398 =item B<X509_ERR_CA_KEY_TOO_SMALL: CA certificate key too weak>
 399
 400 CA certificate key too weak.
 401
 402 =item B<X509_ERR_CA_MD_TOO_WEAK: CA signature digest algorithm too weak>
 403
 404 CA signature digest algorithm too weak.
 405
 406 =item B<X509_V_ERR_INVALID_CALL: invalid certificate verification context>
 407
 408 Invalid certificate verification context.
 409
 410 =item B<X509_V_ERR_STORE_LOOKUP: issuer certificate lookup error>
 411
 412 Issuer certificate lookup error.
 413
 414 =item B<X509_V_ERR_NO_VALID_SCTS: certificate transparency required, but no valid SCTs found>
 415
 416 Certificate Transparency required, but no valid SCTs found.
 417
 418 =item B<X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION: proxy subject name violation>
 419
 420 Proxy subject name violation.
 421
 422 =item B<X509_V_ERR_OCSP_VERIFY_NEEDED: OCSP verification needed>
 423
 424 Returned by the verify callback to indicate an OCSP verification is needed.
 425
 426 =item B<X509_V_ERR_OCSP_VERIFY_FAILED: OCSP verification failed>
 427
 428 Returned by the verify callback to indicate OCSP verification failed.
 429
 430 =item B<X509_V_ERR_OCSP_CERT_UNKNOWN: OCSP unknown cert>
 431
 432 Returned by the verify callback to indicate that the certificate is not
 433 recognized by the OCSP responder.
 434
 435 =item B<509_V_ERROR_NO_ISSUER_PUBLI_KEY, issuer certificate doesn't have a public key>
 436
 437 The issuer certificate does not have a public key.
 438
 439 =item B<X509_V_ERROR_SIGNATURE_ALGORITHM_MISMATCH, Subject signature algorithm and issuer public key algorithm mismatch>
 440
 441 The issuer's public key is not of the type required by the signature in
 442 the subject's certificate.
 443
 444 =back
 445
 446 =head1 NOTES
 447
 448 The above functions should be used instead of directly referencing the fields
 449 in the B<X509_VERIFY_CTX> structure.
 450
 451 In versions of OpenSSL before 1.0 the current certificate returned by
 452 X509_STORE_CTX_get_current_cert() was never B<NULL>. Applications should
 453 check the return value before printing out any debugging information relating
 454 to the current certificate.
 455
 456 If an unrecognised error code is passed to X509_verify_cert_error_string() the
 457 numerical value of the unknown code is returned in a static buffer. This is not
 458 thread safe but will never happen unless an invalid code is passed.
 459
 460 =head1 SEE ALSO
 461
 462 L<X509_verify_cert(3)>,
 463 L<X509_up_ref(3)>,
 464 L<X509_free(3)>.
 465
 466 =head1 COPYRIGHT
 467
 468 Copyright 2009-2020 The OpenSSL Project Authors. All Rights Reserved.
 469
 470 Licensed under the Apache License 2.0 (the "License").  You may not use
 471 this file except in compliance with the License.  You can obtain a copy
 472 in the file LICENSE in the source distribution or at
 473 L<https://www.openssl.org/source/license.html>.
 474
 475 =cut