1X509_STORE_CTX_GET_ERROR(3ossl) OpenSSL X509_STORE_CTX_GET_ERROR(3ossl)
2
6 X509_STORE_CTX_get_error, X509_STORE_CTX_set_error,
7 X509_STORE_CTX_get_error_depth, X509_STORE_CTX_set_error_depth,
8 X509_STORE_CTX_get_current_cert, X509_STORE_CTX_set_current_cert,
9 X509_STORE_CTX_get0_cert, X509_STORE_CTX_get1_chain,
10 X509_verify_cert_error_string - get or set certificate verification
11 status information
12
14 #include <openssl/x509.h>
15 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 STACK_OF(X509) *X509_STORE_CTX_get1_chain(const X509_STORE_CTX *ctx);
25 const char *X509_verify_cert_error_string(long n);
27
29 These functions are typically called after certificate or chain
30 verification using X509_verify_cert(3) or X509_STORE_CTX_verify(3) has
31 indicated an error or in a verification callback to determine the
32 nature of an error.
33 X509_STORE_CTX_get_error() returns the error code of ctx. See the
35 "ERROR CODES" section for a full description of all error codes. It
36 may return a code != X509_V_OK even if X509_verify_cert() did not
37 indicate an error, likely because a verification callback function has
38 waived the error.
39 X509_STORE_CTX_set_error() sets the error code of ctx to s. For example
41 it might be used in a verification callback to set an error based on
42 additional checks.
43 X509_STORE_CTX_get_error_depth() returns the depth of the error. This
45 is a nonnegative integer representing where in the certificate chain
46 the error occurred. If it is zero it occurred in the end entity
47 certificate, one if it is the certificate which signed the end entity
48 certificate and so on.
49 X509_STORE_CTX_set_error_depth() sets the error depth. This can be
51 used in combination with X509_STORE_CTX_set_error() to set the depth at
52 which an error condition was detected.
53 X509_STORE_CTX_get_current_cert() returns the current certificate in
55 ctx. If an error occurred, the current certificate will be the one that
56 is most closely related to the error, or possibly NULL if no such
57 certificate is relevant.
58 X509_STORE_CTX_set_current_cert() sets the certificate x in ctx which
60 caused the error. This value is not intended to remain valid for very
61 long, and remains owned by the caller. It may be examined by a
62 verification callback invoked to handle each error encountered during
63 chain verification and is no longer required after such a callback. If
64 a callback wishes the save the certificate for use after it returns, it
65 needs to increment its reference count via X509_up_ref(3). Once such a
66 saved certificate is no longer needed it can be freed with
67 X509_free(3).
68 X509_STORE_CTX_get0_cert() retrieves an internal pointer to the
70 certificate being verified by the ctx.
71 X509_STORE_CTX_get1_chain() returns a complete validate chain if a
73 previous verification is successful. Otherwise the returned chain may
74 be incomplete or invalid. The returned chain persists after the ctx
75 structure is freed. When it is no longer needed it should be free up
76 using:
77 sk_X509_pop_free(chain, X509_free);
79 X509_verify_cert_error_string() returns a human readable error string
81 for verification error n.
82
84 X509_STORE_CTX_get_error() returns X509_V_OK or an error code.
85 X509_STORE_CTX_get_error_depth() returns a nonnegative error depth.
87 X509_STORE_CTX_get_current_cert() returns the certificate which caused
89 the error or NULL if no certificate is relevant to the error.
90 X509_verify_cert_error_string() returns a human readable error string
92 for verification error n.
93
95 A list of error codes and messages is shown below. Some of the error
96 codes are defined but currently never returned: these are described as
97 "unused".
98 X509_V_OK: ok
100 The operation was successful.
101 X509_V_ERR_UNSPECIFIED: unspecified certificate verification error
103 Unspecified error; should not happen.
104 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate
106 The issuer certificate of a locally looked up certificate could not
107 be found. This normally means the list of trusted certificates is
108 not complete. To allow any certificate (not only a self-signed
109 one) in the trust store to terminate the chain the
110 X509_V_FLAG_PARTIAL_CHAIN flag may be set.
111 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
113 The CRL of a certificate could not be found.
114 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt
116 certificate's signature
117 The certificate signature could not be decrypted. This means that
118 the actual signature value could not be determined rather than it
119 not matching the expected value, this is only meaningful for RSA
120 keys.
121 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's
123 signature
124 The CRL signature could not be decrypted: this means that the
125 actual signature value could not be determined rather than it not
126 matching the expected value. Unused.
127 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer
129 public key
130 The public key in the certificate "SubjectPublicKeyInfo" field
131 could not be read.
132 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
134 The signature of the certificate is invalid.
135 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
137 The signature of the CRL is invalid.
138 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid
140 The certificate is not yet valid: the "notBefore" date is after the
141 current time.
142 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired
144 The certificate has expired: that is the "notAfter" date is before
145 the current time.
146 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
148 The CRL is not yet valid.
149 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
151 The CRL has expired.
152 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in
154 certificate's notBefore field
155 The certificate "notBefore" field contains an invalid time.
156 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's
158 notAfter field
159 The certificate "notAfter" field contains an invalid time.
160 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's
162 lastUpdate field
163 The CRL lastUpdate field contains an invalid time.
164 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's
166 nextUpdate field
167 The CRL "nextUpdate" field contains an invalid time.
168 X509_V_ERR_OUT_OF_MEM: out of memory
170 An error occurred trying to allocate memory.
171 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self-signed certificate
173 The passed certificate is self-signed and the same certificate
174 cannot be found in the list of trusted certificates.
175 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self-signed certificate in
177 certificate chain
178 The certificate chain could be built up using the untrusted
179 certificates but no suitable trust anchor (which typically is a
180 self-signed root certificate) could be found in the trust store.
181 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local
183 issuer certificate
184 The issuer certificate could not be found: this occurs if the
185 issuer certificate of an untrusted certificate cannot be found.
186 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first
188 certificate
189 No signatures could be verified because the chain contains only one
190 certificate and it is not self-signed and the
191 X509_V_FLAG_PARTIAL_CHAIN flag is not set.
192 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long
194 The certificate chain length is greater than the supplied maximum
195 depth.
196 X509_V_ERR_CERT_REVOKED: certificate revoked
198 The certificate has been revoked.
199 X509_V_ERR_NO_ISSUER_PUBLIC_KEY: issuer certificate doesn't have a
201 public key
202 The issuer certificate does not have a public key.
203 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
205 The basicConstraints path-length parameter has been exceeded.
206 X509_V_ERR_INVALID_PURPOSE: unsuitable certificate purpose
208 The target certificate cannot be used for the specified purpose.
209 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
211 The root CA is not marked as trusted for the specified purpose.
212 X509_V_ERR_CERT_REJECTED: certificate rejected
214 The root CA is marked to reject the specified purpose.
215 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch
217 The current candidate issuer certificate was rejected because its
218 subject name did not match the issuer name of the current
219 certificate.
220 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier
222 mismatch
223 The current candidate issuer certificate was rejected because its
224 subject key identifier was present and did not match the authority
225 key identifier current certificate.
226 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial
228 number mismatch
229 The current candidate issuer certificate was rejected because its
230 issuer name and serial number was present and did not match the
231 authority key identifier of the current certificate.
232 X509_V_ERR_KEYUSAGE_NO_CERTSIGN: key usage does not include certificate
234 signing
235 The current candidate issuer certificate was rejected because its
236 "keyUsage" extension does not permit certificate signing.
237 X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER: unable to get CRL issuer
239 certificate
240 Unable to get CRL issuer certificate.
241 X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION: unhandled critical extension
243 Unhandled critical extension.
244 X509_V_ERR_KEYUSAGE_NO_CRL_SIGN: key usage does not include CRL signing
246 Key usage does not include CRL signing.
247 X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION: unhandled critical CRL
249 extension
250 Unhandled critical CRL extension.
251 X509_V_ERR_INVALID_NON_CA: invalid non-CA certificate (has CA markings)
253 Invalid non-CA certificate has CA markings.
254 X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED: proxy path length constraint
256 exceeded
257 Proxy path length constraint exceeded.
258 X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE: key usage does not include
260 digital signature
261 Key usage does not include digital signature, and therefore cannot
262 sign certificates.
263 X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED: proxy certificates not
265 allowed, please set the appropriate flag
266 Proxy certificates not allowed unless the
267 X509_V_FLAG_ALLOW_PROXY_CERTS flag is set.
268 X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate
270 extension
271 A certificate extension had an invalid value (for example an
272 incorrect encoding) or some value inconsistent with other
273 extensions.
274 X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent
276 certificate policy extension
277 A certificate policies extension had an invalid value (for example
278 an incorrect encoding) or some value inconsistent with other
279 extensions. This error only occurs if policy processing is enabled.
280 X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy
282 The verification flags were set to require and explicit policy but
283 none was present.
284 X509_V_ERR_DIFFERENT_CRL_SCOPE: different CRL scope
286 The only CRLs that could be found did not match the scope of the
287 certificate.
288 X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: unsupported extension feature
290 Some feature of a certificate extension is not supported. Unused.
291 X509_V_ERR_UNNESTED_RESOURCE: RFC 3779 resource not subset of parent's
293 resources
294 See RFC 3779 for details.
295 X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation
297 A name constraint violation occurred in the permitted subtrees.
298 X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation
300 A name constraint violation occurred in the excluded subtrees.
301 X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not
303 supported
304 A certificate name constraints extension included a minimum or
305 maximum field: this is not supported.
306 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure
308 An application specific error. This will never be returned unless
309 explicitly set by an application callback.
310 X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint
312 type
313 An unsupported name constraint type was encountered. OpenSSL
314 currently only supports directory name, DNS name, email and URI
315 types.
316 X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name
318 constraint syntax
319 The format of the name constraint is not recognised: for example an
320 email address format of a form not mentioned in RFC3280. This could
321 be caused by a garbage extension or some new feature not currently
322 supported.
323 X509_V_ERR_UNSUPPORTED_NAME_SYNTAX: unsupported or invalid name syntax
325 Unsupported or invalid name syntax.
326 X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error
328 An error occurred when attempting to verify the CRL path. This
329 error can only happen if extended CRL checking is enabled.
330 X509_V_ERR_PATH_LOOP: path loop
332 Path loop.
333 X509_V_ERR_HOSTNAME_MISMATCH: hostname mismatch
335 Hostname mismatch.
336 X509_V_ERR_EMAIL_MISMATCH: email address mismatch
338 Email address mismatch.
339 X509_V_ERR_IP_ADDRESS_MISMATCH: IP address mismatch
341 IP address mismatch.
342 X509_V_ERR_DANE_NO_MATCH: no matching DANE TLSA records
344 DANE TLSA authentication is enabled, but no TLSA records matched
345 the certificate chain. This error is only possible in
346 openssl-s_client(1).
347 X509_V_ERR_EE_KEY_TOO_SMALL: EE certificate key too weak
349 EE certificate key too weak.
350 X509_V_ERR_CA_KEY_TOO_SMALL: CA certificate key too weak
352 CA certificate key too weak.
353 X509_V_ERR_CA_MD_TOO_WEAK: CA signature digest algorithm too weak
355 CA signature digest algorithm too weak.
356 X509_V_ERR_INVALID_CALL: invalid certificate verification context
358 Invalid certificate verification context.
359 X509_V_ERR_STORE_LOOKUP: issuer certificate lookup error
361 Issuer certificate lookup error.
362 X509_V_ERR_NO_VALID_SCTS: certificate transparency required, but no
364 valid SCTs found
365 Certificate Transparency required, but no valid SCTs found.
366 X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION: proxy subject name violation
368 Proxy subject name violation.
369 X509_V_ERR_OCSP_VERIFY_NEEDED: OCSP verification needed
371 Returned by the verify callback to indicate an OCSP verification is
372 needed.
373 X509_V_ERR_OCSP_VERIFY_FAILED: OCSP verification failed
375 Returned by the verify callback to indicate OCSP verification
376 failed.
377 X509_V_ERR_OCSP_CERT_UNKNOWN: OCSP unknown cert
379 Returned by the verify callback to indicate that the certificate is
380 not recognized by the OCSP responder.
381 X509_V_ERR_UNSUPPORTED_SIGNATURE_ALGORITHM: unsupported signature
383 algorithm
384 Cannot find certificate signature algorithm.
385 X509_V_ERR_SIGNATURE_ALGORITHM_MISMATCH: subject signature algorithm
387 and issuer public key algorithm mismatch
388 The issuer's public key is not of the type required by the
389 signature in the subject's certificate.
390 X509_V_ERR_SIGNATURE_ALGORITHM_INCONSISTENCY: cert info signature and
392 signature algorithm mismatch
393 The algorithm given in the certificate info is inconsistent
394 with the one used for the certificate signature.
395 X509_V_ERR_INVALID_CA: invalid CA certificate
397 A CA certificate is invalid. Either it is not a CA or its
398 extensions are not consistent with the supplied purpose.
399
401 The above functions should be used instead of directly referencing the
402 fields in the X509_VERIFY_CTX structure.
403 In versions of OpenSSL before 1.0 the current certificate returned by
405 X509_STORE_CTX_get_current_cert() was never NULL. Applications should
406 check the return value before printing out any debugging information
407 relating to the current certificate.
408 If an unrecognised error code is passed to
410 X509_verify_cert_error_string() the numerical value of the unknown code
411 is returned in a static buffer. This is not thread safe but will never
412 happen unless an invalid code is passed.
413
415 Previous versions of this documentation swapped the meaning of the
416 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT and
417 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY error codes.
418
420 X509_verify_cert(3), X509_STORE_CTX_verify(3), X509_up_ref(3),
421 X509_free(3).
422
424 Copyright 2009-2023 The OpenSSL Project Authors. All Rights Reserved.
425 Licensed under the Apache License 2.0 (the "License"). You may not use
427 this file except in compliance with the License. You can obtain a copy
428 in the file LICENSE in the source distribution or at
429 <https://www.openssl.org/source/license.html>.
4303.1.1 2023-08-31 X509_STORE_CTX_GET_ERROR(3ossl)