1 files changed, 140 insertions, 0 deletions

diff --git a/src/lib/libssl/doc/SSL_CTX_set_client_cert_cb.3 b/src/lib/libssl/doc/SSL_CTX_set_client_cert_cb.3
new file mode 100644
index 0000000000..6aaa5f1016
--- /dev/null
+++ b/src/lib/libssl/doc/SSL_CTX_set_client_cert_cb.3
@@ -0,0 +1,140 @@
+.Dd $Mdocdate: October 12 2014 $
+.Dt SSL_CTX_SET_CLIENT_CERT_CB 3
+.Os
+.Sh NAME
+.Nm SSL_CTX_set_client_cert_cb ,
+.Nm SSL_CTX_get_client_cert_cb
+.Nd handle client certificate callback function
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft void
+.Fo SSL_CTX_set_client_cert_cb
+.Fa "SSL_CTX *ctx"
+.Fa "int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)"
+.Fc
+.Ft int
+.Fo "(*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))"
+.Fa "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey"
+.Fc
+.Ft int
+.Fn "(*client_cert_cb)" "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey"
+.Sh DESCRIPTION
+.Fn SSL_CTX_set_client_cert_cb
+sets the
+.Fa client_cert_cb()
+callback that is called when a client certificate is requested by a server and
+no certificate was yet set for the SSL object.
+.Pp
+When
+.Fa client_cert_cb
+is
+.Dv NULL ,
+no callback function is used.
+.Pp
+.Fn SSL_CTX_get_client_cert_cb
+returns a pointer to the currently set callback function.
+.Pp
+.Fn client_cert_cb
+is the application-defined callback.
+If it wants to set a certificate,
+a certificate/private key combination must be set using the
+.Fa x509
+and
+.Fa pkey
+arguments and 1 must be returned.
+The certificate will be installed into
+.Fa ssl ;
+see the
+.Sx NOTES
+and
+.Sx BUGS
+sections.
+If no certificate should be set,
+0 has to be returned and no certificate will be sent.
+A negative return value will suspend the handshake and the handshake function
+will return immediately.
+.Xr SSL_get_error 3
+will return
+.Dv SSL_ERROR_WANT_X509_LOOKUP
+to indicate that the handshake was suspended.
+The next call to the handshake function will again lead to the call of
+.Fa client_cert_cb() .
+It is the job of the
+.Fa client_cert_cb()
+to store information
+about the state of the last call, if required to continue.
+.Sh NOTES
+During a handshake (or renegotiation)
+a server may request a certificate from the client.
+A client certificate must only be sent when the server did send the request.
+.Pp
+When a certificate has been set using the
+.Xr SSL_CTX_use_certificate 3
+family of functions,
+it will be sent to the server.
+The TLS standard requires that only a certificate is sent if it matches the
+list of acceptable CAs sent by the server.
+This constraint is violated by the default behavior of the OpenSSL library.
+Using the callback function it is possible to implement a proper selection
+routine or to allow a user interaction to choose the certificate to be sent.
+.Pp
+If a callback function is defined and no certificate was yet defined for the
+.Vt SSL
+object, the callback function will be called.
+If the callback function returns a certificate, the OpenSSL library
+will try to load the private key and certificate data into the
+.Vt SSL
+object using the
+.Fn SSL_use_certificate
+and
+.Fn SSL_use_private_key
+functions.
+Thus it will permanently install the certificate and key for this SSL object.
+It will not be reset by calling
+.Xr SSL_clear 3 .
+If the callback returns no certificate, the OpenSSL library will not send a
+certificate.
+.Sh SEE ALSO
+.Xr ssl 3 ,
+.Xr SSL_clear 3 ,
+.Xr SSL_CTX_add_extra_chain_cert 3 ,
+.Xr SSL_CTX_use_certificate 3 ,
+.Xr SSL_free 3 ,
+.Xr SSL_get_client_CA_list 3
+.Sh BUGS
+The
+.Fa client_cert_cb()
+cannot return a complete certificate chain;
+it can only return one client certificate.
+If the chain only has a length of 2,
+the root CA certificate may be omitted according to the TLS standard and
+thus a standard conforming answer can be sent to the server.
+For a longer chain, the client must send the complete chain
+(with the option to leave out the root CA certificate).
+This can be accomplished only by either adding the intermediate CA certificates
+into the trusted certificate store for the
+.Vt SSL_CTX
+object (resulting in having to add CA certificates that otherwise maybe would
+not be trusted), or by adding the chain certificates using the
+.Xr SSL_CTX_add_extra_chain_cert 3
+function, which is only available for the
+.Vt SSL_CTX
+object as a whole and that therefore probably can only apply for one client
+certificate, making the concept of the callback function
+(to allow the choice from several certificates) questionable.
+.Pp
+Once the
+.Vt SSL
+object has been used in conjunction with the callback function,
+the certificate will be set for the
+.Vt SSL
+object and will not be cleared even when
+.Xr SSL_clear 3
+is called.
+It is therefore
+.Em mandatory
+to destroy the
+.Vt SSL
+object using
+.Xr SSL_free 3
+and create a new one to return to the previous state.