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