1.\"	$OpenBSD: X509_STORE_CTX_set_verify_cb.3,v 1.3 2016/12/05 13:39:33 schwarze Exp $
2.\"	OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400
3.\"
4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5.\" Copyright (c) 2009, 2016 The OpenSSL Project.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in
16.\"    the documentation and/or other materials provided with the
17.\"    distribution.
18.\"
19.\" 3. All advertising materials mentioning features or use of this
20.\"    software must display the following acknowledgment:
21.\"    "This product includes software developed by the OpenSSL Project
22.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23.\"
24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25.\"    endorse or promote products derived from this software without
26.\"    prior written permission. For written permission, please contact
27.\"    openssl-core@openssl.org.
28.\"
29.\" 5. Products derived from this software may not be called "OpenSSL"
30.\"    nor may "OpenSSL" appear in their names without prior written
31.\"    permission of the OpenSSL Project.
32.\"
33.\" 6. Redistributions of any form whatsoever must retain the following
34.\"    acknowledgment:
35.\"    "This product includes software developed by the OpenSSL Project
36.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37.\"
38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\"
51.Dd $Mdocdate: December 5 2016 $
52.Dt X509_STORE_CTX_SET_VERIFY_CB 3
53.Os
54.Sh NAME
55.Nm X509_STORE_CTX_set_verify_cb
56.Nd set verification callback
57.Sh SYNOPSIS
58.In openssl/x509_vfy.h
59.Ft void
60.Fo X509_STORE_CTX_set_verify_cb
61.Fa "X509_STORE_CTX *ctx"
62.Fa "int (*verify_cb)(int ok, X509_STORE_CTX *ctx)"
63.Fc
64.Sh DESCRIPTION
65.Fn X509_STORE_CTX_set_verify_cb
66sets the verification callback of
67.Fa ctx
68to
69.Fa verify_cb
70overwriting any existing callback.
71.Pp
72The verification callback can be used to customise the operation of
73certificate verification, either by overriding error conditions or
74logging errors for debugging purposes.
75.Pp
76However a verification callback is
77.Sy not
78essential and the default operation is often sufficient.
79.Pp
80The
81.Fa ok
82parameter to the callback indicates the value the callback should return
83to retain the default behaviour.
84If it is zero then an error condition is indicated.
85If it is 1 then no error occurred.
86If the flag
87.Dv X509_V_FLAG_NOTIFY_POLICY
88is set, then
89.Fa ok
90is set to 2 to indicate the policy checking is complete.
91.Pp
92The
93.Fa ctx
94parameter to the callback is the
95.Vt X509_STORE_CTX
96structure that is performing the verification operation.
97A callback can examine this structure and receive additional information
98about the error, for example by calling
99.Xr X509_STORE_CTX_get_current_cert 3 .
100Additional application data can be passed to the callback via the
101.Sy ex_data
102mechanism.
103.Pp
104The verification callback can be set and inherited from the parent
105structure performing the operation.
106In some cases (such as S/MIME verification) the
107.Vt X509_STORE_CTX
108structure is created and destroyed internally and the only way to set a
109custom verification callback is by inheriting it from the associated
110.Vt X509_STORE .
111.Sh RETURN VALUES
112.Fn X509_STORE_CTX_set_verify_cb
113does not return a value.
114.Sh EXAMPLES
115Default callback operation:
116.Bd -literal
117int
118verify_callback(int ok, X509_STORE_CTX *ctx)
119 {
120	return ok;
121}
122.Ed
123.Pp
124Simple example, suppose a certificate in the chain is expired and we
125wish to continue after this error:
126.Bd -literal
127int
128verify_callback(int ok, X509_STORE_CTX *ctx)
129{
130	/* Tolerate certificate expiration */
131	if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED)
132		return 1;
133	/* Otherwise don't override */
134	return ok;
135}
136.Ed
137.Pp
138More complex example, we don't wish to continue after
139.Sy any
140certificate has expired just one specific case:
141.Bd -literal
142int
143verify_callback(int ok, X509_STORE_CTX *ctx)
144{
145	int err = X509_STORE_CTX_get_error(ctx);
146	X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx);
147
148	if (err == X509_V_ERR_CERT_HAS_EXPIRED) {
149		if (check_is_acceptable_expired_cert(err_cert)
150			return 1;
151	}
152	return ok;
153}
154.Ed
155.Pp
156Full featured logging callback.
157In this case the
158.Fa bio_err
159is assumed to be a global logging
160.Vt BIO ,
161an alternative would to store a
162.Vt BIO
163in
164.Fa ctx
165using
166.Sy ex_data .
167.Bd -literal
168int
169verify_callback(int ok, X509_STORE_CTX *ctx)
170{
171	X509 *err_cert;
172	int err,depth;
173
174	err_cert = X509_STORE_CTX_get_current_cert(ctx);
175	err =	X509_STORE_CTX_get_error(ctx);
176	depth =	X509_STORE_CTX_get_error_depth(ctx);
177
178	BIO_printf(bio_err,"depth=%d ",depth);
179	if (err_cert) {
180		X509_NAME_print_ex(bio_err,
181		    X509_get_subject_name(err_cert), 0,
182		    XN_FLAG_ONELINE);
183		BIO_puts(bio_err, "\en");
184	} else
185		BIO_puts(bio_err, "<no cert>\en");
186	if (!ok)
187		BIO_printf(bio_err, "verify error:num=%d:%s\en",
188		    err, X509_verify_cert_error_string(err));
189	switch (err) {
190	case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT:
191		BIO_puts(bio_err, "issuer= ");
192		X509_NAME_print_ex(bio_err,
193		    X509_get_issuer_name(err_cert), 0,
194		    XN_FLAG_ONELINE);
195		BIO_puts(bio_err, "\en");
196		break;
197	case X509_V_ERR_CERT_NOT_YET_VALID:
198	case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD:
199		BIO_printf(bio_err, "notBefore=");
200		ASN1_TIME_print(bio_err,
201		    X509_get_notBefore(err_cert));
202		BIO_printf(bio_err, "\en");
203		break;
204	case X509_V_ERR_CERT_HAS_EXPIRED:
205	case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD:
206		BIO_printf(bio_err, "notAfter=");
207		ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert));
208		BIO_printf(bio_err, "\en");
209		break;
210	case X509_V_ERR_NO_EXPLICIT_POLICY:
211		policies_print(bio_err, ctx);
212		break;
213	}
214	if (err == X509_V_OK && ok == 2)
215		/* print out policies */
216
217	BIO_printf(bio_err,"verify return:%d\en",ok);
218	return(ok);
219}
220.Ed
221.Sh SEE ALSO
222.Xr X509_STORE_CTX_get_error 3 ,
223.Xr X509_STORE_CTX_get_ex_new_index 3 ,
224.Xr X509_STORE_set_verify_cb_func 3
225.Sh HISTORY
226.Fn X509_STORE_CTX_set_verify_cb
227is available in all versions of SSLeay and OpenSSL.
228.Sh CAVEATS
229In general a verification callback should
230.Sy NOT
231unconditionally return 1 in all circumstances because this will allow
232verification to succeed no matter what the error.
233This effectively removes all security from the application because
234.Sy any
235certificate (including untrusted generated ones) will be accepted.
236