1=pod 2 3=head1 NAME 4 5SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function 6 7=head1 SYNOPSIS 8 9 #include <openssl/ssl.h> 10 11 void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), void *arg); 12 void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg); 13 14 int (*cert_cb)(SSL *ssl, void *arg); 15 16=head1 DESCRIPTION 17 18SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the B<cert_cb()> callback, 19B<arg> value is pointer which is passed to the application callback. 20 21When B<cert_cb()> is NULL, no callback function is used. 22 23cert_cb() is the application defined callback. It is called before a 24certificate will be used by a client or server. The callback can then inspect 25the passed B<ssl> structure and set or clear any appropriate certificates. If 26the callback is successful it B<MUST> return 1 even if no certificates have 27been set. A zero is returned on error which will abort the handshake with a 28fatal internal error alert. A negative return value will suspend the handshake 29and the handshake function will return immediately. 30L<SSL_get_error(3)|SSL_get_error(3)> will return SSL_ERROR_WANT_X509_LOOKUP to 31indicate, that the handshake was suspended. The next call to the handshake 32function will again lead to the call of cert_cb(). It is the job of the 33cert_cb() to store information about the state of the last call, 34if required to continue. 35 36=head1 NOTES 37 38An application will typically call SSL_use_certificate() and 39SSL_use_PrivateKey() to set the end entity certificate and private key. 40It can add intermediate and optionally the root CA certificates using 41SSL_add1_chain_cert(). 42 43It might also call SSL_certs_clear() to delete any certificates associated 44with the B<SSL> object. 45 46The certificate callback functionality supercedes the (largely broken) 47functionality provided by the old client certificate callback interface. 48It is B<always> called even is a certificate is already set so the callback 49can modify or delete the existing certificate. 50 51A more advanced callback might examine the handshake parameters and set 52whatever chain is appropriate. For example a legacy client supporting only 53TLS v1.0 might receive a certificate chain signed using SHA1 whereas a 54TLS v1.2 client which advertises support for SHA256 could receive a chain 55using SHA256. 56 57Normal server sanity checks are performed on any certificates set 58by the callback. So if an EC chain is set for a curve the client does not 59support it will B<not> be used. 60 61=head1 SEE ALSO 62 63L<ssl(3)|ssl(3)>, L<SSL_use_certificate(3)|SSL_use_certificate(3)>, 64L<SSL_add1_chain_cert(3)|SSL_add1_chain_cert(3)>, 65L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, 66L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)> 67 68=cut 69