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