• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1=pod
2
3=head1 NAME
4
5X509_STORE_CTX_get_cleanup,
6X509_STORE_CTX_get_lookup_crls,
7X509_STORE_CTX_get_lookup_certs,
8X509_STORE_CTX_get_check_policy,
9X509_STORE_CTX_get_cert_crl,
10X509_STORE_CTX_get_check_crl,
11X509_STORE_CTX_get_get_crl,
12X509_STORE_CTX_get_check_revocation,
13X509_STORE_CTX_get_check_issued,
14X509_STORE_CTX_get_get_issuer,
15X509_STORE_CTX_get_verify_cb,
16X509_STORE_CTX_set_verify_cb,
17X509_STORE_CTX_verify_cb
18- get and set verification callback
19
20=head1 SYNOPSIS
21
22 #include <openssl/x509_vfy.h>
23
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
28 void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx,
29                                   X509_STORE_CTX_verify_cb verify_cb);
30
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
42=head1 DESCRIPTION
43
44X509_STORE_CTX_set_verify_cb() sets the verification callback of B<ctx> to
45B<verify_cb> overwriting any existing callback.
46
47The verification callback can be used to customise the operation of certificate
48verification, either by overriding error conditions or logging errors for
49debugging purposes.
50
51However, a verification callback is B<not> essential and the default operation
52is often sufficient.
53
54The B<ok> parameter to the callback indicates the value the callback should
55return to retain the default behaviour. If it is zero then an error condition
56is indicated. If it is 1 then no error occurred. If the flag
57B<X509_V_FLAG_NOTIFY_POLICY> is set then B<ok> is set to 2 to indicate the
58policy checking is complete.
59
60The B<ctx> parameter to the callback is the B<X509_STORE_CTX> structure that
61is performing the verification operation. A callback can examine this
62structure and receive additional information about the error, for example
63by calling X509_STORE_CTX_get_current_cert(). Additional application data can
64be passed to the callback via the B<ex_data> mechanism.
65
66X509_STORE_CTX_get_verify_cb() returns the value of the current callback
67for the specific B<ctx>.
68
69X509_STORE_CTX_get_get_issuer(),
70X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(),
71X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(),
72X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(),
73X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls()
74and X509_STORE_CTX_get_cleanup() return the function pointers cached
75from the corresponding B<X509_STORE>, please see
76L<X509_STORE_set_verify(3)> for more information.
77
78
79=head1 WARNINGS
80
81In general a verification callback should B<NOT> unconditionally return 1 in
82all circumstances because this will allow verification to succeed no matter
83what the error. This effectively removes all security from the application
84because B<any> certificate (including untrusted generated ones) will be
85accepted.
86
87=head1 NOTES
88
89The verification callback can be set and inherited from the parent structure
90performing the operation. In some cases (such as S/MIME verification) the
91B<X509_STORE_CTX> structure is created and destroyed internally and the
92only way to set a custom verification callback is by inheriting it from the
93associated B<X509_STORE>.
94
95=head1 RETURN VALUES
96
97X509_STORE_CTX_set_verify_cb() does not return a value.
98
99=head1 EXAMPLES
100
101Default callback operation:
102
103 int verify_callback(int ok, X509_STORE_CTX *ctx) {
104     return ok;
105 }
106
107Simple example, suppose a certificate in the chain is expired and we wish
108to continue after this error:
109
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 }
117
118More complex example, we don't wish to continue after B<any> certificate has
119expired just one specific case:
120
121 int verify_callback(int ok, X509_STORE_CTX *ctx)
122 {
123     int err = X509_STORE_CTX_get_error(ctx);
124     X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx);
125
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 }
132
133Full featured logging callback. In this case the B<bio_err> is assumed to be
134a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using
135B<ex_data>.
136
137 int verify_callback(int ok, X509_STORE_CTX *ctx)
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 }
186
187=head1 SEE ALSO
188
189L<X509_STORE_CTX_get_error(3)>
190L<X509_STORE_set_verify_cb_func(3)>
191L<X509_STORE_CTX_get_ex_new_index(3)>
192
193=head1 HISTORY
194
195The
196X509_STORE_CTX_get_get_issuer(),
197X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(),
198X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(),
199X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(),
200X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls()
201and X509_STORE_CTX_get_cleanup() functions were added in OpenSSL 1.1.0.
202
203=head1 COPYRIGHT
204
205Copyright 2009-2020 The OpenSSL Project Authors. All Rights Reserved.
206
207Licensed under the OpenSSL license (the "License").  You may not use
208this file except in compliance with the License.  You can obtain a copy
209in the file LICENSE in the source distribution or at
210L<https://www.openssl.org/source/license.html>.
211
212=cut
213