SSL_CTX_set_client_cert_cb.pod revision 100928
1100928Snectar=pod 2100928Snectar 3100928Snectar=head1 NAME 4100928Snectar 5100928SnectarSSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certificate callback function 6100928Snectar 7100928Snectar=head1 SYNOPSIS 8100928Snectar 9100928Snectar #include <openssl/ssl.h> 10100928Snectar 11100928Snectar void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)); 12100928Snectar int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); 13100928Snectar int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey); 14100928Snectar 15100928Snectar=head1 DESCRIPTION 16100928Snectar 17100928SnectarSSL_CTX_set_client_cert_cb() sets the B<client_cert_cb()> callback, that is 18100928Snectarcalled when a client certificate is requested by a server. 19100928SnectarWhen B<client_cert_cb()> is NULL, not callback function is used. 20100928Snectar 21100928SnectarSSL_CTX_get_client_cert_cb() returns a pointer to the currently set callback 22100928Snectarfunction. 23100928Snectar 24100928Snectarclient_cert_cb() is the application defined callback. If it wants to 25100928Snectarset a certificate, a certificate/private key combination must be set 26100928Snectarusing the B<x509> and B<pkey> arguments and "1" must be returned. The 27100928Snectarcertificate will be installed into B<ssl>, see the NOTES and BUGS sections. 28100928SnectarIf no certificate should be set, "0" has to be returned and the default 29100928Snectarcertificate will be sent. A fatal error can be indicated by returning 30100928Snectara negative value, in which case the handshake will be canceled. 31100928Snectar 32100928Snectar=head1 NOTES 33100928Snectar 34100928SnectarDuring a handshake (or renegotiation) a server may request a certificate 35100928Snectarfrom the client. A client certificate must only be sent, when the server 36100928Snectardid send the request. 37100928Snectar 38100928SnectarWhen no callback function is set, an OpenSSL client will send the certificate 39100928Snectarthat was set using the 40100928SnectarL<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> family of functions. 41100928SnectarThe TLS standard requires that only a certificate is sent, if it matches 42100928Snectarthe list of acceptable CAs sent by the server. This constraint is 43100928Snectarviolated by the default behavior of the OpenSSL library. Using the 44100928Snectarcallback function it is possible to implement a proper selection routine 45100928Snectaror to allow a user interaction to choose the certificate to be sent. 46100928SnectarThe callback function can obtain the list of acceptable CAs using the 47100928SnectarL<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)> function. 48100928Snectar 49100928SnectarIf a callback function is defined, the callback function will be called. 50100928SnectarIf the callback function returns a certificate, the OpenSSL library 51100928Snectarwill try to load the private key and certificate data into the SSL 52100928Snectarobject using SSL_use_certificate() and SSL_use_private_key() functions. 53100928SnectarThus it will permanently override the certificate and key previously 54100928Snectarinstalled and will not be reset by calling L<SSL_clear(3)|SSL_clear(3)>. 55100928SnectarIf the callback returns no certificate, the OpenSSL library will send 56100928Snectarthe certificate previously installed for the SSL_CTX object or the specific 57100928Snectarcertificate of the SSL object, if available. 58100928Snectar 59100928Snectar=head1 BUGS 60100928Snectar 61100928SnectarThe client_cert_cb() cannot return a complete certificate chain, it can 62100928Snectaronly return one client certificate. If the chain only has a length of 2, 63100928Snectarthe root CA certificate may be omitted according to the TLS standard and 64100928Snectarthus a standard conforming answer can be sent to the server. For a 65100928Snectarlonger chain, the client must send the complete chain (with the option 66100928Snectarto leave out the root CA certificate). This can only be accomplished by 67100928Snectareither adding the intermediate CA certificates into the trusted 68100928Snectarcertificate store for the SSL_CTX object (resulting in having to add 69100928SnectarCA certificates that otherwise maybe would not be trusted), or by adding 70100928Snectarthe chain certificates using the 71100928SnectarL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> 72100928Snectarfunction, which is only available for the SSL_CTX object as a whole and that 73100928Snectartherefore probably can only apply for one client certificate, making 74100928Snectarthe concept of the callback function (to allow the choice from several 75100928Snectarcertificates) questionable. 76100928Snectar 77100928SnectarOnce the SSL object has been used in conjunction with the callback function, 78100928Snectarthe certificate will be set for the SSL object and will not be cleared 79100928Snectareven when L<SSL_clear(3)|SSL_clear(3)> is being called. It is therefore 80100928Snectarmandatory to destroy the SSL object using L<SSL_free(3)|SSL_free(3)> 81100928Snectarand create a new one to return to the previous state. 82100928Snectar 83100928Snectar=head1 SEE ALSO 84100928Snectar 85100928SnectarL<ssl(3)|ssl(3)>, L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, 86100928SnectarL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, 87100928SnectarL<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, 88100928SnectarL<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)> 89100928Snectar 90100928Snectar=cut 91