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