X509_STORE_CTX_get_error.pod revision 264331 
1=pod
2
3=head1 NAME
4
5X509_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
23These functions are typically called after X509_verify_cert() has indicated
24an error or in a verification callback to determine the nature of an error.
25
26X509_STORE_CTX_get_error() returns the error code of B<ctx>, see
27the B<ERROR CODES> section for a full description of all error codes.
28
29X509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. For example
30it might be used in a verification callback to set an error based on additional
31checks.
32
33X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a
34non-negative integer representing where in the certificate chain the error
35occurred. If it is zero it occured in the end entity certificate, one if
36it is the certificate which signed the end entity certificate and so on.
37
38X509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which
39caused the error or B<NULL> if no certificate is relevant.
40
41X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous
42call to X509_verify_cert() is successful. If the call to X509_verify_cert()
43is B<not> successful the returned chain may be incomplete or invalid. The
44returned chain persists after the B<ctx> structure is freed, when it is
45no longer needed it should be free up using:
46
47  sk_X509_pop_free(chain, X509_free);
48
49X509_verify_cert_error_string() returns a human readable error string for
50verification error B<n>.
51
52=head1 RETURN VALUES
53
54X509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code.
55
56X509_STORE_CTX_get_error_depth() returns a non-negative error depth.
57
58X509_STORE_CTX_get_current_cert() returns the cerificate which caused the
59error or B<NULL> if no certificate is relevant to the error.
60
61X509_verify_cert_error_string() returns a human readable error string for
62verification error B<n>.
63
64=head1 ERROR CODES
65
66A list of error codes and messages is shown below.  Some of the
67error 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
74the operation was successful.
75
76=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
77
78the issuer certificate could not be found: this occurs if the issuer certificate
79of an untrusted certificate cannot be found.
80
81=item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
82
83the 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
87the certificate signature could not be decrypted. This means that the actual
88signature value could not be determined rather than it not matching the
89expected 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
93the CRL signature could not be decrypted: this means that the actual signature
94value could not be determined rather than it not matching the expected value.
95Unused.
96
97=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key>
98
99the public key in the certificate SubjectPublicKeyInfo could not be read.
100
101=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
102
103the signature of the certificate is invalid.
104
105=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
106
107the signature of the certificate is invalid.
108
109=item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
110
111the 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
115the 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
119the CRL is not yet valid.
120
121=item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
122
123the CRL has expired.
124
125=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
126
127the 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
131the 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
135the 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
139the CRL nextUpdate field contains an invalid time.
140
141=item B<X509_V_ERR_OUT_OF_MEM: out of memory>
142
143an 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
147the passed certificate is self signed and the same certificate cannot be found
148in the list of trusted certificates.
149
150=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain>
151
152the certificate chain could be built up using the untrusted certificates but
153the 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
157the issuer certificate of a locally looked up certificate could not be found.
158This 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
162no signatures could be verified because the chain contains only one certificate
163and it is not self signed.
164
165=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
166
167the certificate chain length is greater than the supplied maximum depth. Unused.
168
169=item B<X509_V_ERR_CERT_REVOKED: certificate revoked>
170
171the certificate has been revoked.
172
173=item B<X509_V_ERR_INVALID_CA: invalid CA certificate>
174
175a CA certificate is invalid. Either it is not a CA or its extensions are not
176consistent with the supplied purpose.
177
178=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
179
180the basicConstraints pathlength parameter has been exceeded.
181
182=item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
183
184the supplied certificate cannot be used for the specified purpose.
185
186=item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
187
188the root CA is not marked as trusted for the specified purpose.
189
190=item B<X509_V_ERR_CERT_REJECTED: certificate rejected>
191
192the root CA is marked to reject the specified purpose.
193
194=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
195
196the current candidate issuer certificate was rejected because its subject name
197did not match the issuer name of the current certificate. This is only set
198if issuer check debugging is enabled it is used for status notification and
199is B<not> in itself an error.
200
201=item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch>
202
203the current candidate issuer certificate was rejected because its subject key
204identifier was present and did not match the authority key identifier current
205certificate. This is only set if issuer check debugging is enabled it is used
206for 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
210the current candidate issuer certificate was rejected because its issuer name
211and serial number was present and did not match the authority key identifier of
212the current certificate. This is only set if issuer check debugging is enabled
213it 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
217the current candidate issuer certificate was rejected because its keyUsage
218extension does not permit certificate signing. This is only set if issuer check
219debugging is enabled it is used for status notification and is B<not> in itself
220an error.
221
222=item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension>
223
224A certificate extension had an invalid value (for example an incorrect
225encoding) 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
230A certificate policies extension had an invalid value (for example an incorrect
231encoding) or some value inconsistent with other extensions. This error only
232occurs if policy processing is enabled.
233
234=item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy>
235
236The verification flags were set to require and explicit policy but none was
237present.
238
239=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope>
240
241The 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
245Some feature of a certificate extension is not supported. Unused.
246
247=item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation>
248
249A name constraint violation occured in the permitted subtrees.
250
251=item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation>
252
253A name constraint violation occured in the excluded subtrees.
254
255=item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported>
256
257A certificate name constraints extension included a minimum or maximum field:
258this is not supported.
259
260=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type>
261
262An unsupported name constraint type was encountered. OpenSSL currently only
263supports 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
267The format of the name constraint is not recognised: for example an email
268address format of a form not mentioned in RFC3280. This could be caused by
269a 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
273An error occured when attempting to verify the CRL path. This error can only
274happen if extended CRL checking is enabled.
275
276=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
277
278an application specific error. This will never be returned unless explicitly
279set by an application.
280
281=back
282
283=head1 NOTES
284
285The above functions should be used instead of directly referencing the fields
286in the B<X509_VERIFY_CTX> structure.
287
288In versions of OpenSSL before 1.0 the current certificate returned by
289X509_STORE_CTX_get_current_cert() was never B<NULL>. Applications should
290check the return value before printing out any debugging information relating
291to the current certificate.
292
293If an unrecognised error code is passed to X509_verify_cert_error_string() the
294numerical value of the unknown code is returned in a static buffer. This is not
295thread safe but will never happen unless an invalid code is passed.
296
297=head1 SEE ALSO
298
299L<X509_verify_cert(3)|X509_verify_cert(3)>
300
301=head1 HISTORY
302
303TBA
304
305=cut
306