SSL_CTX_set_client_cert_cb.pod revision 269682
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 18100936Snectarcalled when a client certificate is requested by a server and no certificate 19100936Snectarwas yet set for the SSL object. 20100928Snectar 21100936SnectarWhen B<client_cert_cb()> is NULL, no callback function is used. 22100936Snectar 23100928SnectarSSL_CTX_get_client_cert_cb() returns a pointer to the currently set callback 24100928Snectarfunction. 25100928Snectar 26100928Snectarclient_cert_cb() is the application defined callback. If it wants to 27100928Snectarset a certificate, a certificate/private key combination must be set 28100928Snectarusing the B<x509> and B<pkey> arguments and "1" must be returned. The 29100928Snectarcertificate will be installed into B<ssl>, see the NOTES and BUGS sections. 30100936SnectarIf no certificate should be set, "0" has to be returned and no certificate 31100936Snectarwill be sent. A negative return value will suspend the handshake and the 32269682Sjkimhandshake function will return immediately. L<SSL_get_error(3)|SSL_get_error(3)> 33100936Snectarwill return SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was 34100936Snectarsuspended. The next call to the handshake function will again lead to the call 35100936Snectarof client_cert_cb(). It is the job of the client_cert_cb() to store information 36100936Snectarabout the state of the last call, if required to continue. 37100928Snectar 38100928Snectar=head1 NOTES 39100928Snectar 40100928SnectarDuring a handshake (or renegotiation) a server may request a certificate 41100928Snectarfrom the client. A client certificate must only be sent, when the server 42100928Snectardid send the request. 43100928Snectar 44100936SnectarWhen a certificate was set using the 45100936SnectarL<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> family of functions, 46100936Snectarit will be sent to the server. The TLS standard requires that only a 47100936Snectarcertificate is sent, if it matches the list of acceptable CAs sent by the 48100936Snectarserver. This constraint is violated by the default behavior of the OpenSSL 49100936Snectarlibrary. Using the callback function it is possible to implement a proper 50100936Snectarselection routine or to allow a user interaction to choose the certificate to 51100936Snectarbe sent. 52100928Snectar 53100936SnectarIf a callback function is defined and no certificate was yet defined for the 54100936SnectarSSL object, the callback function will be called. 55100928SnectarIf the callback function returns a certificate, the OpenSSL library 56100928Snectarwill try to load the private key and certificate data into the SSL 57100936Snectarobject using the SSL_use_certificate() and SSL_use_private_key() functions. 58100936SnectarThus it will permanently install the certificate and key for this SSL 59100936Snectarobject. It will not be reset by calling L<SSL_clear(3)|SSL_clear(3)>. 60100936SnectarIf the callback returns no certificate, the OpenSSL library will not send 61100936Snectara certificate. 62100928Snectar 63100928Snectar=head1 BUGS 64100928Snectar 65100928SnectarThe client_cert_cb() cannot return a complete certificate chain, it can 66100928Snectaronly return one client certificate. If the chain only has a length of 2, 67100928Snectarthe root CA certificate may be omitted according to the TLS standard and 68100928Snectarthus a standard conforming answer can be sent to the server. For a 69100928Snectarlonger chain, the client must send the complete chain (with the option 70100928Snectarto leave out the root CA certificate). This can only be accomplished by 71100928Snectareither adding the intermediate CA certificates into the trusted 72100928Snectarcertificate store for the SSL_CTX object (resulting in having to add 73100928SnectarCA certificates that otherwise maybe would not be trusted), or by adding 74100928Snectarthe chain certificates using the 75100928SnectarL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> 76100928Snectarfunction, which is only available for the SSL_CTX object as a whole and that 77100928Snectartherefore probably can only apply for one client certificate, making 78100928Snectarthe concept of the callback function (to allow the choice from several 79100928Snectarcertificates) questionable. 80100928Snectar 81100928SnectarOnce the SSL object has been used in conjunction with the callback function, 82100928Snectarthe certificate will be set for the SSL object and will not be cleared 83100928Snectareven when L<SSL_clear(3)|SSL_clear(3)> is being called. It is therefore 84100928Snectarmandatory to destroy the SSL object using L<SSL_free(3)|SSL_free(3)> 85100928Snectarand create a new one to return to the previous state. 86100928Snectar 87100928Snectar=head1 SEE ALSO 88100928Snectar 89100928SnectarL<ssl(3)|ssl(3)>, L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, 90100928SnectarL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, 91100928SnectarL<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, 92100928SnectarL<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)> 93100928Snectar 94100928Snectar=cut 95