1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certificate callback function
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
   12:  int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
   13:  int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey);
   14: 
   15: =head1 DESCRIPTION
   16: 
   17: SSL_CTX_set_client_cert_cb() sets the B<client_cert_cb()> callback, that is
   18: called when a client certificate is requested by a server and no certificate
   19: was yet set for the SSL object.
   20: 
   21: When B<client_cert_cb()> is NULL, no callback function is used.
   22: 
   23: SSL_CTX_get_client_cert_cb() returns a pointer to the currently set callback
   24: function.
   25: 
   26: client_cert_cb() is the application defined callback. If it wants to
   27: set a certificate, a certificate/private key combination must be set
   28: using the B<x509> and B<pkey> arguments and "1" must be returned. The
   29: certificate will be installed into B<ssl>, see the NOTES and BUGS sections.
   30: If no certificate should be set, "0" has to be returned and no certificate
   31: will be sent. A negative return value will suspend the handshake and the
   32: handshake function will return immediatly. L<SSL_get_error(3)|SSL_get_error(3)>
   33: will return SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was
   34: suspended. The next call to the handshake function will again lead to the call
   35: of client_cert_cb(). It is the job of the client_cert_cb() to store information
   36: about the state of the last call, if required to continue.
   37: 
   38: =head1 NOTES
   39: 
   40: During a handshake (or renegotiation) a server may request a certificate
   41: from the client. A client certificate must only be sent, when the server
   42: did send the request.
   43: 
   44: When a certificate was set using the
   45: L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> family of functions,
   46: it will be sent to the server. The TLS standard requires that only a
   47: certificate is sent, if it matches the list of acceptable CAs sent by the
   48: server. This constraint is violated by the default behavior of the OpenSSL
   49: library. Using the callback function it is possible to implement a proper
   50: selection routine or to allow a user interaction to choose the certificate to
   51: be sent.
   52: 
   53: If a callback function is defined and no certificate was yet defined for the
   54: SSL object, the callback function will be called.
   55: If the callback function returns a certificate, the OpenSSL library
   56: will try to load the private key and certificate data into the SSL
   57: object using the SSL_use_certificate() and SSL_use_private_key() functions.
   58: Thus it will permanently install the certificate and key for this SSL
   59: object. It will not be reset by calling L<SSL_clear(3)|SSL_clear(3)>.
   60: If the callback returns no certificate, the OpenSSL library will not send
   61: a certificate.
   62: 
   63: =head1 BUGS
   64: 
   65: The client_cert_cb() cannot return a complete certificate chain, it can
   66: only return one client certificate. If the chain only has a length of 2,
   67: the root CA certificate may be omitted according to the TLS standard and
   68: thus a standard conforming answer can be sent to the server. For a
   69: longer chain, the client must send the complete chain (with the option
   70: to leave out the root CA certificate). This can only be accomplished by
   71: either adding the intermediate CA certificates into the trusted
   72: certificate store for the SSL_CTX object (resulting in having to add
   73: CA certificates that otherwise maybe would not be trusted), or by adding
   74: the chain certificates using the
   75: L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
   76: function, which is only available for the SSL_CTX object as a whole and that
   77: therefore probably can only apply for one client certificate, making
   78: the concept of the callback function (to allow the choice from several
   79: certificates) questionable.
   80: 
   81: Once the SSL object has been used in conjunction with the callback function,
   82: the certificate will be set for the SSL object and will not be cleared
   83: even when L<SSL_clear(3)|SSL_clear(3)> is being called. It is therefore
   84: mandatory to destroy the SSL object using L<SSL_free(3)|SSL_free(3)>
   85: and create a new one to return to the previous state.
   86: 
   87: =head1 SEE ALSO
   88: 
   89: L<ssl(3)|ssl(3)>, L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
   90: L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,
   91: L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
   92: L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>
   93: 
   94: =cut