lib/libssl/man/SSL_CTX_set_client_cert_cb.3

   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.