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 certificate in ctx which
55       caused the error or NULL if no certificate is relevant.
56
57       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
67       X509_STORE_CTX_get0_cert() retrieves an internal pointer to the
68       certificate being verified by the ctx.
69
70       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
76        sk_X509_pop_free(chain, X509_free);
77
78       X509_verify_cert_error_string() returns a human readable error string
79       for verification error n.
80

RETURN VALUES

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

ERROR CODES

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
97       X509_V_OK: ok
98           The operation was successful.
99
100       X509_V_ERR_UNSPECIFIED: unspecified certificate verification error
101           Unspecified error; should not happen.
102
103       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
110       X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
111           The CRL of a certificate could not be found.
112
113       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
120       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
126       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
131       X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
132           The signature of the certificate is invalid.
133
134       X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
135           The signature of the CRL is invalid.
136
137       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
141       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
145       X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
146           The CRL is not yet valid.
147
148       X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
149           The CRL has expired.
150
151       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
155       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
159       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
163       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
167       X509_V_ERR_OUT_OF_MEM: out of memory
168           An error occurred trying to allocate memory.
169
170       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
174       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
180       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
185       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
191       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
195       X509_V_ERR_CERT_REVOKED: certificate revoked
196           The certificate has been revoked.
197
198       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
202       X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
203           The basicConstraints path-length parameter has been exceeded.
204
205       X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose
206           The target certificate cannot be used for the specified purpose.
207
208       X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
209           The root CA is not marked as trusted for the specified purpose.
210
211       X509_V_ERR_CERT_REJECTED: certificate rejected
212           The root CA is marked to reject the specified purpose.
213
214       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
219       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
225       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
231       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
236       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
242       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
248       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
252       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
256       X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature
257           Some feature of a certificate extension is not supported. Unused.
258
259       X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation
260           A name constraint violation occurred in the permitted subtrees.
261
262       X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation
263           A name constraint violation occurred in the excluded subtrees.
264
265       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
270       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
276       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
283       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
287       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
291       X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER: unable to get CRL issuer
292       certificate
293           Unable to get CRL issuer certificate.
294
295       X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION: unhandled critical extension
296           Unhandled critical extension.
297
298       X509_V_ERR_KEYUSAGE_NO_CRL_SIGN: key usage does not include CRL signing
299           Key usage does not include CRL signing.
300
301       X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION: unhandled critical CRL
302       extension
303           Unhandled critical CRL extension.
304
305       X509_V_ERR_INVALID_NON_CA: invalid non-CA certificate (has CA markings)
306           Invalid non-CA certificate has CA markings.
307
308       X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED: proxy path length constraint
309       exceeded
310           Proxy path length constraint exceeded.
311
312       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
317       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
322       X509_V_ERR_UNNESTED_RESOURCE: RFC 3779 resource not subset of parent's
323       resources
324           See RFC 3779 for details.
325
326       X509_V_ERR_UNSUPPORTED_NAME_SYNTAX: unsupported or invalid name syntax
327           Unsupported or invalid name syntax.
328
329       X509_V_ERR_PATH_LOOP: path loop
330           Path loop.
331
332       X509_V_ERR_HOSTNAME_MISMATCH: hostname mismatch
333           Hostname mismatch.
334
335       X509_V_ERR_EMAIL_MISMATCH: email address mismatch
336           Email address mismatch.
337
338       X509_V_ERR_IP_ADDRESS_MISMATCH: IP address mismatch
339           IP address mismatch.
340
341       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
346       X509_V_ERR_EE_KEY_TOO_SMALL: EE certificate key too weak
347           EE certificate key too weak.
348
349       X509_V_ERR_CA_KEY_TOO_SMALL: CA certificate key too weak
350           CA certificate key too weak.
351
352       X509_V_ERR_CA_MD_TOO_WEAK: CA signature digest algorithm too weak
353           CA signature digest algorithm too weak.
354
355       X509_V_ERR_INVALID_CALL: invalid certificate verification context
356           Invalid certificate verification context.
357
358       X509_V_ERR_STORE_LOOKUP: issuer certificate lookup error
359           Issuer certificate lookup error.
360
361       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
365       X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION: proxy subject name violation
366           Proxy subject name violation.
367
368       X509_V_ERR_OCSP_VERIFY_NEEDED: OCSP verification needed
369           Returned by the verify callback to indicate an OCSP verification is
370           needed.
371
372       X509_V_ERR_OCSP_VERIFY_FAILED: OCSP verification failed
373           Returned by the verify callback to indicate OCSP verification
374           failed.
375
376       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
380       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
384       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

NOTES

390       The above functions should be used instead of directly referencing the
391       fields in the X509_VERIFY_CTX structure.
392
393       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
398       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

BUGS

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

SEE ALSO

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
415       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>.
419
420
421
4223.0.5                             2022-07-05   X509_STORE_CTX_GET_ERROR(3ossl)
Impressum