1.\"	$OpenBSD: SSL_CTX_set_cert_verify_callback.3,v 1.5 2019/06/08 15:25:43 schwarze Exp $
2.\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3.\"
4.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
5.\" Copyright (c) 2001, 2002 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: June 8 2019 $
52.Dt SSL_CTX_SET_CERT_VERIFY_CALLBACK 3
53.Os
54.Sh NAME
55.Nm SSL_CTX_set_cert_verify_callback
56.Nd set peer certificate verification procedure
57.Sh SYNOPSIS
58.In openssl/ssl.h
59.Ft void
60.Fo SSL_CTX_set_cert_verify_callback
61.Fa "SSL_CTX *ctx"
62.Fa "int (*callback)(X509_STORE_CTX *, void *)"
63.Fa "void *arg"
64.Fc
65.Sh DESCRIPTION
66.Fn SSL_CTX_set_cert_verify_callback
67sets the verification callback function for
68.Fa ctx .
69.Vt SSL
70objects that are created from
71.Fa ctx
72inherit the setting valid at the time when
73.Xr SSL_new 3
74is called.
75.Pp
76Whenever a certificate is verified during a SSL/TLS handshake,
77a verification function is called.
78If the application does not explicitly specify a verification callback
79function, the built-in verification function is used.
80If a verification callback
81.Fa callback
82is specified via
83.Fn SSL_CTX_set_cert_verify_callback ,
84the supplied callback function is called instead.
85By setting
86.Fa callback
87to
88.Dv NULL ,
89the default behaviour is restored.
90.Pp
91When the verification must be performed,
92.Fa callback
93will be called with the arguments
94.Fn callback "X509_STORE_CTX *x509_store_ctx" "void *arg" .
95The argument
96.Fa arg
97is specified by the application when setting
98.Fa callback .
99.Pp
100.Fa callback
101should return 1 to indicate verification success and 0 to indicate verification
102failure.
103If
104.Dv SSL_VERIFY_PEER
105is set and
106.Fa callback
107returns 0, the handshake will fail.
108As the verification procedure may allow the connection to continue in case of
109failure (by always returning 1) the verification result must be set in any case
110using the
111.Fa error
112member of
113.Fa x509_store_ctx
114so that the calling application will be informed about the detailed result of
115the verification procedure!
116.Pp
117Within
118.Fa x509_store_ctx ,
119.Fa callback
120has access to the
121.Fa verify_callback
122function set using
123.Xr SSL_CTX_set_verify 3 .
124.Sh SEE ALSO
125.Xr ssl 3 ,
126.Xr SSL_CTX_load_verify_locations 3 ,
127.Xr SSL_CTX_set_verify 3 ,
128.Xr SSL_get_verify_result 3
129.Sh HISTORY
130.Fn SSL_CTX_set_cert_verify_callback
131first appeared in SSLeay 0.6.1 and has been available since
132.Ox 2.4 .
133.Pp
134Previous to OpenSSL 0.9.7, the
135.Fa arg
136argument to
137.Fn SSL_CTX_set_cert_verify_callback
138was ignored, and
139.Fa callback
140was called
141simply as
142.Ft int
143.Fn (*callback) "X509_STORE_CTX *" .
144To compile software written for previous versions of OpenSSL,
145a dummy argument will have to be added to
146.Fa callback .
147.Sh CAVEATS
148Do not mix the verification callback described in this function with the
149.Fa verify_callback
150function called during the verification process.
151The latter is set using the
152.Xr SSL_CTX_set_verify 3
153family of functions.
154.Pp
155Providing a complete verification procedure including certificate purpose
156settings, etc., is a complex task.
157The built-in procedure is quite powerful and in most cases it should be
158sufficient to modify its behaviour using the
159.Fa verify_callback
160function.
161.Sh BUGS
162.Fn SSL_CTX_set_cert_verify_callback
163does not provide diagnostic information.
164