Index for Section 3

Alphabetical listing for S

Bottom of page

SSL_CTX_set_client_cert_cb(3)
NAME
  SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - Handle client
  certificate callback function

SYNOPSIS
  #include <openssl/ssl.h>

  void SSL_CTX_set_client_cert_cb(
	  SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY
  **pkey) );

  int * (
	  SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509,
  EVP_PKEY **pkey );

  int *(
	  client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey );

DESCRIPTION
  The SSL_CTX_set_client_cert_cb() function sets the client_cert_cb()
  callback that is called when a client certificate is requested by a server
  and no certificate was  set for the SSL object. When client_cert_cb() is
  NULL, no callback function is used. The
  SSL_CTX_get_client_cert_cb()function returns a pointer to the currently set
  callback function. The 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 x509 and pkey arguments and ``1'' must be
  returned.

  The certificate will be installed into ssl. (See the NOTES and WARNINGS
  sections.) If no  certificate is set, ``0'' must be returned and no
  certificate will be sent. A negative return value will suspend the
  handshake and the  handshake function will return immediately. The
  SSL_get_error() function will return SSL_ERROR_WANT_X509_LOOKUP to
  indicate that the handshake was suspended. The next call to the  handshake
  function will lead to the call of client_cert_cb(). It  is the job of the
  client_cert_cb() function to store information about the state of the last
  call, if required to continue.

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
  sent a request. When a certificate was set using the
  SSL_CTX_use_certificate() family of functions, it will be  sent to the
  server. The TLS standard requires that a certificate is sent only 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. If a callback function is defined and no certificate was  defined for
  the 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 SSL object using the
  SSL_use_certificate() and 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 SSL_clear(). If the callback returns no
  certificate, the OpenSSL library will not send a certificate.

WARNINGS
  The client_cert_cb() function 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	 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 only be accomplished by either
  adding the intermediate CA certificates into the trusted certificate store
  for the 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 SSL_CTX_add_extra_chain_cert()function. The
  SSL_CTX_add_extra_chain_cert()function is only available for the SSL_CTX
  object as a whole and probably can only apply for one client certificate,
  making the concept of the callback function (to allow the choice from
  several certificates) questionable. Once the SSL object has been used in
  conjunction with the callback function, the certificate will be set for the
  SSL object and will not be cleared even when SSL_clear() is called.  It is
  mandatory to destroy the SSL object using SSL_free() and create a new one
  to return to the previous state.

SEE ALSO
  Files: ssl(3), SSL_CTX_use_certificate(3), SSL_CTX_add_extra_chain_cert(3),
  (3), SSL_get_client_CA_list(3), SSL_clear(3), SSL_free(3)

Index for Section 3

Alphabetical listing for S

Top of page