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