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