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