| blob | 28002c1e5c1c018f8b73a30b31f143e8b0a27740 |
1 .\" $OpenBSD: SSL_CTX_set_client_cert_cb.3,v 1.2 2016/11/30 17:26:09 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) 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: November 30 2016 $
52 .Dt SSL_CTX_SET_CLIENT_CERT_CB 3
53 .Os
54 .Sh NAME
55 .Nm SSL_CTX_set_client_cert_cb ,
56 .Nm SSL_CTX_get_client_cert_cb
57 .Nd handle client certificate callback function
58 .Sh SYNOPSIS
59 .In openssl/ssl.h
60 .Ft void
61 .Fo SSL_CTX_set_client_cert_cb
62 .Fa "SSL_CTX *ctx"
63 .Fa "int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)"
64 .Fc
65 .Ft int
66 .Fo "(*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))"
67 .Fa "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey"
68 .Fc
69 .Ft int
70 .Fn "(*client_cert_cb)" "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey"
71 .Sh DESCRIPTION
72 .Fn SSL_CTX_set_client_cert_cb
73 sets the
74 .Fa client_cert_cb()
75 callback that is called when a client certificate is requested by a server and
76 no certificate was yet set for the SSL object.
77 .Pp
78 When
79 .Fa client_cert_cb
80 is
81 .Dv NULL ,
82 no callback function is used.
83 .Pp
84 .Fn SSL_CTX_get_client_cert_cb
85 returns a pointer to the currently set callback function.
86 .Pp
87 .Fn client_cert_cb
88 is the application-defined callback.
89 If it wants to set a certificate,
90 a certificate/private key combination must be set using the
91 .Fa x509
92 and
93 .Fa pkey
94 arguments and 1 must be returned.
95 The certificate will be installed into
96 .Fa ssl .
97 If no certificate should be set,
98 0 has to be returned and no certificate will be sent.
99 A negative return value will suspend the handshake and the handshake function
100 will return immediately.
101 .Xr SSL_get_error 3
102 will return
103 .Dv SSL_ERROR_WANT_X509_LOOKUP
104 to indicate that the handshake was suspended.
105 The next call to the handshake function will again lead to the call of
106 .Fa client_cert_cb() .
107 It is the job of the
108 .Fa client_cert_cb()
109 to store information
110 about the state of the last call, if required to continue.
111 .Pp
112 During a handshake (or renegotiation)
113 a server may request a certificate from the client.
114 A client certificate must only be sent when the server did send the request.
115 .Pp
116 When a certificate has been set using the
117 .Xr SSL_CTX_use_certificate 3
118 family of functions,
119 it will be sent to the server.
120 The TLS standard requires that only a certificate is sent if it matches the
121 list of acceptable CAs sent by the server.
122 This constraint is violated by the default behavior of the OpenSSL library.
123 Using the callback function it is possible to implement a proper selection
124 routine or to allow a user interaction to choose the certificate to be sent.
125 .Pp
126 If a callback function is defined and no certificate was yet defined for the
127 .Vt SSL
128 object, the callback function will be called.
129 If the callback function returns a certificate, the OpenSSL library
130 will try to load the private key and certificate data into the
131 .Vt SSL
132 object using the
133 .Fn SSL_use_certificate
134 and
135 .Fn SSL_use_private_key
136 functions.
137 Thus it will permanently install the certificate and key for this SSL object.
138 It will not be reset by calling
139 .Xr SSL_clear 3 .
140 If the callback returns no certificate, the OpenSSL library will not send a
141 certificate.
142 .Sh SEE ALSO
143 .Xr ssl 3 ,
144 .Xr SSL_clear 3 ,
145 .Xr SSL_CTX_add_extra_chain_cert 3 ,
146 .Xr SSL_CTX_use_certificate 3 ,
147 .Xr SSL_free 3 ,
148 .Xr SSL_get_client_CA_list 3
149 .Sh BUGS
150 The
151 .Fa client_cert_cb()
152 cannot return a complete certificate chain;
153 it can only return one client certificate.
154 If the chain only has a length of 2,
155 the root CA certificate may be omitted according to the TLS standard and
156 thus a standard conforming answer can be sent to the server.
157 For a longer chain, the client must send the complete chain
158 (with the option to leave out the root CA certificate).
159 This can be accomplished only by either adding the intermediate CA certificates
160 into the trusted certificate store for the
161 .Vt SSL_CTX
162 object (resulting in having to add CA certificates that otherwise maybe would
163 not be trusted), or by adding the chain certificates using the
164 .Xr SSL_CTX_add_extra_chain_cert 3
165 function, which is only available for the
166 .Vt SSL_CTX
167 object as a whole and that therefore probably can only apply for one client
168 certificate, making the concept of the callback function
169 (to allow the choice from several certificates) questionable.
170 .Pp
171 Once the
172 .Vt SSL
173 object has been used in conjunction with the callback function,
174 the certificate will be set for the
175 .Vt SSL
176 object and will not be cleared even when
177 .Xr SSL_clear 3
178 is called.
179 It is therefore
180 .Em mandatory
181 to destroy the
182 .Vt SSL
183 object using
184 .Xr SSL_free 3
185 and create a new one to return to the previous state.