1X509_STORE_CTX_GET_ERROR(3) OpenSSL X509_STORE_CTX_GET_ERROR(3)
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(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(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(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(X509_STORE_CTX *ctx);
23 STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx);
25 const char *X509_verify_cert_error_string(long n);
27
29 These functions are typically called after X509_verify_cert() has
30 indicated an error or in a verification callback to determine the
31 nature of an error.
32 X509_STORE_CTX_get_error() returns the error code of ctx, see the ERROR
34 CODES section for a full description of all error codes.
35 X509_STORE_CTX_set_error() sets the error code of ctx to s. For example
37 it might be used in a verification callback to set an error based on
38 additional checks.
39 X509_STORE_CTX_get_error_depth() returns the depth of the error. This
41 is a nonnegative integer representing where in the certificate chain
42 the error occurred. If it is zero it occurred in the end entity
43 certificate, one if it is the certificate which signed the end entity
44 certificate and so on.
45 X509_STORE_CTX_set_error_depth() sets the error depth. This can be
47 used in combination with X509_STORE_CTX_set_error() to set the depth at
48 which an error condition was detected.
49 X509_STORE_CTX_get_current_cert() returns the certificate in ctx which
51 caused the error or NULL if no certificate is relevant.
52 X509_STORE_CTX_set_current_cert() sets the certificate x in ctx which
54 caused the error. This value is not intended to remain valid for very
55 long, and remains owned by the caller. It may be examined by a
56 verification callback invoked to handle each error encountered during
57 chain verification and is no longer required after such a callback. If
58 a callback wishes the save the certificate for use after it returns, it
59 needs to increment its reference count via X509_up_ref(3). Once such a
60 saved certificate is no longer needed it can be freed with
61 X509_free(3).
62 X509_STORE_CTX_get0_cert() retrieves an internal pointer to the
64 certificate being verified by the ctx.
65 X509_STORE_CTX_get1_chain() returns a complete validate chain if a
67 previous call to X509_verify_cert() is successful. If the call to
68 X509_verify_cert() is not successful the returned chain may be
69 incomplete or invalid. The returned chain persists after the ctx
70 structure is freed, when it is no longer needed it should be free up
71 using:
72 sk_X509_pop_free(chain, X509_free);
74 X509_verify_cert_error_string() returns a human readable error string
76 for verification error n.
77
79 X509_STORE_CTX_get_error() returns X509_V_OK or an error code.
80 X509_STORE_CTX_get_error_depth() returns a nonnegative error depth.
82 X509_STORE_CTX_get_current_cert() returns the certificate which caused
84 the error or NULL if no certificate is relevant to the error.
85 X509_verify_cert_error_string() returns a human readable error string
87 for verification error n.
88
90 A list of error codes and messages is shown below. Some of the error
91 codes are defined but currently never returned: these are described as
92 "unused".
93 X509_V_OK: ok
95 the operation was successful.
96 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate
98 the issuer certificate of a locally looked up certificate could not
99 be found. This normally means the list of trusted certificates is
100 not complete.
101 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
103 the CRL of a certificate could not be found.
104 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt
106 certificate's signature
107 the certificate signature could not be decrypted. This means that
108 the actual signature value could not be determined rather than it
109 not matching the expected value, this is only meaningful for RSA
110 keys.
111 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's
113 signature
114 the CRL signature could not be decrypted: this means that the
115 actual signature value could not be determined rather than it not
116 matching the expected value. Unused.
117 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer
119 public key
120 the public key in the certificate SubjectPublicKeyInfo could not be
121 read.
122 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
124 the signature of the certificate is invalid.
125 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
127 the signature of the certificate is invalid.
128 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid
130 the certificate is not yet valid: the notBefore date is after the
131 current time.
132 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired
134 the certificate has expired: that is the notAfter date is before
135 the current time.
136 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
138 the CRL is not yet valid.
139 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
141 the CRL has expired.
142 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in
144 certificate's notBefore field
145 the certificate notBefore field contains an invalid time.
146 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's
148 notAfter field
149 the certificate notAfter field contains an invalid time.
150 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's
152 lastUpdate field
153 the CRL lastUpdate field contains an invalid time.
154 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's
156 nextUpdate field
157 the CRL nextUpdate field contains an invalid time.
158 X509_V_ERR_OUT_OF_MEM: out of memory
160 an error occurred trying to allocate memory. This should never
161 happen.
162 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate
164 the passed certificate is self signed and the same certificate
165 cannot be found in the list of trusted certificates.
166 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in
168 certificate chain
169 the certificate chain could be built up using the untrusted
170 certificates but the root could not be found locally.
171 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local
173 issuer certificate
174 the issuer certificate could not be found: this occurs if the
175 issuer certificate of an untrusted certificate cannot be found.
176 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first
178 certificate
179 no signatures could be verified because the chain contains only one
180 certificate and it is not self signed.
181 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long
183 the certificate chain length is greater than the supplied maximum
184 depth. Unused.
185 X509_V_ERR_CERT_REVOKED: certificate revoked
187 the certificate has been revoked.
188 X509_V_ERR_INVALID_CA: invalid CA certificate
190 a CA certificate is invalid. Either it is not a CA or its
191 extensions are not consistent with the supplied purpose.
192 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
194 the basicConstraints path-length parameter has been exceeded.
195 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose
197 the supplied certificate cannot be used for the specified purpose.
198 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
200 the root CA is not marked as trusted for the specified purpose.
201 X509_V_ERR_CERT_REJECTED: certificate rejected
203 the root CA is marked to reject the specified purpose.
204 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch
206 the current candidate issuer certificate was rejected because its
207 subject name did not match the issuer name of the current
208 certificate. This is only set if issuer check debugging is enabled
209 it is used for status notification and is not in itself an error.
210 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier
212 mismatch
213 the current candidate issuer certificate was rejected because its
214 subject key identifier was present and did not match the authority
215 key identifier current certificate. This is only set if issuer
216 check debugging is enabled it is used for status notification and
217 is not in itself an error.
218 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial
220 number mismatch
221 the current candidate issuer certificate was rejected because its
222 issuer name and serial number was present and did not match the
223 authority key identifier of the current certificate. This is only
224 set if issuer check debugging is enabled it is used for status
225 notification and is not in itself an error.
226 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate
228 signing
229 the current candidate issuer certificate was rejected because its
230 keyUsage extension does not permit certificate signing. This is
231 only set if issuer check debugging is enabled it is used for status
232 notification and is not in itself an error.
233 X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate
235 extension
236 A certificate extension had an invalid value (for example an
237 incorrect encoding) or some value inconsistent with other
238 extensions.
239 X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent
241 certificate policy extension
242 A certificate policies extension had an invalid value (for example
243 an incorrect encoding) or some value inconsistent with other
244 extensions. This error only occurs if policy processing is enabled.
245 X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy
247 The verification flags were set to require and explicit policy but
248 none was present.
249 X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope
251 The only CRLs that could be found did not match the scope of the
252 certificate.
253 X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature
255 Some feature of a certificate extension is not supported. Unused.
256 X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation
258 A name constraint violation occurred in the permitted subtrees.
259 X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation
261 A name constraint violation occurred in the excluded subtrees.
262 X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not
264 supported
265 A certificate name constraints extension included a minimum or
266 maximum field: this is not supported.
267 X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint
269 type
270 An unsupported name constraint type was encountered. OpenSSL
271 currently only supports directory name, DNS name, email and URI
272 types.
273 X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name
275 constraint syntax
276 The format of the name constraint is not recognised: for example an
277 email address format of a form not mentioned in RFC3280. This could
278 be caused by a garbage extension or some new feature not currently
279 supported.
280 X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error
282 An error occurred when attempting to verify the CRL path. This
283 error can only happen if extended CRL checking is enabled.
284 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure
286 an application specific error. This will never be returned unless
287 explicitly set by an application.
288
290 The above functions should be used instead of directly referencing the
291 fields in the X509_VERIFY_CTX structure.
292 In versions of OpenSSL before 1.0 the current certificate returned by
294 X509_STORE_CTX_get_current_cert() was never NULL. Applications should
295 check the return value before printing out any debugging information
296 relating to the current certificate.
297 If an unrecognised error code is passed to
299 X509_verify_cert_error_string() the numerical value of the unknown code
300 is returned in a static buffer. This is not thread safe but will never
301 happen unless an invalid code is passed.
302
304 X509_verify_cert(3), X509_up_ref(3), X509_free(3).
305
307 Copyright 2009-2020 The OpenSSL Project Authors. All Rights Reserved.
308 Licensed under the OpenSSL license (the "License"). You may not use
310 this file except in compliance with the License. You can obtain a copy
311 in the file LICENSE in the source distribution or at
312 <https://www.openssl.org/source/license.html>.
3131.1.1q 2023-07-20 X509_STORE_CTX_GET_ERROR(3)