]>
Commit | Line | Data |
---|---|---|
e05d6c7d DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
1a627771 RS |
5 | X509_STORE_CTX_get_cleanup, |
6 | X509_STORE_CTX_get_lookup_crls, | |
7 | X509_STORE_CTX_get_lookup_certs, | |
8 | X509_STORE_CTX_get_check_policy, | |
9 | X509_STORE_CTX_get_cert_crl, | |
10 | X509_STORE_CTX_get_check_crl, | |
11 | X509_STORE_CTX_get_get_crl, | |
12 | X509_STORE_CTX_get_check_revocation, | |
13 | X509_STORE_CTX_get_check_issued, | |
14 | X509_STORE_CTX_get_get_issuer, | |
f0e0fd51 | 15 | X509_STORE_CTX_get_verify_cb, |
121677b4 RS |
16 | X509_STORE_CTX_set_verify_cb, |
17 | X509_STORE_CTX_verify_cb | |
18 | - get and set verification callback | |
e05d6c7d DSH |
19 | |
20 | =head1 SYNOPSIS | |
21 | ||
22 | #include <openssl/x509_vfy.h> | |
23 | ||
f0e0fd51 RS |
24 | typedef int (*X509_STORE_CTX_verify_cb)(int, X509_STORE_CTX *); |
25 | ||
26 | X509_STORE_CTX_verify_cb X509_STORE_CTX_get_verify_cb(X509_STORE_CTX *ctx); | |
27 | ||
e05d6c7d | 28 | void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx, |
1bc74519 | 29 | X509_STORE_CTX_verify_cb verify_cb); |
e05d6c7d | 30 | |
0e82e0e1 RL |
31 | X509_STORE_CTX_get_issuer_fn X509_STORE_CTX_get_get_issuer(X509_STORE_CTX *ctx); |
32 | X509_STORE_CTX_check_issued_fn X509_STORE_CTX_get_check_issued(X509_STORE_CTX *ctx); | |
33 | X509_STORE_CTX_check_revocation_fn X509_STORE_CTX_get_check_revocation(X509_STORE_CTX *ctx); | |
34 | X509_STORE_CTX_get_crl_fn X509_STORE_CTX_get_get_crl(X509_STORE_CTX *ctx); | |
35 | X509_STORE_CTX_check_crl_fn X509_STORE_CTX_get_check_crl(X509_STORE_CTX *ctx); | |
36 | X509_STORE_CTX_cert_crl_fn X509_STORE_CTX_get_cert_crl(X509_STORE_CTX *ctx); | |
37 | X509_STORE_CTX_check_policy_fn X509_STORE_CTX_get_check_policy(X509_STORE_CTX *ctx); | |
38 | X509_STORE_CTX_lookup_certs_fn X509_STORE_CTX_get_lookup_certs(X509_STORE_CTX *ctx); | |
39 | X509_STORE_CTX_lookup_crls_fn X509_STORE_CTX_get_lookup_crls(X509_STORE_CTX *ctx); | |
40 | X509_STORE_CTX_cleanup_fn X509_STORE_CTX_get_cleanup(X509_STORE_CTX *ctx); | |
41 | ||
e05d6c7d DSH |
42 | =head1 DESCRIPTION |
43 | ||
44 | X509_STORE_CTX_set_verify_cb() sets the verification callback of B<ctx> to | |
45 | B<verify_cb> overwriting any existing callback. | |
46 | ||
47 | The verification callback can be used to customise the operation of certificate | |
48 | verification, either by overriding error conditions or logging errors for | |
49 | debugging purposes. | |
50 | ||
51 | However a verification callback is B<not> essential and the default operation | |
52 | is often sufficient. | |
53 | ||
54 | The B<ok> parameter to the callback indicates the value the callback should | |
0e82e0e1 | 55 | return to retain the default behaviour. If it is zero then an error condition |
e05d6c7d DSH |
56 | is indicated. If it is 1 then no error occurred. If the flag |
57 | B<X509_V_FLAG_NOTIFY_POLICY> is set then B<ok> is set to 2 to indicate the | |
58 | policy checking is complete. | |
59 | ||
60 | The B<ctx> parameter to the callback is the B<X509_STORE_CTX> structure that | |
61 | is performing the verification operation. A callback can examine this | |
62 | structure and receive additional information about the error, for example | |
63 | by calling X509_STORE_CTX_get_current_cert(). Additional application data can | |
64 | be passed to the callback via the B<ex_data> mechanism. | |
65 | ||
f0e0fd51 RS |
66 | X509_STORE_CTX_get_verify_cb() returns the value of the current callback |
67 | for the specific B<ctx>. | |
68 | ||
99d63d46 | 69 | X509_STORE_CTX_get_get_issuer(), |
0e82e0e1 RL |
70 | X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(), |
71 | X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(), | |
72 | X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(), | |
73 | X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls() | |
74 | and X509_STORE_CTX_get_cleanup() return the function pointers cached | |
75 | from the corresponding B<X509_STORE>, please see | |
76 | L<X509_STORE_set_verify(3)> for more information. | |
77 | ||
78 | ||
e05d6c7d DSH |
79 | =head1 WARNING |
80 | ||
81 | In general a verification callback should B<NOT> unconditionally return 1 in | |
82 | all circumstances because this will allow verification to succeed no matter | |
83 | what the error. This effectively removes all security from the application | |
84 | because B<any> certificate (including untrusted generated ones) will be | |
85 | accepted. | |
86 | ||
87 | =head1 NOTES | |
88 | ||
89 | The verification callback can be set and inherited from the parent structure | |
90 | performing the operation. In some cases (such as S/MIME verification) the | |
91 | B<X509_STORE_CTX> structure is created and destroyed internally and the | |
92 | only way to set a custom verification callback is by inheriting it from the | |
93 | associated B<X509_STORE>. | |
94 | ||
95 | =head1 RETURN VALUES | |
96 | ||
97 | X509_STORE_CTX_set_verify_cb() does not return a value. | |
98 | ||
99 | =head1 EXAMPLES | |
100 | ||
101 | Default callback operation: | |
102 | ||
2947af32 BB |
103 | int verify_callback(int ok, X509_STORE_CTX *ctx) { |
104 | return ok; | |
105 | } | |
e05d6c7d DSH |
106 | |
107 | Simple example, suppose a certificate in the chain is expired and we wish | |
108 | to continue after this error: | |
109 | ||
2947af32 BB |
110 | int verify_callback(int ok, X509_STORE_CTX *ctx) { |
111 | /* Tolerate certificate expiration */ | |
112 | if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED) | |
113 | return 1; | |
114 | /* Otherwise don't override */ | |
115 | return ok; | |
116 | } | |
e05d6c7d DSH |
117 | |
118 | More complex example, we don't wish to continue after B<any> certificate has | |
119 | expired just one specific case: | |
120 | ||
121 | int verify_callback(int ok, X509_STORE_CTX *ctx) | |
2947af32 BB |
122 | { |
123 | int err = X509_STORE_CTX_get_error(ctx); | |
124 | X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx); | |
e9b77246 | 125 | |
2947af32 BB |
126 | if (err == X509_V_ERR_CERT_HAS_EXPIRED) { |
127 | if (check_is_acceptable_expired_cert(err_cert) | |
128 | return 1; | |
129 | } | |
130 | return ok; | |
131 | } | |
e05d6c7d DSH |
132 | |
133 | Full featured logging callback. In this case the B<bio_err> is assumed to be | |
134 | a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using | |
135 | B<ex_data>. | |
1bc74519 | 136 | |
e05d6c7d | 137 | int verify_callback(int ok, X509_STORE_CTX *ctx) |
2947af32 BB |
138 | { |
139 | X509 *err_cert; | |
140 | int err, depth; | |
141 | ||
142 | err_cert = X509_STORE_CTX_get_current_cert(ctx); | |
143 | err = X509_STORE_CTX_get_error(ctx); | |
144 | depth = X509_STORE_CTX_get_error_depth(ctx); | |
145 | ||
146 | BIO_printf(bio_err, "depth=%d ", depth); | |
147 | if (err_cert) { | |
148 | X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert), | |
149 | 0, XN_FLAG_ONELINE); | |
150 | BIO_puts(bio_err, "\n"); | |
151 | } | |
152 | else | |
153 | BIO_puts(bio_err, "<no cert>\n"); | |
154 | if (!ok) | |
155 | BIO_printf(bio_err, "verify error:num=%d:%s\n", err, | |
156 | X509_verify_cert_error_string(err)); | |
157 | switch (err) { | |
158 | case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: | |
159 | BIO_puts(bio_err, "issuer= "); | |
160 | X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert), | |
161 | 0, XN_FLAG_ONELINE); | |
162 | BIO_puts(bio_err, "\n"); | |
163 | break; | |
164 | case X509_V_ERR_CERT_NOT_YET_VALID: | |
165 | case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: | |
166 | BIO_printf(bio_err, "notBefore="); | |
167 | ASN1_TIME_print(bio_err, X509_get_notBefore(err_cert)); | |
168 | BIO_printf(bio_err, "\n"); | |
169 | break; | |
170 | case X509_V_ERR_CERT_HAS_EXPIRED: | |
171 | case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: | |
172 | BIO_printf(bio_err, "notAfter="); | |
173 | ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert)); | |
174 | BIO_printf(bio_err, "\n"); | |
175 | break; | |
176 | case X509_V_ERR_NO_EXPLICIT_POLICY: | |
177 | policies_print(bio_err, ctx); | |
178 | break; | |
179 | } | |
180 | if (err == X509_V_OK && ok == 2) | |
181 | /* print out policies */ | |
182 | ||
183 | BIO_printf(bio_err, "verify return:%d\n", ok); | |
184 | return(ok); | |
185 | } | |
e05d6c7d DSH |
186 | |
187 | =head1 SEE ALSO | |
188 | ||
9b86974e RS |
189 | L<X509_STORE_CTX_get_error(3)> |
190 | L<X509_STORE_set_verify_cb_func(3)> | |
191 | L<X509_STORE_CTX_get_ex_new_index(3)> | |
e05d6c7d | 192 | |
0e82e0e1 RL |
193 | =head1 HISTORY |
194 | ||
fc5ecadd | 195 | The |
99d63d46 | 196 | X509_STORE_CTX_get_get_issuer(), |
0e82e0e1 RL |
197 | X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(), |
198 | X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(), | |
199 | X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(), | |
200 | X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls() | |
fc5ecadd | 201 | and X509_STORE_CTX_get_cleanup() functions were added in OpenSSL 1.1.0. |
0e82e0e1 | 202 | |
e2f92610 RS |
203 | =head1 COPYRIGHT |
204 | ||
205 | Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. | |
206 | ||
4746f25a | 207 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
208 | this file except in compliance with the License. You can obtain a copy |
209 | in the file LICENSE in the source distribution or at | |
210 | L<https://www.openssl.org/source/license.html>. | |
211 | ||
212 | =cut |