| blob | 6d575139d5d2ca0cc0ec2be2ff4af452b49e29f0 |
1 .\" $OpenBSD: X509_STORE_CTX_get_error.3,v 1.10 2018/03/23 23:18:17 schwarze Exp $
2 .\" full merge up to:
3 .\" OpenSSL crypto/X509_STORE_CTX_get_error f0e0fd51 Apr 14 23:59:26 2016 -0400
4 .\" selective merge up to:
5 .\" OpenSSL man3/X509_STORE_CTX_get_error 2947af32 Nov 19 00:10:05 2016 +0100
6 .\" OpenSSL man3/X509_STORE_CTX_new 7643a172 Apr 21 13:35:51 2017 +0200
7 .\"
8 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
9 .\" Copyright (c) 2009, 2013, 2015, 2016 The OpenSSL Project.
10 .\" All rights reserved.
11 .\"
12 .\" Redistribution and use in source and binary forms, with or without
13 .\" modification, are permitted provided that the following conditions
14 .\" are met:
15 .\"
16 .\" 1. Redistributions of source code must retain the above copyright
17 .\" notice, this list of conditions and the following disclaimer.
18 .\"
19 .\" 2. Redistributions in binary form must reproduce the above copyright
20 .\" notice, this list of conditions and the following disclaimer in
21 .\" the documentation and/or other materials provided with the
22 .\" distribution.
23 .\"
24 .\" 3. All advertising materials mentioning features or use of this
25 .\" software must display the following acknowledgment:
26 .\" "This product includes software developed by the OpenSSL Project
27 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
28 .\"
29 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
30 .\" endorse or promote products derived from this software without
31 .\" prior written permission. For written permission, please contact
32 .\" openssl-core@openssl.org.
33 .\"
34 .\" 5. Products derived from this software may not be called "OpenSSL"
35 .\" nor may "OpenSSL" appear in their names without prior written
36 .\" permission of the OpenSSL Project.
37 .\"
38 .\" 6. Redistributions of any form whatsoever must retain the following
39 .\" acknowledgment:
40 .\" "This product includes software developed by the OpenSSL Project
41 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
42 .\"
43 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
44 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
45 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
46 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
47 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
48 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
49 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
50 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
51 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
52 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
53 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
54 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
55 .\"
56 .Dd $Mdocdate: March 23 2018 $
57 .Dt X509_STORE_CTX_GET_ERROR 3
58 .Os
59 .Sh NAME
60 .Nm X509_STORE_CTX_get_error ,
61 .Nm X509_STORE_CTX_set_error ,
62 .Nm X509_STORE_CTX_get_error_depth ,
63 .Nm X509_STORE_CTX_get_current_cert ,
64 .Nm X509_STORE_CTX_get0_cert ,
65 .Nm X509_STORE_CTX_get0_chain ,
66 .Nm X509_STORE_CTX_get1_chain ,
67 .Nm X509_verify_cert_error_string
68 .Nd get or set certificate verification status information
69 .Sh SYNOPSIS
70 .In openssl/x509.h
71 .Ft int
72 .Fo X509_STORE_CTX_get_error
73 .Fa "X509_STORE_CTX *ctx"
74 .Fc
75 .Ft void
76 .Fo X509_STORE_CTX_set_error
77 .Fa "X509_STORE_CTX *ctx"
78 .Fa "int s"
79 .Fc
80 .Ft int
81 .Fo X509_STORE_CTX_get_error_depth
82 .Fa "X509_STORE_CTX *ctx"
83 .Fc
84 .Ft X509 *
85 .Fo X509_STORE_CTX_get_current_cert
86 .Fa "X509_STORE_CTX *ctx"
87 .Fc
88 .Ft X509 *
89 .Fo X509_STORE_CTX_get0_cert
90 .Fa "X509_STORE_CTX *ctx"
91 .Fc
92 .Ft STACK_OF(X509) *
93 .Fo X509_STORE_CTX_get0_chain
94 .Fa "X509_STORE_CTX *ctx"
95 .Fc
96 .Ft STACK_OF(X509) *
97 .Fo X509_STORE_CTX_get1_chain
98 .Fa "X509_STORE_CTX *ctx"
99 .Fc
100 .Ft const char *
101 .Fo X509_verify_cert_error_string
102 .Fa "long n"
103 .Fc
104 .Sh DESCRIPTION
105 These functions are typically called after
106 .Xr X509_verify_cert 3
107 has indicated an error or in a verification callback to determine the
108 nature of an error.
109 .Pp
110 .Fn X509_STORE_CTX_get_error
111 returns the error code of
112 .Fa ctx .
113 See the
114 .Sy ERROR CODES
115 section for a full description of all error codes.
116 .Pp
117 .Fn X509_STORE_CTX_set_error
118 sets the error code of
119 .Fa ctx
120 to
121 .Fa s .
122 For example it might be used in a verification callback to set an error
123 based on additional checks.
124 .Pp
125 .Fn X509_STORE_CTX_get_error_depth
126 returns the depth of the error.
127 This is a non-negative integer representing where in the certificate
128 chain the error occurred.
129 If it is zero, it occurred in the end entity certificate, one if it is
130 the certificate which signed the end entity certificate, and so on.
131 .Pp
132 .Fn X509_STORE_CTX_get_current_cert
133 returns the certificate in
134 .Fa ctx
135 which caused the error or
136 .Dv NULL
137 if no certificate is relevant.
138 .Pp
139 .Fn X509_STORE_CTX_get0_chain
140 returns an internal pointer to a complete validate chain
141 if a previous call to
142 .Xr X509_verify_cert 3
143 was successful.
144 If the call to
145 .Xr X509_verify_cert 3
146 was not successful, the returned chain may be incomplete or invalid.
147 .Fn X509_STORE_CTX_get1_chain
148 returns a deep copy of the same chain which persists even after the
149 .Fa ctx
150 structure is freed.
151 When it is no longer needed, it should be freed using
152 .Fn sk_X509_pop_free chain X509_free .
153 .Pp
154 .Fn X509_verify_cert_error_string
155 returns a human readable error string for verification error
156 .Fa n .
157 .Pp
158 The above functions should be used instead of directly referencing the
159 fields in the
160 .Sy X509_VERIFY_CTX
161 structure.
162 .Pp
163 In versions of OpenSSL before 1.0, the current certificate returned by
164 .Fn X509_STORE_CTX_get_current_cert
165 was never
166 .Dv NULL .
167 Applications should check the return value before printing out any
168 debugging information relating to the current certificate.
169 .Pp
170 If an unrecognised error code is passed to
171 .Fn X509_verify_cert_error_string ,
172 the numerical value of the unknown code is returned in a static buffer.
173 This is not thread safe but will never happen unless an invalid code is
174 passed.
175 .Sh RETURN VALUES
176 .Fn X509_STORE_CTX_get_error
177 returns
178 .Dv X509_V_OK
179 or an error code.
180 .Pp
181 .Fn X509_STORE_CTX_get_error_depth
182 returns a non-negative error depth.
183 .Pp
184 .Fn X509_STORE_CTX_get_current_cert
185 returns the certificate which caused the error or
186 .Dv NULL
187 if no certificate is relevant to the error.
188 .Pp
189 .Fn X509_STORE_CTX_get0_cert
190 retrieves an internal pointer to the certificate being verified by
191 .Fa ctx .
192 .Pp
193 .Fn X509_STORE_CTX_get0_chain
194 and
195 .Fn X509_STORE_CTX_get1_chain
196 return a pointer to a stack of certificates or
197 .Dv NULL
198 if an error occurs.
199 .Pp
200 .Fn X509_verify_cert_error_string
201 returns a human readable error string for verification error
202 .Fa n .
203 .Sh ERROR CODES
204 A list of error codes and messages is shown below.
205 Some of the error codes are defined but currently never returned:
206 these are described as "unused".
207 .Bl -tag -width Ds
208 .It Dv X509_V_OK : No ok
209 The operation was successful.
210 .It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT : \
211 No unable to get issuer certificate
212 The issuer certificate could not be found: this occurs if the issuer
213 certificate of an untrusted certificate cannot be found.
214 .It Dv X509_V_ERR_UNABLE_TO_GET_CRL : No unable to get certificate CRL
215 The CRL of a certificate could not be found.
216 .It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE : \
217 No unable to decrypt certificate's signature
218 The certificate signature could not be decrypted.
219 This means that the actual signature value could not be determined
220 rather than it not matching the expected value.
221 This is only meaningful for RSA keys.
222 .It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE : \
223 No unable to decrypt CRL's signature
224 The CRL signature could not be decrypted: this means that the actual
225 signature value could not be determined rather than it not matching the
226 expected value.
227 Unused.
228 .It Dv X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY : \
229 No unable to decode issuer public key
230 The public key in the certificate
231 .Vt SubjectPublicKeyInfo
232 could not be read.
233 .It Dv X509_V_ERR_CERT_SIGNATURE_FAILURE : No certificate signature failure
234 The signature of the certificate is invalid.
235 .It Dv X509_V_ERR_CRL_SIGNATURE_FAILURE : No CRL signature failure
236 The signature of the certificate is invalid.
237 .It Dv X509_V_ERR_CERT_NOT_YET_VALID : No certificate is not yet valid
238 The certificate is not yet valid: the notBefore date is after the
239 current time.
240 .It Dv X509_V_ERR_CERT_HAS_EXPIRED : No certificate has expired
241 The certificate has expired: that is the notAfter date is before the
242 current time.
243 .It Dv X509_V_ERR_CRL_NOT_YET_VALID : No CRL is not yet valid
244 The CRL is not yet valid.
245 .It Dv X509_V_ERR_CRL_HAS_EXPIRED : No CRL has expired
246 The CRL has expired.
247 .It Dv X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD : \
248 No format error in certificate's notBefore field
249 The certificate notBefore field contains an invalid time.
250 .It Dv X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD : \
251 No format error in certificate's notAfter field
252 The certificate notAfter field contains an invalid time.
253 .It Dv X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD : \
254 No format error in CRL's lastUpdate field
255 The CRL lastUpdate field contains an invalid time.
256 .It Dv X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD : \
257 No format error in CRL's nextUpdate field
258 The CRL nextUpdate field contains an invalid time.
259 .It Dv X509_V_ERR_OUT_OF_MEM : No out of memory
260 An error occurred trying to allocate memory.
261 This should never happen.
262 .It Dv X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT : No self signed certificate
263 The passed certificate is self signed and the same certificate cannot be
264 found in the list of trusted certificates.
265 .It Dv X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN : \
266 No self signed certificate in certificate chain
267 The certificate chain could be built up using the untrusted certificates
268 but the root could not be found locally.
269 .It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY : \
270 No unable to get local issuer certificate
271 The issuer certificate of a locally looked up certificate could not be found.
272 This normally means the list of trusted certificates is not complete.
273 .It Dv X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE : \
274 No unable to verify the first certificate
275 No signatures could be verified because the chain contains only one
276 certificate and it is not self signed.
277 .It Dv X509_V_ERR_CERT_CHAIN_TOO_LONG : No certificate chain too long
278 The certificate chain length is greater than the supplied maximum depth.
279 Unused.
280 .It Dv X509_V_ERR_CERT_REVOKED : No certificate revoked
281 The certificate has been revoked.
282 .It Dv X509_V_ERR_INVALID_CA : No invalid CA certificate
283 A CA certificate is invalid.
284 Either it is not a CA or its extensions are not consistent with the
285 supplied purpose.
286 .It Dv X509_V_ERR_PATH_LENGTH_EXCEEDED : No path length constraint exceeded
287 The basicConstraints path-length parameter has been exceeded.
288 .It Dv X509_V_ERR_INVALID_PURPOSE : No unsupported certificate purpose
289 The supplied certificate cannot be used for the specified purpose.
290 .It Dv X509_V_ERR_CERT_UNTRUSTED : No certificate not trusted
291 The root CA is not marked as trusted for the specified purpose.
292 .It Dv X509_V_ERR_CERT_REJECTED : No certificate rejected
293 The root CA is marked to reject the specified purpose.
294 .It Dv X509_V_ERR_SUBJECT_ISSUER_MISMATCH : No subject issuer mismatch
295 The current candidate issuer certificate was rejected because its
296 subject name did not match the issuer name of the current certificate.
297 This is only set if issuer check debugging is enabled; it is used for
298 status notification and is
299 .Sy not
300 in itself an error.
301 .It Dv X509_V_ERR_AKID_SKID_MISMATCH : \
302 No authority and subject key identifier mismatch
303 The current candidate issuer certificate was rejected because its
304 subject key identifier was present and did not match the authority key
305 identifier current certificate.
306 This is only set if issuer check debugging is enabled; it is used for
307 status notification and is
308 .Sy not
309 in itself an error.
310 .It Dv X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH : \
311 Noauthority and issuer serial number mismatch
312 The current candidate issuer certificate was rejected because its issuer
313 name and serial number was present and did not match the authority key
314 identifier of the current certificate.
315 This is only set if issuer check debugging is enabled; it is used for
316 status notification and is
317 .Sy not
318 in itself an error.
319 .It Dv X509_V_ERR_KEYUSAGE_NO_CERTSIGN : \
320 No key usage does not include certificate signing
321 The current candidate issuer certificate was rejected because its
322 keyUsage extension does not permit certificate signing.
323 This is only set if issuer check debugging is enabled it is used for
324 status notification and is
325 .Sy not
326 in itself an error.
327 .It Dv X509_V_ERR_INVALID_EXTENSION : \
328 No invalid or inconsistent certificate extension
329 A certificate extension had an invalid value (for example an incorrect
330 encoding) or some value inconsistent with other extensions.
331 .It Dv X509_V_ERR_INVALID_POLICY_EXTENSION : \
332 No invalid or inconsistent certificate policy extension
333 A certificate policies extension had an invalid value (for example an
334 incorrect encoding) or some value inconsistent with other extensions.
335 This error only occurs if policy processing is enabled.
336 .It Dv X509_V_ERR_NO_EXPLICIT_POLICY : No no explicit policy
337 The verification flags were set to require an explicit policy but none
338 was present.
339 .It Dv X509_V_ERR_DIFFERENT_CRL_SCOPE : No different CRL scope
340 The only CRLs that could be found did not match the scope of the
341 certificate.
342 .It Dv X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE : \
343 No unsupported extension feature
344 Some feature of a certificate extension is not supported.
345 Unused.
346 .It Dv X509_V_ERR_PERMITTED_VIOLATION : No permitted subtree violation
347 A name constraint violation occurred in the permitted subtrees.
348 .It Dv X509_V_ERR_EXCLUDED_VIOLATION : No excluded subtree violation
349 A name constraint violation occurred in the excluded subtrees.
350 .It Dv X509_V_ERR_SUBTREE_MINMAX : \
351 No name constraints minimum and maximum not supported
352 A certificate name constraints extension included a minimum or maximum
353 field: this is not supported.
354 .It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE : \
355 No unsupported name constraint type
356 An unsupported name constraint type was encountered.
357 OpenSSL currently only supports directory name, DNS name, email and URI
358 types.
359 .It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX : \
360 No unsupported or invalid name constraint syntax
361 The format of the name constraint is not recognised: for example an
362 email address format of a form not mentioned in RFC 3280.
363 This could be caused by a garbage extension or some new feature not
364 currently supported.
365 .It Dv X509_V_ERR_CRL_PATH_VALIDATION_ERROR : No CRL path validation error
366 An error occurred when attempting to verify the CRL path.
367 This error can only happen if extended CRL checking is enabled.
368 .It Dv X509_V_ERR_APPLICATION_VERIFICATION : \
369 No application verification failure
370 An application specific error.
371 This will never be returned unless explicitly set by an application.
372 .El
373 .Sh SEE ALSO
374 .Xr X509_STORE_CTX_new 3 ,
375 .Xr X509_up_ref 3 ,
376 .Xr X509_verify_cert 3
377 .Sh HISTORY
378 .Fn X509_STORE_CTX_get_error ,
379 .Fn X509_STORE_CTX_set_error ,
380 .Fn X509_STORE_CTX_get_error_depth ,
381 .Fn X509_STORE_CTX_get_current_cert ,
382 and
383 .Fn X509_verify_cert_error_string
384 appeared before SSLeay 0.8 and have been available since
385 .Ox 2.4 .
386 .Pp
387 .Fn X509_STORE_CTX_get1_chain
388 first appeared in OpenSSL 0.9.5 and has been available since
389 .Ox 2.7 .
390 .Pp
391 .Fn X509_STORE_CTX_get0_cert
392 and
393 .Fn X509_STORE_CTX_get0_chain
394 first appeared in OpenSSL 1.1.0 and have been available since
395 .Ox 6.3 .