1=pod
2
3=head1 NAME
4
5X509_STORE_CTX_get_error, X509_STORE_CTX_set_error,
6X509_STORE_CTX_get_error_depth, X509_STORE_CTX_set_error_depth,
7X509_STORE_CTX_get_current_cert, X509_STORE_CTX_set_current_cert,
8X509_STORE_CTX_get0_cert, X509_STORE_CTX_get1_chain,
9X509_verify_cert_error_string - get or set certificate verification status
10information
11
12=head1 SYNOPSIS
13
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
28=head1 DESCRIPTION
29
30These functions are typically called after certificate or chain verification
31using L<X509_verify_cert(3)> or L<X509_STORE_CTX_verify(3)> has indicated
32an error or in a verification callback to determine the nature of an error.
33
34X509_STORE_CTX_get_error() returns the error code of I<ctx>.
35See the L</ERROR CODES> section for a full description of all error codes.
36It may return a code != X509_V_OK even if X509_verify_cert() did not indicate
37an error, likely because a verification callback function has waived the error.
38
39X509_STORE_CTX_set_error() sets the error code of I<ctx> to I<s>. For example
40it might be used in a verification callback to set an error based on additional
41checks.
42
43X509_STORE_CTX_get_error_depth() returns the I<depth> of the error. This is a
44nonnegative integer representing where in the certificate chain the error
45occurred. If it is zero it occurred in the end entity certificate, one if
46it is the certificate which signed the end entity certificate and so on.
47
48X509_STORE_CTX_set_error_depth() sets the error I<depth>.
49This can be used in combination with X509_STORE_CTX_set_error() to set the
50depth at which an error condition was detected.
51
52X509_STORE_CTX_get_current_cert() returns the current certificate in
53I<ctx>. If an error occurred, the current certificate will be the one
54that is most closely related to the error, or possibly NULL if no such
55certificate is relevant.
56
57X509_STORE_CTX_set_current_cert() sets the certificate I<x> in I<ctx> which
58caused the error.
59This value is not intended to remain valid for very long, and remains owned by
60the caller.
61It may be examined by a verification callback invoked to handle each error
62encountered during chain verification and is no longer required after such a
63callback.
64If a callback wishes the save the certificate for use after it returns, it
65needs to increment its reference count via L<X509_up_ref(3)>.
66Once such a I<saved> certificate is no longer needed it can be freed with
67L<X509_free(3)>.
68
69X509_STORE_CTX_get0_cert() retrieves an internal pointer to the
70certificate being verified by the I<ctx>.
71
72X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous
73verification is successful. Otherwise the returned chain may be incomplete or
74invalid.  The returned chain persists after the I<ctx> structure is freed.
75When it is no longer needed it should be free up using:
76
77 sk_X509_pop_free(chain, X509_free);
78
79X509_verify_cert_error_string() returns a human readable error string for
80verification error I<n>.
81
82=head1 RETURN VALUES
83
84X509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code.
85
86X509_STORE_CTX_get_error_depth() returns a nonnegative error depth.
87
88X509_STORE_CTX_get_current_cert() returns the certificate which caused the
89error or NULL if no certificate is relevant to the error.
90
91X509_verify_cert_error_string() returns a human readable error string for
92verification error I<n>.
93
94=head1 ERROR CODES
95
96A list of error codes and messages is shown below.  Some of the
97error codes are defined but currently never returned: these are described as
98"unused".
99
100=over 4
101
102=item B<X509_V_OK: ok>
103
104The operation was successful.
105
106=item B<X509_V_ERR_UNSPECIFIED: unspecified certificate verification error>
107
108Unspecified error; should not happen.
109
110=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
111
112The issuer certificate of a locally looked up certificate could not be found.
113This normally means the list of trusted certificates is not complete.
114To allow any certificate (not only a self-signed one) in the trust store
115to terminate the chain the B<X509_V_FLAG_PARTIAL_CHAIN> flag may be set.
116
117=item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
118
119The CRL of a certificate could not be found.
120
121=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE:
122unable to decrypt certificate's signature>
123
124The certificate signature could not be decrypted. This means that the actual
125signature value could not be determined rather than it not matching the
126expected value, this is only meaningful for RSA keys.
127
128=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE:
129unable to decrypt CRL's signature>
130
131The CRL signature could not be decrypted: this means that the actual signature
132value could not be determined rather than it not matching the expected value.
133Unused.
134
135=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY:
136unable to decode issuer public key>
137
138The public key in the certificate C<SubjectPublicKeyInfo> field could
139not be read.
140
141=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
142
143The signature of the certificate is invalid.
144
145=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
146
147The signature of the CRL is invalid.
148
149=item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
150
151The certificate is not yet valid: the C<notBefore> date is after the
152current time.
153
154=item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired>
155
156The certificate has expired: that is the C<notAfter> date is before the
157current time.
158
159=item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
160
161The CRL is not yet valid.
162
163=item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
164
165The CRL has expired.
166
167=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD:
168format error in certificate's notBefore field>
169
170The certificate C<notBefore> field contains an invalid time.
171
172=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD:
173format error in certificate's notAfter field>
174
175The certificate C<notAfter> field contains an invalid time.
176
177=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD:
178format error in CRL's lastUpdate field>
179
180The CRL B<lastUpdate> field contains an invalid time.
181
182=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD:
183format error in CRL's nextUpdate field>
184
185The CRL C<nextUpdate> field contains an invalid time.
186
187=item B<X509_V_ERR_OUT_OF_MEM: out of memory>
188
189An error occurred trying to allocate memory.
190
191=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self-signed certificate>
192
193The passed certificate is self-signed and the same certificate cannot be found
194in the list of trusted certificates.
195
196=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN:
197self-signed certificate in certificate chain>
198
199The certificate chain could be built up using the untrusted certificates
200but no suitable trust anchor (which typically is a self-signed root certificate)
201could be found in the trust store.
202
203=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY:
204unable to get local issuer certificate>
205
206The issuer certificate could not be found: this occurs if the issuer certificate
207of an untrusted certificate cannot be found.
208
209=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE:
210unable to verify the first certificate>
211
212No signatures could be verified because the chain contains only one certificate
213and it is not self-signed and the B<X509_V_FLAG_PARTIAL_CHAIN> flag is not set.
214
215=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
216
217The certificate chain length is greater than the supplied maximum depth.
218
219=item B<X509_V_ERR_CERT_REVOKED: certificate revoked>
220
221The certificate has been revoked.
222
223=item B<X509_V_ERR_NO_ISSUER_PUBLIC_KEY:
224 issuer certificate doesn't have a public key>
225
226The issuer certificate does not have a public key.
227
228=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
229
230The basicConstraints path-length parameter has been exceeded.
231
232=item B<X509_V_ERR_INVALID_PURPOSE: unsuitable certificate purpose>
233
234The target certificate cannot be used for the specified purpose.
235
236=item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
237
238The root CA is not marked as trusted for the specified purpose.
239
240=item B<X509_V_ERR_CERT_REJECTED: certificate rejected>
241
242The root CA is marked to reject the specified purpose.
243
244=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
245
246The current candidate issuer certificate was rejected because its subject name
247did not match the issuer name of the current certificate.
248
249=item B<X509_V_ERR_AKID_SKID_MISMATCH:
250authority and subject key identifier mismatch>
251
252The current candidate issuer certificate was rejected because its subject key
253identifier was present and did not match the authority key identifier current
254certificate.
255
256=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH:
257authority and issuer serial number mismatch>
258
259The current candidate issuer certificate was rejected because its issuer name
260and serial number was present and did not match the authority key identifier of
261the current certificate.
262
263=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:
264key usage does not include certificate signing>
265
266The current candidate issuer certificate was rejected because its C<keyUsage>
267extension does not permit certificate signing.
268
269=item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER:
270unable to get CRL issuer certificate>
271
272Unable to get CRL issuer certificate.
273
274=item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION: unhandled critical extension>
275
276Unhandled critical extension.
277
278=item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN: key usage does not include CRL signing>
279
280Key usage does not include CRL signing.
281
282=item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION: unhandled critical CRL extension>
283
284Unhandled critical CRL extension.
285
286=item B<X509_V_ERR_INVALID_NON_CA: invalid non-CA certificate (has CA markings)>
287
288Invalid non-CA certificate has CA markings.
289
290=item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED:
291proxy path length constraint exceeded>
292
293Proxy path length constraint exceeded.
294
295=item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE:
296key usage does not include digital signature>
297
298Key usage does not include digital signature, and therefore cannot sign
299certificates.
300
301=item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED:
302 proxy certificates not allowed, please set the appropriate flag>
303
304Proxy certificates not allowed unless the B<X509_V_FLAG_ALLOW_PROXY_CERTS> flag
305is set.
306
307=item B<X509_V_ERR_INVALID_EXTENSION:
308invalid or inconsistent certificate extension>
309
310A certificate extension had an invalid value (for example an incorrect
311encoding) or some value inconsistent with other extensions.
312
313=item B<X509_V_ERR_INVALID_POLICY_EXTENSION:
314invalid or inconsistent certificate policy extension>
315
316A certificate policies extension had an invalid value (for example an incorrect
317encoding) or some value inconsistent with other extensions. This error only
318occurs if policy processing is enabled.
319
320=item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy>
321
322The verification flags were set to require and explicit policy but none was
323present.
324
325=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: different CRL scope>
326
327The only CRLs that could be found did not match the scope of the certificate.
328
329=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: unsupported extension feature>
330
331Some feature of a certificate extension is not supported. Unused.
332
333=item B<X509_V_ERR_UNNESTED_RESOURCE: RFC 3779 resource not subset of parent's resources>
334
335See RFC 3779 for details.
336
337=item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation>
338
339A name constraint violation occurred in the permitted subtrees.
340
341=item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation>
342
343A name constraint violation occurred in the excluded subtrees.
344
345=item B<X509_V_ERR_SUBTREE_MINMAX:
346name constraints minimum and maximum not supported>
347
348A certificate name constraints extension included a minimum or maximum field:
349this is not supported.
350
351=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
352
353An application specific error. This will never be returned unless explicitly
354set by an application callback.
355
356=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE:
357unsupported name constraint type>
358
359An unsupported name constraint type was encountered. OpenSSL currently only
360supports directory name, DNS name, email and URI types.
361
362=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX:
363unsupported or invalid name constraint syntax>
364
365The format of the name constraint is not recognised: for example an email
366address format of a form not mentioned in RFC3280. This could be caused by
367a garbage extension or some new feature not currently supported.
368
369=item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX: unsupported or invalid name syntax>
370
371Unsupported or invalid name syntax.
372
373=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error>
374
375An error occurred when attempting to verify the CRL path. This error can only
376happen if extended CRL checking is enabled.
377
378=item B<X509_V_ERR_PATH_LOOP: path loop>
379
380Path loop.
381
382=item B<X509_V_ERR_HOSTNAME_MISMATCH: hostname mismatch>
383
384Hostname mismatch.
385
386=item B<X509_V_ERR_EMAIL_MISMATCH: email address mismatch>
387
388Email address mismatch.
389
390=item B<X509_V_ERR_IP_ADDRESS_MISMATCH: IP address mismatch>
391
392IP address mismatch.
393
394=item B<X509_V_ERR_DANE_NO_MATCH: no matching DANE TLSA records>
395
396DANE TLSA authentication is enabled, but no TLSA records matched the
397certificate chain.
398This error is only possible in L<openssl-s_client(1)>.
399
400=item B<X509_V_ERR_EE_KEY_TOO_SMALL: EE certificate key too weak>
401
402EE certificate key too weak.
403
404=item B<X509_V_ERR_CA_KEY_TOO_SMALL: CA certificate key too weak>
405
406CA certificate key too weak.
407
408=item B<X509_V_ERR_CA_MD_TOO_WEAK: CA signature digest algorithm too weak>
409
410CA signature digest algorithm too weak.
411
412=item B<X509_V_ERR_INVALID_CALL: invalid certificate verification context>
413
414Invalid certificate verification context.
415
416=item B<X509_V_ERR_STORE_LOOKUP: issuer certificate lookup error>
417
418Issuer certificate lookup error.
419
420=item B<X509_V_ERR_NO_VALID_SCTS: certificate transparency required, but no valid SCTs found>
421
422Certificate Transparency required, but no valid SCTs found.
423
424=item B<X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION: proxy subject name violation>
425
426Proxy subject name violation.
427
428=item B<X509_V_ERR_OCSP_VERIFY_NEEDED: OCSP verification needed>
429
430Returned by the verify callback to indicate an OCSP verification is needed.
431
432=item B<X509_V_ERR_OCSP_VERIFY_FAILED: OCSP verification failed>
433
434Returned by the verify callback to indicate OCSP verification failed.
435
436=item B<X509_V_ERR_OCSP_CERT_UNKNOWN: OCSP unknown cert>
437
438Returned by the verify callback to indicate that the certificate is not
439recognized by the OCSP responder.
440
441=item B<X509_V_ERR_UNSUPPORTED_SIGNATURE_ALGORITHM:
442unsupported signature algorithm>
443
444Cannot find certificate signature algorithm.
445
446=item B<X509_V_ERR_SIGNATURE_ALGORITHM_MISMATCH:
447subject signature algorithm and issuer public key algorithm mismatch>
448
449The issuer's public key is not of the type required by the signature in
450the subject's certificate.
451
452=item B<X509_V_ERR_SIGNATURE_ALGORITHM_INCONSISTENCY:
453cert info signature and signature algorithm mismatch>
454
455The algorithm given in the certificate info is inconsistent
456 with the one used for the certificate signature.
457
458=item B<X509_V_ERR_INVALID_CA: invalid CA certificate>
459
460A CA certificate is invalid. Either it is not a CA or its extensions are not
461consistent with the supplied purpose.
462
463=back
464
465=head1 NOTES
466
467The above functions should be used instead of directly referencing the fields
468in the B<X509_VERIFY_CTX> structure.
469
470In versions of OpenSSL before 1.0 the current certificate returned by
471X509_STORE_CTX_get_current_cert() was never NULL. Applications should
472check the return value before printing out any debugging information relating
473to the current certificate.
474
475If an unrecognised error code is passed to X509_verify_cert_error_string() the
476numerical value of the unknown code is returned in a static buffer. This is not
477thread safe but will never happen unless an invalid code is passed.
478
479=head1 BUGS
480
481Previous versions of this documentation swapped the meaning of the
482B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
483B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
484
485=head1 SEE ALSO
486
487L<X509_verify_cert(3)>, L<X509_STORE_CTX_verify(3)>,
488L<X509_up_ref(3)>,
489L<X509_free(3)>.
490
491=head1 COPYRIGHT
492
493Copyright 2009-2023 The OpenSSL Project Authors. All Rights Reserved.
494
495Licensed under the Apache License 2.0 (the "License").  You may not use
496this file except in compliance with the License.  You can obtain a copy
497in the file LICENSE in the source distribution or at
498L<https://www.openssl.org/source/license.html>.
499
500=cut
501