]>
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); | |
125 | if (err == X509_V_ERR_CERT_HAS_EXPIRED) { | |
126 | if (check_is_acceptable_expired_cert(err_cert) | |
127 | return 1; | |
128 | } | |
129 | return ok; | |
130 | } | |
e05d6c7d DSH |
131 | |
132 | Full featured logging callback. In this case the B<bio_err> is assumed to be | |
133 | a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using | |
134 | B<ex_data>. | |
1bc74519 | 135 | |
e05d6c7d | 136 | int verify_callback(int ok, X509_STORE_CTX *ctx) |
2947af32 BB |
137 | { |
138 | X509 *err_cert; | |
139 | int err, depth; | |
140 | ||
141 | err_cert = X509_STORE_CTX_get_current_cert(ctx); | |
142 | err = X509_STORE_CTX_get_error(ctx); | |
143 | depth = X509_STORE_CTX_get_error_depth(ctx); | |
144 | ||
145 | BIO_printf(bio_err, "depth=%d ", depth); | |
146 | if (err_cert) { | |
147 | X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert), | |
148 | 0, XN_FLAG_ONELINE); | |
149 | BIO_puts(bio_err, "\n"); | |
150 | } | |
151 | else | |
152 | BIO_puts(bio_err, "<no cert>\n"); | |
153 | if (!ok) | |
154 | BIO_printf(bio_err, "verify error:num=%d:%s\n", err, | |
155 | X509_verify_cert_error_string(err)); | |
156 | switch (err) { | |
157 | case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: | |
158 | BIO_puts(bio_err, "issuer= "); | |
159 | X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert), | |
160 | 0, XN_FLAG_ONELINE); | |
161 | BIO_puts(bio_err, "\n"); | |
162 | break; | |
163 | case X509_V_ERR_CERT_NOT_YET_VALID: | |
164 | case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: | |
165 | BIO_printf(bio_err, "notBefore="); | |
166 | ASN1_TIME_print(bio_err, X509_get_notBefore(err_cert)); | |
167 | BIO_printf(bio_err, "\n"); | |
168 | break; | |
169 | case X509_V_ERR_CERT_HAS_EXPIRED: | |
170 | case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: | |
171 | BIO_printf(bio_err, "notAfter="); | |
172 | ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert)); | |
173 | BIO_printf(bio_err, "\n"); | |
174 | break; | |
175 | case X509_V_ERR_NO_EXPLICIT_POLICY: | |
176 | policies_print(bio_err, ctx); | |
177 | break; | |
178 | } | |
179 | if (err == X509_V_OK && ok == 2) | |
180 | /* print out policies */ | |
181 | ||
182 | BIO_printf(bio_err, "verify return:%d\n", ok); | |
183 | return(ok); | |
184 | } | |
e05d6c7d DSH |
185 | |
186 | =head1 SEE ALSO | |
187 | ||
9b86974e RS |
188 | L<X509_STORE_CTX_get_error(3)> |
189 | L<X509_STORE_set_verify_cb_func(3)> | |
190 | L<X509_STORE_CTX_get_ex_new_index(3)> | |
e05d6c7d | 191 | |
0e82e0e1 RL |
192 | =head1 HISTORY |
193 | ||
99d63d46 | 194 | X509_STORE_CTX_get_get_issuer(), |
0e82e0e1 RL |
195 | X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(), |
196 | X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(), | |
197 | X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(), | |
198 | X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls() | |
60250017 | 199 | and X509_STORE_CTX_get_cleanup() were added in OpenSSL 1.1.0. |
0e82e0e1 | 200 | |
e2f92610 RS |
201 | =head1 COPYRIGHT |
202 | ||
203 | Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. | |
204 | ||
205 | Licensed under the OpenSSL license (the "License"). You may not use | |
206 | this file except in compliance with the License. You can obtain a copy | |
207 | in the file LICENSE in the source distribution or at | |
208 | L<https://www.openssl.org/source/license.html>. | |
209 | ||
210 | =cut |