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 certificate in I<ctx> which
  53 caused the error or NULL if no certificate is relevant.
  54
  55 X509_STORE_CTX_set_current_cert() sets the certificate I<x> in I<ctx> which
  56 caused the error.
  57 This value is not intended to remain valid for very long, and remains owned by
  58 the caller.
  59 It may be examined by a verification callback invoked to handle each error
  60 encountered during chain verification and is no longer required after such a
  61 callback.
  62 If a callback wishes the save the certificate for use after it returns, it
  63 needs to increment its reference count via L<X509_up_ref(3)>.
  64 Once such a I<saved> certificate is no longer needed it can be freed with
  65 L<X509_free(3)>.
  66
  67 X509_STORE_CTX_get0_cert() retrieves an internal pointer to the
  68 certificate being verified by the I<ctx>.
  69
  70 X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous
  71 verification is successful. Otherwise the returned chain may be incomplete or
  72 invalid.  The returned chain persists after the I<ctx> structure is freed.
  73 When it is no longer needed it should be free up using:
  74
  75  OSSL_STACK_OF_X509_free(chain);
  76
  77 X509_verify_cert_error_string() returns a human readable error string for
  78 verification error I<n>.
  79
  80 =head1 RETURN VALUES
  81
  82 X509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code.
  83
  84 X509_STORE_CTX_get_error_depth() returns a nonnegative error depth.
  85
  86 X509_STORE_CTX_get_current_cert() returns the certificate which caused the
  87 error or NULL if no certificate is relevant to the error.
  88
  89 X509_verify_cert_error_string() returns a human readable error string for
  90 verification error I<n>.
  91
  92 =head1 ERROR CODES
  93
  94 A list of error codes and messages is shown below.  Some of the
  95 error codes are defined but currently never returned: these are described as
  96 "unused".
  97
  98 =over 4
  99
 100 =item B<X509_V_OK: ok>
 101
 102 The operation was successful.
 103
 104 =item B<X509_V_ERR_UNSPECIFIED: unspecified certificate verification error>
 105
 106 Unspecified error; should not happen.
 107
 108 =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
 109
 110 The issuer certificate of a locally looked up certificate could not be found.
 111 This normally means the list of trusted certificates is not complete.
 112 To allow any certificate (not only a self-signed one) in the trust store
 113 to terminate the chain the B<X509_V_FLAG_PARTIAL_CHAIN> flag may be set.
 114
 115 =item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
 116
 117 The CRL of a certificate could not be found.
 118
 119 =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE:
 120 unable to decrypt certificate's signature>
 121
 122 The certificate signature could not be decrypted. This means that the actual
 123 signature value could not be determined rather than it not matching the
 124 expected value, this is only meaningful for RSA keys.
 125
 126 =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE:
 127 unable to decrypt CRL's signature>
 128
 129 The CRL signature could not be decrypted: this means that the actual signature
 130 value could not be determined rather than it not matching the expected value.
 131 Unused.
 132
 133 =item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY:
 134 unable to decode issuer public key>
 135
 136 The public key in the certificate C<SubjectPublicKeyInfo> field could
 137 not be read.
 138
 139 =item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
 140
 141 The signature of the certificate is invalid.
 142
 143 =item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
 144
 145 The signature of the CRL is invalid.
 146
 147 =item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
 148
 149 The certificate is not yet valid: the C<notBefore> date is after the
 150 current time.
 151
 152 =item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired>
 153
 154 The certificate has expired: that is the C<notAfter> date is before the
 155 current time.
 156
 157 =item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
 158
 159 The CRL is not yet valid.
 160
 161 =item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
 162
 163 The CRL has expired.
 164
 165 =item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD:
 166 format error in certificate's notBefore field>
 167
 168 The certificate C<notBefore> field contains an invalid time.
 169
 170 =item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD:
 171 format error in certificate's notAfter field>
 172
 173 The certificate C<notAfter> field contains an invalid time.
 174
 175 =item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD:
 176 format error in CRL's lastUpdate field>
 177
 178 The CRL B<lastUpdate> field contains an invalid time.
 179
 180 =item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD:
 181 format error in CRL's nextUpdate field>
 182
 183 The CRL C<nextUpdate> field contains an invalid time.
 184
 185 =item B<X509_V_ERR_OUT_OF_MEM: out of memory>
 186
 187 An error occurred trying to allocate memory.
 188
 189 =item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self-signed certificate>
 190
 191 The passed certificate is self-signed and the same certificate cannot be found
 192 in the list of trusted certificates.
 193
 194 =item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN:
 195 self-signed certificate in certificate chain>
 196
 197 The certificate chain could be built up using the untrusted certificates
 198 but no suitable trust anchor (which typically is a self-signed root certificate)
 199 could be found in the trust store.
 200
 201 =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY:
 202 unable to get local issuer certificate>
 203
 204 The issuer certificate could not be found: this occurs if the issuer certificate
 205 of an untrusted certificate cannot be found.
 206
 207 =item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE:
 208 unable to verify the first certificate>
 209
 210 No signatures could be verified because the chain contains only one certificate
 211 and it is not self-signed and the B<X509_V_FLAG_PARTIAL_CHAIN> flag is not set.
 212
 213 =item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
 214
 215 The certificate chain length is greater than the supplied maximum depth. Unused.
 216
 217 =item B<X509_V_ERR_CERT_REVOKED: certificate revoked>
 218
 219 The certificate has been revoked.
 220
 221 =item B<X509_V_ERR_INVALID_CA: invalid CA certificate>
 222
 223 A CA certificate is invalid. Either it is not a CA or its extensions are not
 224 consistent with the supplied purpose.
 225
 226 =item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
 227
 228 The basicConstraints path-length parameter has been exceeded.
 229
 230 =item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
 231
 232 The target certificate cannot be used for the specified purpose.
 233
 234 =item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
 235
 236 The root CA is not marked as trusted for the specified purpose.
 237
 238 =item B<X509_V_ERR_CERT_REJECTED: certificate rejected>
 239
 240 The root CA is marked to reject the specified purpose.
 241
 242 =item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
 243
 244 The current candidate issuer certificate was rejected because its subject name
 245 did not match the issuer name of the current certificate.
 246
 247 =item B<X509_V_ERR_AKID_SKID_MISMATCH:
 248 authority and subject key identifier mismatch>
 249
 250 The current candidate issuer certificate was rejected because its subject key
 251 identifier was present and did not match the authority key identifier current
 252 certificate.
 253
 254 =item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH:
 255 authority and issuer serial number mismatch>
 256
 257 The current candidate issuer certificate was rejected because its issuer name
 258 and serial number was present and did not match the authority key identifier of
 259 the current certificate.
 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 C<keyUsage>
 265 extension does not permit certificate signing.
 266
 267 =item B<X509_V_ERR_INVALID_EXTENSION:
 268 invalid or inconsistent certificate extension>
 269
 270 A certificate extension had an invalid value (for example an incorrect
 271 encoding) or some value inconsistent with other extensions.
 272
 273 =item B<X509_V_ERR_INVALID_POLICY_EXTENSION:
 274 invalid or inconsistent certificate policy extension>
 275
 276 A certificate policies extension had an invalid value (for example an incorrect
 277 encoding) or some value inconsistent with other extensions. This error only
 278 occurs if policy processing is enabled.
 279
 280 =item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy>
 281
 282 The verification flags were set to require and explicit policy but none was
 283 present.
 284
 285 =item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: different CRL scope>
 286
 287 The only CRLs that could be found did not match the scope of the certificate.
 288
 289 =item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature>
 290
 291 Some feature of a certificate extension is not supported. Unused.
 292
 293 =item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation>
 294
 295 A name constraint violation occurred in the permitted subtrees.
 296
 297 =item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation>
 298
 299 A name constraint violation occurred in the excluded subtrees.
 300
 301 =item B<X509_V_ERR_SUBTREE_MINMAX:
 302 name constraints minimum and maximum not supported>
 303
 304 A certificate name constraints extension included a minimum or maximum field:
 305 this is not supported.
 306
 307 =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE:
 308 unsupported name constraint type>
 309
 310 An unsupported name constraint type was encountered. OpenSSL currently only
 311 supports directory name, DNS name, email and URI types.
 312
 313 =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX:
 314 unsupported or invalid name constraint syntax>
 315
 316 The format of the name constraint is not recognised: for example an email
 317 address format of a form not mentioned in RFC3280. This could be caused by
 318 a garbage extension or some new feature not currently supported.
 319
 320 =item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error>
 321
 322 An error occurred when attempting to verify the CRL path. This error can only
 323 happen if extended CRL checking is enabled.
 324
 325 =item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
 326
 327 An application specific error. This will never be returned unless explicitly
 328 set by an application callback.
 329
 330 =item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER: unable to get CRL issuer certificate>
 331
 332 Unable to get CRL issuer certificate.
 333
 334 =item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION: unhandled critical extension>
 335
 336 Unhandled critical extension.
 337
 338 =item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN: key usage does not include CRL signing>
 339
 340 Key usage does not include CRL signing.
 341
 342 =item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION: unhandled critical CRL extension>
 343
 344 Unhandled critical CRL extension.
 345
 346 =item B<X509_V_ERR_INVALID_NON_CA: invalid non-CA certificate (has CA markings)>
 347
 348 Invalid non-CA certificate has CA markings.
 349
 350 =item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED: proxy path length constraint exceeded>
 351
 352 Proxy path length constraint exceeded.
 353
 354 =item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE: key usage does not include digital signature>
 355
 356 Key usage does not include digital signature, and therefore cannot sign
 357 certificates.
 358
 359 =item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED: proxy certificates not allowed, please set the appropriate flag>
 360
 361 Proxy certificates not allowed unless the B<X509_V_FLAG_ALLOW_PROXY_CERTS> flag
 362 is set.
 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_V_ERR_CA_KEY_TOO_SMALL: CA certificate key too weak>
 399
 400 CA certificate key too weak.
 401
 402 =item B<X509_V_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<X509_V_ERR_NO_ISSUER_PUBLIC_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_ERR_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 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 BUGS
 461
 462 Previous versions of this documentation swapped the meaning of the
 463 B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
 464 B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
 465
 466 =head1 SEE ALSO
 467
 468 L<X509_verify_cert(3)>, L<X509_STORE_CTX_verify(3)>,
 469 L<X509_up_ref(3)>,
 470 L<X509_free(3)>.
 471
 472 =head1 COPYRIGHT
 473
 474 Copyright 2009-2021 The OpenSSL Project Authors. All Rights Reserved.
 475
 476 Licensed under the Apache License 2.0 (the "License").  You may not use
 477 this file except in compliance with the License.  You can obtain a copy
 478 in the file LICENSE in the source distribution or at
 479 L<https://www.openssl.org/source/license.html>.
 480
 481 =cut