1X509_STORE_CTX_GET_ERROR(3ossl)     OpenSSL    X509_STORE_CTX_GET_ERROR(3ossl)
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(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

DESCRIPTION

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
34       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
40       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
44       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
50       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
54       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
59       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
69       X509_STORE_CTX_get0_cert() retrieves an internal pointer to the
70       certificate being verified by the ctx.
71
72       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
78        sk_X509_pop_free(chain, X509_free);
79
80       X509_verify_cert_error_string() returns a human readable error string
81       for verification error n.
82

RETURN VALUES

84       X509_STORE_CTX_get_error() returns X509_V_OK or an error code.
85
86       X509_STORE_CTX_get_error_depth() returns a nonnegative error depth.
87
88       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
91       X509_verify_cert_error_string() returns a human readable error string
92       for verification error n.
93

ERROR CODES

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
99       X509_V_OK: ok
100           The operation was successful.
101
102       X509_V_ERR_UNSPECIFIED: unspecified certificate verification error
103           Unspecified error; should not happen.
104
105       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
112       X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
113           The CRL of a certificate could not be found.
114
115       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
122       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
128       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
133       X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
134           The signature of the certificate is invalid.
135
136       X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
137           The signature of the CRL is invalid.
138
139       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
143       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
147       X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
148           The CRL is not yet valid.
149
150       X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
151           The CRL has expired.
152
153       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
157       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
161       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
165       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
169       X509_V_ERR_OUT_OF_MEM: out of memory
170           An error occurred trying to allocate memory.
171
172       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
176       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
182       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
187       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
193       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
197       X509_V_ERR_CERT_REVOKED: certificate revoked
198           The certificate has been revoked.
199
200       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
204       X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
205           The basicConstraints path-length parameter has been exceeded.
206
207       X509_V_ERR_INVALID_PURPOSE: unsuitable certificate purpose
208           The target certificate cannot be used for the specified purpose.
209
210       X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
211           The root CA is not marked as trusted for the specified purpose.
212
213       X509_V_ERR_CERT_REJECTED: certificate rejected
214           The root CA is marked to reject the specified purpose.
215
216       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
221       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
227       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
233       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
238       X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER: unable to get CRL issuer
239       certificate
240           Unable to get CRL issuer certificate.
241
242       X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION: unhandled critical extension
243           Unhandled critical extension.
244
245       X509_V_ERR_KEYUSAGE_NO_CRL_SIGN: key usage does not include CRL signing
246           Key usage does not include CRL signing.
247
248       X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION: unhandled critical CRL
249       extension
250           Unhandled critical CRL extension.
251
252       X509_V_ERR_INVALID_NON_CA: invalid non-CA certificate (has CA markings)
253           Invalid non-CA certificate has CA markings.
254
255       X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED: proxy path length constraint
256       exceeded
257           Proxy path length constraint exceeded.
258
259       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
264       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
269       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
275       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
281       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
285       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
289       X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: unsupported extension feature
290           Some feature of a certificate extension is not supported. Unused.
291
292       X509_V_ERR_UNNESTED_RESOURCE: RFC 3779 resource not subset of parent's
293       resources
294           See RFC 3779 for details.
295
296       X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation
297           A name constraint violation occurred in the permitted subtrees.
298
299       X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation
300           A name constraint violation occurred in the excluded subtrees.
301
302       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
307       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
311       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
317       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
324       X509_V_ERR_UNSUPPORTED_NAME_SYNTAX: unsupported or invalid name syntax
325           Unsupported or invalid name syntax.
326
327       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
331       X509_V_ERR_PATH_LOOP: path loop
332           Path loop.
333
334       X509_V_ERR_HOSTNAME_MISMATCH: hostname mismatch
335           Hostname mismatch.
336
337       X509_V_ERR_EMAIL_MISMATCH: email address mismatch
338           Email address mismatch.
339
340       X509_V_ERR_IP_ADDRESS_MISMATCH: IP address mismatch
341           IP address mismatch.
342
343       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
348       X509_V_ERR_EE_KEY_TOO_SMALL: EE certificate key too weak
349           EE certificate key too weak.
350
351       X509_V_ERR_CA_KEY_TOO_SMALL: CA certificate key too weak
352           CA certificate key too weak.
353
354       X509_V_ERR_CA_MD_TOO_WEAK: CA signature digest algorithm too weak
355           CA signature digest algorithm too weak.
356
357       X509_V_ERR_INVALID_CALL: invalid certificate verification context
358           Invalid certificate verification context.
359
360       X509_V_ERR_STORE_LOOKUP: issuer certificate lookup error
361           Issuer certificate lookup error.
362
363       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
367       X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION: proxy subject name violation
368           Proxy subject name violation.
369
370       X509_V_ERR_OCSP_VERIFY_NEEDED: OCSP verification needed
371           Returned by the verify callback to indicate an OCSP verification is
372           needed.
373
374       X509_V_ERR_OCSP_VERIFY_FAILED: OCSP verification failed
375           Returned by the verify callback to indicate OCSP verification
376           failed.
377
378       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
382       X509_V_ERR_UNSUPPORTED_SIGNATURE_ALGORITHM: unsupported signature
383       algorithm
384           Cannot find certificate signature algorithm.
385
386       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
391       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
396       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

NOTES

401       The above functions should be used instead of directly referencing the
402       fields in the X509_VERIFY_CTX structure.
403
404       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
409       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

BUGS

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

SEE ALSO

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
426       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>.
430
431
432
4333.0.9                             2023-07-27   X509_STORE_CTX_GET_ERROR(3ossl)
Impressum