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