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 certificate in ctx which
55 caused the error or NULL if no certificate is relevant.
56 X509_STORE_CTX_set_current_cert() sets the certificate x in ctx which
58 caused the error. This value is not intended to remain valid for very
59 long, and remains owned by the caller. It may be examined by a
60 verification callback invoked to handle each error encountered during
61 chain verification and is no longer required after such a callback. If
62 a callback wishes the save the certificate for use after it returns, it
63 needs to increment its reference count via X509_up_ref(3). Once such a
64 saved certificate is no longer needed it can be freed with
65 X509_free(3).
66 X509_STORE_CTX_get0_cert() retrieves an internal pointer to the
68 certificate being verified by the ctx.
69 X509_STORE_CTX_get1_chain() returns a complete validate chain if a
71 previous verification is successful. Otherwise the returned chain may
72 be incomplete or invalid. The returned chain persists after the ctx
73 structure is freed. When it is no longer needed it should be free up
74 using:
75 sk_X509_pop_free(chain, X509_free);
77 X509_verify_cert_error_string() returns a human readable error string
79 for verification error n.
80
82 X509_STORE_CTX_get_error() returns X509_V_OK or an error code.
83 X509_STORE_CTX_get_error_depth() returns a nonnegative error depth.
85 X509_STORE_CTX_get_current_cert() returns the certificate which caused
87 the error or NULL if no certificate is relevant to the error.
88 X509_verify_cert_error_string() returns a human readable error string
90 for verification error n.
91
93 A list of error codes and messages is shown below. Some of the error
94 codes are defined but currently never returned: these are described as
95 "unused".
96 X509_V_OK: ok
98 The operation was successful.
99 X509_V_ERR_UNSPECIFIED: unspecified certificate verification error
101 Unspecified error; should not happen.
102 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate
104 The issuer certificate of a locally looked up certificate could not
105 be found. This normally means the list of trusted certificates is
106 not complete. To allow any certificate (not only a self-signed
107 one) in the trust store to terminate the chain the
108 X509_V_FLAG_PARTIAL_CHAIN flag may be set.
109 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
111 The CRL of a certificate could not be found.
112 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt
114 certificate's signature
115 The certificate signature could not be decrypted. This means that
116 the actual signature value could not be determined rather than it
117 not matching the expected value, this is only meaningful for RSA
118 keys.
119 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's
121 signature
122 The CRL signature could not be decrypted: this means that the
123 actual signature value could not be determined rather than it not
124 matching the expected value. Unused.
125 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer
127 public key
128 The public key in the certificate "SubjectPublicKeyInfo" field
129 could not be read.
130 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
132 The signature of the certificate is invalid.
133 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
135 The signature of the CRL is invalid.
136 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid
138 The certificate is not yet valid: the "notBefore" date is after the
139 current time.
140 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired
142 The certificate has expired: that is the "notAfter" date is before
143 the current time.
144 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
146 The CRL is not yet valid.
147 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
149 The CRL has expired.
150 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in
152 certificate's notBefore field
153 The certificate "notBefore" field contains an invalid time.
154 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's
156 notAfter field
157 The certificate "notAfter" field contains an invalid time.
158 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's
160 lastUpdate field
161 The CRL lastUpdate field contains an invalid time.
162 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's
164 nextUpdate field
165 The CRL "nextUpdate" field contains an invalid time.
166 X509_V_ERR_OUT_OF_MEM: out of memory
168 An error occurred trying to allocate memory.
169 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self-signed certificate
171 The passed certificate is self-signed and the same certificate
172 cannot be found in the list of trusted certificates.
173 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self-signed certificate in
175 certificate chain
176 The certificate chain could be built up using the untrusted
177 certificates but no suitable trust anchor (which typically is a
178 self-signed root certificate) could be found in the trust store.
179 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local
181 issuer certificate
182 The issuer certificate could not be found: this occurs if the
183 issuer certificate of an untrusted certificate cannot be found.
184 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first
186 certificate
187 No signatures could be verified because the chain contains only one
188 certificate and it is not self-signed and the
189 X509_V_FLAG_PARTIAL_CHAIN flag is not set.
190 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long
192 The certificate chain length is greater than the supplied maximum
193 depth.
194 X509_V_ERR_CERT_REVOKED: certificate revoked
196 The certificate has been revoked.
197 X509_V_ERR_INVALID_CA: invalid CA certificate
199 A CA certificate is invalid. Either it is not a CA or its
200 extensions are not consistent with the supplied purpose.
201 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
203 The basicConstraints path-length parameter has been exceeded.
204 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose
206 The target certificate cannot be used for the specified purpose.
207 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
209 The root CA is not marked as trusted for the specified purpose.
210 X509_V_ERR_CERT_REJECTED: certificate rejected
212 The root CA is marked to reject the specified purpose.
213 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch
215 The current candidate issuer certificate was rejected because its
216 subject name did not match the issuer name of the current
217 certificate.
218 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier
220 mismatch
221 The current candidate issuer certificate was rejected because its
222 subject key identifier was present and did not match the authority
223 key identifier current certificate.
224 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial
226 number mismatch
227 The current candidate issuer certificate was rejected because its
228 issuer name and serial number was present and did not match the
229 authority key identifier of the current certificate.
230 X509_V_ERR_KEYUSAGE_NO_CERTSIGN: key usage does not include certificate
232 signing
233 The current candidate issuer certificate was rejected because its
234 "keyUsage" extension does not permit certificate signing.
235 X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate
237 extension
238 A certificate extension had an invalid value (for example an
239 incorrect encoding) or some value inconsistent with other
240 extensions.
241 X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent
243 certificate policy extension
244 A certificate policies extension had an invalid value (for example
245 an incorrect encoding) or some value inconsistent with other
246 extensions. This error only occurs if policy processing is enabled.
247 X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy
249 The verification flags were set to require and explicit policy but
250 none was present.
251 X509_V_ERR_DIFFERENT_CRL_SCOPE: different CRL scope
253 The only CRLs that could be found did not match the scope of the
254 certificate.
255 X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature
257 Some feature of a certificate extension is not supported. Unused.
258 X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation
260 A name constraint violation occurred in the permitted subtrees.
261 X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation
263 A name constraint violation occurred in the excluded subtrees.
264 X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not
266 supported
267 A certificate name constraints extension included a minimum or
268 maximum field: this is not supported.
269 X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint
271 type
272 An unsupported name constraint type was encountered. OpenSSL
273 currently only supports directory name, DNS name, email and URI
274 types.
275 X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name
277 constraint syntax
278 The format of the name constraint is not recognised: for example an
279 email address format of a form not mentioned in RFC3280. This could
280 be caused by a garbage extension or some new feature not currently
281 supported.
282 X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error
284 An error occurred when attempting to verify the CRL path. This
285 error can only happen if extended CRL checking is enabled.
286 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure
288 An application specific error. This will never be returned unless
289 explicitly set by an application callback.
290 X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER: unable to get CRL issuer
292 certificate
293 Unable to get CRL issuer certificate.
294 X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION: unhandled critical extension
296 Unhandled critical extension.
297 X509_V_ERR_KEYUSAGE_NO_CRL_SIGN: key usage does not include CRL signing
299 Key usage does not include CRL signing.
300 X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION: unhandled critical CRL
302 extension
303 Unhandled critical CRL extension.
304 X509_V_ERR_INVALID_NON_CA: invalid non-CA certificate (has CA markings)
306 Invalid non-CA certificate has CA markings.
307 X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED: proxy path length constraint
309 exceeded
310 Proxy path length constraint exceeded.
311 X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE: key usage does not include
313 digital signature
314 Key usage does not include digital signature, and therefore cannot
315 sign certificates.
316 X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED: proxy certificates not
318 allowed, please set the appropriate flag
319 Proxy certificates not allowed unless the
320 X509_V_FLAG_ALLOW_PROXY_CERTS flag is set.
321 X509_V_ERR_UNNESTED_RESOURCE: RFC 3779 resource not subset of parent's
323 resources
324 See RFC 3779 for details.
325 X509_V_ERR_UNSUPPORTED_NAME_SYNTAX: unsupported or invalid name syntax
327 Unsupported or invalid name syntax.
328 X509_V_ERR_PATH_LOOP: path loop
330 Path loop.
331 X509_V_ERR_HOSTNAME_MISMATCH: hostname mismatch
333 Hostname mismatch.
334 X509_V_ERR_EMAIL_MISMATCH: email address mismatch
336 Email address mismatch.
337 X509_V_ERR_IP_ADDRESS_MISMATCH: IP address mismatch
339 IP address mismatch.
340 X509_V_ERR_DANE_NO_MATCH: no matching DANE TLSA records
342 DANE TLSA authentication is enabled, but no TLSA records matched
343 the certificate chain. This error is only possible in
344 openssl-s_client(1).
345 X509_V_ERR_EE_KEY_TOO_SMALL: EE certificate key too weak
347 EE certificate key too weak.
348 X509_V_ERR_CA_KEY_TOO_SMALL: CA certificate key too weak
350 CA certificate key too weak.
351 X509_V_ERR_CA_MD_TOO_WEAK: CA signature digest algorithm too weak
353 CA signature digest algorithm too weak.
354 X509_V_ERR_INVALID_CALL: invalid certificate verification context
356 Invalid certificate verification context.
357 X509_V_ERR_STORE_LOOKUP: issuer certificate lookup error
359 Issuer certificate lookup error.
360 X509_V_ERR_NO_VALID_SCTS: certificate transparency required, but no
362 valid SCTs found
363 Certificate Transparency required, but no valid SCTs found.
364 X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION: proxy subject name violation
366 Proxy subject name violation.
367 X509_V_ERR_OCSP_VERIFY_NEEDED: OCSP verification needed
369 Returned by the verify callback to indicate an OCSP verification is
370 needed.
371 X509_V_ERR_OCSP_VERIFY_FAILED: OCSP verification failed
373 Returned by the verify callback to indicate OCSP verification
374 failed.
375 X509_V_ERR_OCSP_CERT_UNKNOWN: OCSP unknown cert
377 Returned by the verify callback to indicate that the certificate is
378 not recognized by the OCSP responder.
379 X509_V_ERR_NO_ISSUER_PUBLIC_KEY: issuer certificate doesn't have a
381 public key
382 The issuer certificate does not have a public key.
383 X509_V_ERR_SIGNATURE_ALGORITHM_MISMATCH: subject signature algorithm
385 and issuer public key algorithm mismatch
386 The issuer's public key is not of the type required by the
387 signature in the subject's certificate.
388
390 The above functions should be used instead of directly referencing the
391 fields in the X509_VERIFY_CTX structure.
392 In versions of OpenSSL before 1.0 the current certificate returned by
394 X509_STORE_CTX_get_current_cert() was never NULL. Applications should
395 check the return value before printing out any debugging information
396 relating to the current certificate.
397 If an unrecognised error code is passed to
399 X509_verify_cert_error_string() the numerical value of the unknown code
400 is returned in a static buffer. This is not thread safe but will never
401 happen unless an invalid code is passed.
402
404 Previous versions of this documentation swapped the meaning of the
405 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT and
406 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY error codes.
407
409 X509_verify_cert(3), X509_STORE_CTX_verify(3), X509_up_ref(3),
410 X509_free(3).
411
413 Copyright 2009-2022 The OpenSSL Project Authors. All Rights Reserved.
414 Licensed under the Apache License 2.0 (the "License"). You may not use
416 this file except in compliance with the License. You can obtain a copy
417 in the file LICENSE in the source distribution or at
418 <https://www.openssl.org/source/license.html>.
4193.0.5 2022-11-01 X509_STORE_CTX_GET_ERROR(3ossl)