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