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  sk_X509_pop_free(chain, X509_free);
  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 certificate 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 Not used as of OpenSSL 1.1.0.
 254
 255 =item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH:
 256 authority and issuer serial number mismatch>
 257
 258 The current candidate issuer certificate was rejected because its issuer name
 259 and serial number was present and did not match the authority key identifier of
 260 the current certificate.
 261 Not used as of OpenSSL 1.1.0.
 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 Not used as of OpenSSL 1.1.0.
 269
 270 =item B<X509_V_ERR_INVALID_EXTENSION:
 271 invalid or inconsistent certificate extension>
 272
 273 A certificate extension had an invalid value (for example an incorrect
 274 encoding) or some value inconsistent with other extensions.
 275
 276 =item B<X509_V_ERR_INVALID_POLICY_EXTENSION:
 277 invalid or inconsistent certificate policy extension>
 278
 279 A certificate policies extension had an invalid value (for example an incorrect
 280 encoding) or some value inconsistent with other extensions. This error only
 281 occurs if policy processing is enabled.
 282
 283 =item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy>
 284
 285 The verification flags were set to require and explicit policy but none was
 286 present.
 287
 288 =item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: different CRL scope>
 289
 290 The only CRLs that could be found did not match the scope of the certificate.
 291
 292 =item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature>
 293
 294 Some feature of a certificate extension is not supported. Unused.
 295
 296 =item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation>
 297
 298 A name constraint violation occurred in the permitted subtrees.
 299
 300 =item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation>
 301
 302 A name constraint violation occurred in the excluded subtrees.
 303
 304 =item B<X509_V_ERR_SUBTREE_MINMAX:
 305 name constraints minimum and maximum not supported>
 306
 307 A certificate name constraints extension included a minimum or maximum field:
 308 this is not supported.
 309
 310 =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE:
 311 unsupported name constraint type>
 312
 313 An unsupported name constraint type was encountered. OpenSSL currently only
 314 supports directory name, DNS name, email and URI types.
 315
 316 =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX:
 317 unsupported or invalid name constraint syntax>
 318
 319 The format of the name constraint is not recognised: for example an email
 320 address format of a form not mentioned in RFC3280. This could be caused by
 321 a garbage extension or some new feature not currently supported.
 322
 323 =item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error>
 324
 325 An error occurred when attempting to verify the CRL path. This error can only
 326 happen if extended CRL checking is enabled.
 327
 328 =item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
 329
 330 An application specific error. This will never be returned unless explicitly
 331 set by an application callback.
 332
 333 =item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER: unable to get CRL issuer certificate>
 334
 335 Unable to get CRL issuer certificate.
 336
 337 =item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION: unhandled critical extension>
 338
 339 Unhandled critical extension.
 340
 341 =item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN: key usage does not include CRL signing>
 342
 343 Key usage does not include CRL signing.
 344
 345 =item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION: unhandled critical CRL extension>
 346
 347 Unhandled critical CRL extension.
 348
 349 =item B<X509_V_ERR_INVALID_NON_CA: invalid non-CA certificate (has CA markings)>
 350
 351 Invalid non-CA certificate has CA markings.
 352
 353 =item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED: proxy path length constraint exceeded>
 354
 355 Proxy path length constraint exceeded.
 356
 357 =item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE: key usage does not include digital signature>
 358
 359 Key usage does not include digital signature, and therefore cannot sign
 360 certificates.
 361
 362 =item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED: proxy certificates not allowed, please set the appropriate flag>
 363
 364 Proxy certificates not allowed unless the B<X509_V_FLAG_ALLOW_PROXY_CERTS> flag
 365 is set.
 366
 367 =item B<X509_V_ERR_UNNESTED_RESOURCE: RFC 3779 resource not subset of parent's resources>
 368
 369 See RFC 3779 for details.
 370
 371 =item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX: unsupported or invalid name syntax>
 372
 373 Unsupported or invalid name syntax.
 374
 375 =item B<X509_V_ERR_PATH_LOOP: path loop>
 376
 377 Path loop.
 378
 379 =item B<X509_V_ERR_HOSTNAME_MISMATCH: hostname mismatch>
 380
 381 Hostname mismatch.
 382
 383 =item B<X509_V_ERR_EMAIL_MISMATCH: email address mismatch>
 384
 385 Email address mismatch.
 386
 387 =item B<X509_V_ERR_IP_ADDRESS_MISMATCH: IP address mismatch>
 388
 389 IP address mismatch.
 390
 391 =item B<X509_V_ERR_DANE_NO_MATCH: no matching DANE TLSA records>
 392
 393 DANE TLSA authentication is enabled, but no TLSA records matched the
 394 certificate chain.
 395 This error is only possible in L<openssl-s_client(1)>.
 396
 397 =item B<X509_V_ERR_EE_KEY_TOO_SMALL: EE certificate key too weak>
 398
 399 EE certificate key too weak.
 400
 401 =item B<X509_ERR_CA_KEY_TOO_SMALL: CA certificate key too weak>
 402
 403 CA certificate key too weak.
 404
 405 =item B<X509_ERR_CA_MD_TOO_WEAK: CA signature digest algorithm too weak>
 406
 407 CA signature digest algorithm too weak.
 408
 409 =item B<X509_V_ERR_INVALID_CALL: invalid certificate verification context>
 410
 411 Invalid certificate verification context.
 412
 413 =item B<X509_V_ERR_STORE_LOOKUP: issuer certificate lookup error>
 414
 415 Issuer certificate lookup error.
 416
 417 =item B<X509_V_ERR_NO_VALID_SCTS: certificate transparency required, but no valid SCTs found>
 418
 419 Certificate Transparency required, but no valid SCTs found.
 420
 421 =item B<X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION: proxy subject name violation>
 422
 423 Proxy subject name violation.
 424
 425 =item B<X509_V_ERR_OCSP_VERIFY_NEEDED: OCSP verification needed>
 426
 427 Returned by the verify callback to indicate an OCSP verification is needed.
 428
 429 =item B<X509_V_ERR_OCSP_VERIFY_FAILED: OCSP verification failed>
 430
 431 Returned by the verify callback to indicate OCSP verification failed.
 432
 433 =item B<X509_V_ERR_OCSP_CERT_UNKNOWN: OCSP unknown cert>
 434
 435 Returned by the verify callback to indicate that the certificate is not
 436 recognized by the OCSP responder.
 437
 438 =item B<509_V_ERROR_NO_ISSUER_PUBLI_KEY, issuer certificate doesn't have a public key>
 439
 440 The issuer certificate does not have a public key.
 441
 442 =item B<X509_V_ERROR_SIGNATURE_ALGORITHM_MISMATCH, Subject signature algorithm and issuer public key algorithm mismatch>
 443
 444 The issuer's public key is not of the type required by the signature in
 445 the subject's certificate.
 446
 447 =back
 448
 449 =head1 NOTES
 450
 451 The above functions should be used instead of directly referencing the fields
 452 in the B<X509_VERIFY_CTX> structure.
 453
 454 In versions of OpenSSL before 1.0 the current certificate returned by
 455 X509_STORE_CTX_get_current_cert() was never NULL. Applications should
 456 check the return value before printing out any debugging information relating
 457 to the current certificate.
 458
 459 If an unrecognised error code is passed to X509_verify_cert_error_string() the
 460 numerical value of the unknown code is returned in a static buffer. This is not
 461 thread safe but will never happen unless an invalid code is passed.
 462
 463 =head1 SEE ALSO
 464
 465 L<X509_verify_cert(3)>, L<X509_STORE_CTX_verify(3)>,
 466 L<X509_up_ref(3)>,
 467 L<X509_free(3)>.
 468
 469 =head1 COPYRIGHT
 470
 471 Copyright 2009-2021 The OpenSSL Project Authors. All Rights Reserved.
 472
 473 Licensed under the Apache License 2.0 (the "License").  You may not use
 474 this file except in compliance with the License.  You can obtain a copy
 475 in the file LICENSE in the source distribution or at
 476 L<https://www.openssl.org/source/license.html>.
 477
 478 =cut