]>
Commit | Line | Data |
---|---|---|
53246488 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
f0e0fd51 | 5 | X509_STORE_CTX_get_error, X509_STORE_CTX_set_error, |
51227177 | 6 | X509_STORE_CTX_get_error_depth, X509_STORE_CTX_set_error_depth, |
c9654873 VD |
7 | X509_STORE_CTX_get_current_cert, X509_STORE_CTX_set_current_cert, |
8 | X509_STORE_CTX_get0_cert, X509_STORE_CTX_get1_chain, | |
9 | X509_verify_cert_error_string - get or set certificate verification status | |
10 | information | |
53246488 DSH |
11 | |
12 | =head1 SYNOPSIS | |
13 | ||
1e6b8d39 | 14 | #include <openssl/x509.h> |
53246488 | 15 | |
51227177 | 16 | int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx); |
c9654873 | 17 | void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx, int s); |
51227177 VD |
18 | int X509_STORE_CTX_get_error_depth(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(X509_STORE_CTX *ctx); | |
c9654873 | 21 | void X509_STORE_CTX_set_current_cert(X509_STORE_CTX *ctx, X509 *x); |
51227177 | 22 | X509 *X509_STORE_CTX_get0_cert(X509_STORE_CTX *ctx); |
53246488 DSH |
23 | |
24 | STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx); | |
25 | ||
1e6b8d39 DSH |
26 | const char *X509_verify_cert_error_string(long n); |
27 | ||
53246488 DSH |
28 | =head1 DESCRIPTION |
29 | ||
30 | These functions are typically called after X509_verify_cert() has indicated | |
31 | an error or in a verification callback to determine the nature of an error. | |
32 | ||
33 | X509_STORE_CTX_get_error() returns the error code of B<ctx>, see | |
34 | the B<ERROR CODES> section for a full description of all error codes. | |
35 | ||
36 | X509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. For example | |
37 | it might be used in a verification callback to set an error based on additional | |
38 | checks. | |
39 | ||
40 | X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a | |
41 | non-negative integer representing where in the certificate chain the error | |
478b50cf | 42 | occurred. If it is zero it occurred in the end entity certificate, one if |
53246488 DSH |
43 | it is the certificate which signed the end entity certificate and so on. |
44 | ||
51227177 VD |
45 | X509_STORE_CTX_set_error_depth() sets the error B<depth>. |
46 | This can be used in combination with X509_STORE_CTX_set_error() to set the | |
47 | depth at which an error condition was detected. | |
48 | ||
53246488 DSH |
49 | X509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which |
50 | caused the error or B<NULL> if no certificate is relevant. | |
51 | ||
c9654873 VD |
52 | X509_STORE_CTX_set_current_cert() sets the certificate B<x> in B<ctx> which |
53 | caused the error. | |
54 | This value is not intended to remain valid for very long, and remains owned by | |
55 | the caller. | |
56 | It may be examined by a verification callback invoked to handle each error | |
57 | encountered during chain verification and is no longer required after such a | |
58 | callback. | |
59 | If a callback wishes the save the certificate for use after it returns, it | |
60 | needs to increment its reference count via L<X509_up_ref(3)>. | |
61 | Once such a I<saved> certificate is no longer needed it can be freed with | |
62 | L<X509_free(3)>. | |
63 | ||
8162f6f5 RS |
64 | X509_STORE_CTX_get0_cert() retrieves an internal pointer to the |
65 | certificate being verified by the B<ctx>. | |
c9654873 | 66 | |
53246488 DSH |
67 | X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous |
68 | call to X509_verify_cert() is successful. If the call to X509_verify_cert() | |
69 | is B<not> successful the returned chain may be incomplete or invalid. The | |
70 | returned chain persists after the B<ctx> structure is freed, when it is | |
71 | no longer needed it should be free up using: | |
72 | ||
2947af32 | 73 | sk_X509_pop_free(chain, X509_free); |
53246488 | 74 | |
1e6b8d39 DSH |
75 | X509_verify_cert_error_string() returns a human readable error string for |
76 | verification error B<n>. | |
77 | ||
53246488 DSH |
78 | =head1 RETURN VALUES |
79 | ||
1e6b8d39 | 80 | X509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code. |
53246488 DSH |
81 | |
82 | X509_STORE_CTX_get_error_depth() returns a non-negative error depth. | |
83 | ||
186bb907 | 84 | X509_STORE_CTX_get_current_cert() returns the certificate which caused the |
53246488 DSH |
85 | error or B<NULL> if no certificate is relevant to the error. |
86 | ||
1e6b8d39 DSH |
87 | X509_verify_cert_error_string() returns a human readable error string for |
88 | verification error B<n>. | |
89 | ||
53246488 DSH |
90 | =head1 ERROR CODES |
91 | ||
1e6b8d39 DSH |
92 | A list of error codes and messages is shown below. Some of the |
93 | error codes are defined but currently never returned: these are described as | |
94 | "unused". | |
53246488 DSH |
95 | |
96 | =over 4 | |
97 | ||
6c17629f | 98 | =item B<X509_V_OK: ok> |
53246488 DSH |
99 | |
100 | the operation was successful. | |
101 | ||
102 | =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> | |
103 | ||
104 | the issuer certificate could not be found: this occurs if the issuer certificate | |
105 | of an untrusted certificate cannot be found. | |
106 | ||
107 | =item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> | |
108 | ||
109 | the CRL of a certificate could not be found. | |
110 | ||
111 | =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> | |
112 | ||
113 | the certificate signature could not be decrypted. This means that the actual | |
114 | signature value could not be determined rather than it not matching the | |
115 | expected value, this is only meaningful for RSA keys. | |
116 | ||
117 | =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> | |
118 | ||
119 | the CRL signature could not be decrypted: this means that the actual signature | |
120 | value could not be determined rather than it not matching the expected value. | |
121 | Unused. | |
122 | ||
123 | =item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> | |
124 | ||
125 | the public key in the certificate SubjectPublicKeyInfo could not be read. | |
126 | ||
127 | =item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> | |
128 | ||
129 | the signature of the certificate is invalid. | |
130 | ||
131 | =item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> | |
132 | ||
133 | the signature of the certificate is invalid. | |
134 | ||
135 | =item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> | |
136 | ||
137 | the certificate is not yet valid: the notBefore date is after the current time. | |
138 | ||
139 | =item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> | |
140 | ||
141 | the certificate has expired: that is the notAfter date is before the current time. | |
142 | ||
143 | =item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> | |
144 | ||
145 | the CRL is not yet valid. | |
146 | ||
147 | =item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> | |
148 | ||
149 | the CRL has expired. | |
150 | ||
151 | =item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> | |
152 | ||
153 | the certificate notBefore field contains an invalid time. | |
154 | ||
155 | =item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> | |
156 | ||
157 | the certificate notAfter field contains an invalid time. | |
158 | ||
159 | =item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field> | |
160 | ||
161 | the CRL lastUpdate field contains an invalid time. | |
162 | ||
163 | =item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field> | |
164 | ||
165 | the CRL nextUpdate field contains an invalid time. | |
166 | ||
167 | =item B<X509_V_ERR_OUT_OF_MEM: out of memory> | |
168 | ||
169 | an error occurred trying to allocate memory. This should never happen. | |
170 | ||
171 | =item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> | |
172 | ||
173 | the passed certificate is self signed and the same certificate cannot be found | |
174 | in the list of trusted certificates. | |
175 | ||
176 | =item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> | |
177 | ||
178 | the certificate chain could be built up using the untrusted certificates but | |
179 | the root could not be found locally. | |
180 | ||
181 | =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> | |
182 | ||
183 | the issuer certificate of a locally looked up certificate could not be found. | |
184 | This normally means the list of trusted certificates is not complete. | |
185 | ||
186 | =item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> | |
187 | ||
188 | no signatures could be verified because the chain contains only one certificate | |
189 | and it is not self signed. | |
190 | ||
191 | =item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> | |
192 | ||
193 | the certificate chain length is greater than the supplied maximum depth. Unused. | |
194 | ||
195 | =item B<X509_V_ERR_CERT_REVOKED: certificate revoked> | |
196 | ||
197 | the certificate has been revoked. | |
198 | ||
199 | =item B<X509_V_ERR_INVALID_CA: invalid CA certificate> | |
200 | ||
201 | a CA certificate is invalid. Either it is not a CA or its extensions are not | |
202 | consistent with the supplied purpose. | |
203 | ||
204 | =item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> | |
205 | ||
0ad69cd6 | 206 | the basicConstraints path-length parameter has been exceeded. |
53246488 DSH |
207 | |
208 | =item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> | |
209 | ||
210 | the supplied certificate cannot be used for the specified purpose. | |
211 | ||
212 | =item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> | |
213 | ||
214 | the root CA is not marked as trusted for the specified purpose. | |
215 | ||
216 | =item B<X509_V_ERR_CERT_REJECTED: certificate rejected> | |
217 | ||
218 | the root CA is marked to reject the specified purpose. | |
219 | ||
220 | =item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> | |
221 | ||
222 | the current candidate issuer certificate was rejected because its subject name | |
223 | did not match the issuer name of the current certificate. This is only set | |
224 | if issuer check debugging is enabled it is used for status notification and | |
225 | is B<not> in itself an error. | |
226 | ||
227 | =item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch> | |
228 | ||
229 | the current candidate issuer certificate was rejected because its subject key | |
230 | identifier was present and did not match the authority key identifier current | |
231 | certificate. This is only set if issuer check debugging is enabled it is used | |
232 | for status notification and is B<not> in itself an error. | |
233 | ||
234 | =item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch> | |
235 | ||
236 | the current candidate issuer certificate was rejected because its issuer name | |
237 | and serial number was present and did not match the authority key identifier of | |
238 | the current certificate. This is only set if issuer check debugging is enabled | |
239 | it is used for status notification and is B<not> in itself an error. | |
240 | ||
241 | =item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing> | |
242 | ||
243 | the current candidate issuer certificate was rejected because its keyUsage | |
244 | extension does not permit certificate signing. This is only set if issuer check | |
245 | debugging is enabled it is used for status notification and is B<not> in itself | |
246 | an error. | |
247 | ||
1e6b8d39 DSH |
248 | =item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension> |
249 | ||
250 | A certificate extension had an invalid value (for example an incorrect | |
251 | encoding) or some value inconsistent with other extensions. | |
252 | ||
253 | ||
254 | =item B<X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate policy extension> | |
255 | ||
256 | A certificate policies extension had an invalid value (for example an incorrect | |
257 | encoding) or some value inconsistent with other extensions. This error only | |
258 | occurs if policy processing is enabled. | |
259 | ||
260 | =item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy> | |
261 | ||
262 | The verification flags were set to require and explicit policy but none was | |
263 | present. | |
264 | ||
265 | =item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope> | |
266 | ||
267 | The only CRLs that could be found did not match the scope of the certificate. | |
268 | ||
269 | =item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature> | |
270 | ||
271 | Some feature of a certificate extension is not supported. Unused. | |
272 | ||
273 | =item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation> | |
274 | ||
478b50cf | 275 | A name constraint violation occurred in the permitted subtrees. |
1e6b8d39 DSH |
276 | |
277 | =item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation> | |
278 | ||
478b50cf | 279 | A name constraint violation occurred in the excluded subtrees. |
1e6b8d39 DSH |
280 | |
281 | =item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported> | |
282 | ||
283 | A certificate name constraints extension included a minimum or maximum field: | |
284 | this is not supported. | |
285 | ||
286 | =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type> | |
287 | ||
288 | An unsupported name constraint type was encountered. OpenSSL currently only | |
289 | supports directory name, DNS name, email and URI types. | |
290 | ||
291 | =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name constraint syntax> | |
292 | ||
293 | The format of the name constraint is not recognised: for example an email | |
294 | address format of a form not mentioned in RFC3280. This could be caused by | |
295 | a garbage extension or some new feature not currently supported. | |
296 | ||
297 | =item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error> | |
298 | ||
478b50cf | 299 | An error occurred when attempting to verify the CRL path. This error can only |
1e6b8d39 DSH |
300 | happen if extended CRL checking is enabled. |
301 | ||
53246488 DSH |
302 | =item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> |
303 | ||
304 | an application specific error. This will never be returned unless explicitly | |
305 | set by an application. | |
306 | ||
5cc27077 NA |
307 | =back |
308 | ||
53246488 DSH |
309 | =head1 NOTES |
310 | ||
311 | The above functions should be used instead of directly referencing the fields | |
312 | in the B<X509_VERIFY_CTX> structure. | |
313 | ||
314 | In versions of OpenSSL before 1.0 the current certificate returned by | |
315 | X509_STORE_CTX_get_current_cert() was never B<NULL>. Applications should | |
316 | check the return value before printing out any debugging information relating | |
317 | to the current certificate. | |
318 | ||
1e6b8d39 DSH |
319 | If an unrecognised error code is passed to X509_verify_cert_error_string() the |
320 | numerical value of the unknown code is returned in a static buffer. This is not | |
321 | thread safe but will never happen unless an invalid code is passed. | |
53246488 DSH |
322 | |
323 | =head1 SEE ALSO | |
324 | ||
c9654873 VD |
325 | L<X509_verify_cert(3)>, |
326 | L<X509_up_ref(3)>, | |
327 | L<X509_free(3)>. | |
53246488 | 328 | |
e2f92610 RS |
329 | =head1 COPYRIGHT |
330 | ||
331 | Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. | |
332 | ||
4746f25a | 333 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
334 | this file except in compliance with the License. You can obtain a copy |
335 | in the file LICENSE in the source distribution or at | |
336 | L<https://www.openssl.org/source/license.html>. | |
337 | ||
338 | =cut |