90 lines
4.2 KiB
Text
90 lines
4.2 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certificate callback function
|
|
|
|
=head1 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);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
SSL_CTX_set_client_cert_cb() sets the B<client_cert_cb()> callback, that is
|
|
called when a client certificate is requested by a server.
|
|
When B<client_cert_cb()> is NULL, not callback function is used.
|
|
|
|
SSL_CTX_get_client_cert_cb() returns a pointer to the currently set callback
|
|
function.
|
|
|
|
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 B<x509> and B<pkey> arguments and "1" must be returned. The
|
|
certificate will be installed into B<ssl>, see the NOTES and BUGS sections.
|
|
If no certificate should be set, "0" has to be returned and the default
|
|
certificate will be sent. A fatal error can be indicated by returning
|
|
a negative value, in which case the handshake will be canceled.
|
|
|
|
=head1 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.
|
|
|
|
When no callback function is set, an OpenSSL client will send the certificate
|
|
that was set using the
|
|
L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> family of functions.
|
|
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.
|
|
The callback function can obtain the list of acceptable CAs using the
|
|
L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)> function.
|
|
|
|
If a callback function is defined, 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 SSL_use_certificate() and SSL_use_private_key() functions.
|
|
Thus it will permanently override the certificate and key previously
|
|
installed and will not be reset by calling L<SSL_clear(3)|SSL_clear(3)>.
|
|
If the callback returns no certificate, the OpenSSL library will send
|
|
the certificate previously installed for the SSL_CTX object or the specific
|
|
certificate of the SSL object, if available.
|
|
|
|
=head1 BUGS
|
|
|
|
The 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 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
|
|
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>
|
|
function, which is only available for the 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.
|
|
|
|
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 L<SSL_clear(3)|SSL_clear(3)> is being called. It is therefore
|
|
mandatory to destroy the SSL object using L<SSL_free(3)|SSL_free(3)>
|
|
and create a new one to return to the previous state.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<ssl(3)|ssl(3)>, L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
|
|
L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>,
|
|
L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>,
|
|
L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>
|
|
|
|
=cut
|