1X509_STORE_CTX_GET_ERROR(3)         OpenSSL        X509_STORE_CTX_GET_ERROR(3)
2
3
4

NAME

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

SYNOPSIS

14        #include <openssl/x509.h>
15
16        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
24        STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx);
25
26        const char *X509_verify_cert_error_string(long n);
27

DESCRIPTION

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
33       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
36       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
40       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
46       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
50       X509_STORE_CTX_get_current_cert() returns the certificate in ctx which
51       caused the error or NULL if no certificate is relevant.
52
53       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
63       X509_STORE_CTX_get0_cert() retrieves an internal pointer to the
64       certificate being verified by the ctx.
65
66       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
73        sk_X509_pop_free(chain, X509_free);
74
75       X509_verify_cert_error_string() returns a human readable error string
76       for verification error n.
77

RETURN VALUES

79       X509_STORE_CTX_get_error() returns X509_V_OK or an error code.
80
81       X509_STORE_CTX_get_error_depth() returns a nonnegative error depth.
82
83       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
86       X509_verify_cert_error_string() returns a human readable error string
87       for verification error n.
88

ERROR CODES

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
94       X509_V_OK: ok
95           the operation was successful.
96
97       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
102       X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
103           the CRL of a certificate could not be found.
104
105       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
112       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
118       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
123       X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
124           the signature of the certificate is invalid.
125
126       X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
127           the signature of the certificate is invalid.
128
129       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
133       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
137       X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
138           the CRL is not yet valid.
139
140       X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
141           the CRL has expired.
142
143       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
147       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
151       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
155       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
159       X509_V_ERR_OUT_OF_MEM: out of memory
160           an error occurred trying to allocate memory. This should never
161           happen.
162
163       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
167       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
172       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
177       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
182       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
186       X509_V_ERR_CERT_REVOKED: certificate revoked
187           the certificate has been revoked.
188
189       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
193       X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
194           the basicConstraints path-length parameter has been exceeded.
195
196       X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose
197           the supplied certificate cannot be used for the specified purpose.
198
199       X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
200           the root CA is not marked as trusted for the specified purpose.
201
202       X509_V_ERR_CERT_REJECTED: certificate rejected
203           the root CA is marked to reject the specified purpose.
204
205       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
211       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
219       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
227       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
234       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
240       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
246       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
250       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
254       X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature
255           Some feature of a certificate extension is not supported. Unused.
256
257       X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation
258           A name constraint violation occurred in the permitted subtrees.
259
260       X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation
261           A name constraint violation occurred in the excluded subtrees.
262
263       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
268       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
274       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
281       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
285       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

NOTES

290       The above functions should be used instead of directly referencing the
291       fields in the X509_VERIFY_CTX structure.
292
293       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
298       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

SEE ALSO

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
309       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>.
313
314
315
3161.1.1i                            2021-07-22       X509_STORE_CTX_GET_ERROR(3)
Impressum