1289848Sjkim=pod 2289848Sjkim 3289848Sjkim=head1 NAME 4289848Sjkim 5289848SjkimSSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function 6289848Sjkim 7289848Sjkim=head1 SYNOPSIS 8289848Sjkim 9289848Sjkim #include <openssl/ssl.h> 10289848Sjkim 11289848Sjkim void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), void *arg); 12289848Sjkim void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg); 13289848Sjkim 14289848Sjkim int (*cert_cb)(SSL *ssl, void *arg); 15289848Sjkim 16289848Sjkim=head1 DESCRIPTION 17289848Sjkim 18289848SjkimSSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the B<cert_cb()> callback, 19289848SjkimB<arg> value is pointer which is passed to the application callback. 20289848Sjkim 21289848SjkimWhen B<cert_cb()> is NULL, no callback function is used. 22289848Sjkim 23289848Sjkimcert_cb() is the application defined callback. It is called before a 24289848Sjkimcertificate will be used by a client or server. The callback can then inspect 25289848Sjkimthe passed B<ssl> structure and set or clear any appropriate certificates. If 26289848Sjkimthe callback is successful it B<MUST> return 1 even if no certificates have 27289848Sjkimbeen set. A zero is returned on error which will abort the handshake with a 28289848Sjkimfatal internal error alert. A negative return value will suspend the handshake 29289848Sjkimand the handshake function will return immediately. 30289848SjkimL<SSL_get_error(3)|SSL_get_error(3)> will return SSL_ERROR_WANT_X509_LOOKUP to 31289848Sjkimindicate, that the handshake was suspended. The next call to the handshake 32289848Sjkimfunction will again lead to the call of cert_cb(). It is the job of the 33289848Sjkimcert_cb() to store information about the state of the last call, 34289848Sjkimif required to continue. 35289848Sjkim 36289848Sjkim=head1 NOTES 37289848Sjkim 38289848SjkimAn application will typically call SSL_use_certificate() and 39289848SjkimSSL_use_PrivateKey() to set the end entity certificate and private key. 40289848SjkimIt can add intermediate and optionally the root CA certificates using 41289848SjkimSSL_add1_chain_cert(). 42289848Sjkim 43289848SjkimIt might also call SSL_certs_clear() to delete any certificates associated 44289848Sjkimwith the B<SSL> object. 45289848Sjkim 46289848SjkimThe certificate callback functionality supercedes the (largely broken) 47289848Sjkimfunctionality provided by the old client certificate callback interface. 48289848SjkimIt is B<always> called even is a certificate is already set so the callback 49289848Sjkimcan modify or delete the existing certificate. 50289848Sjkim 51289848SjkimA more advanced callback might examine the handshake parameters and set 52289848Sjkimwhatever chain is appropriate. For example a legacy client supporting only 53289848SjkimTLS v1.0 might receive a certificate chain signed using SHA1 whereas a 54289848SjkimTLS v1.2 client which advertises support for SHA256 could receive a chain 55289848Sjkimusing SHA256. 56289848Sjkim 57289848SjkimNormal server sanity checks are performed on any certificates set 58289848Sjkimby the callback. So if an EC chain is set for a curve the client does not 59289848Sjkimsupport it will B<not> be used. 60289848Sjkim 61289848Sjkim=head1 SEE ALSO 62289848Sjkim 63289848SjkimL<ssl(3)|ssl(3)>, L<SSL_use_certificate(3)|SSL_use_certificate(3)>, 64289848SjkimL<SSL_add1_chain_cert(3)|SSL_add1_chain_cert(3)>, 65289848SjkimL<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, 66289848SjkimL<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)> 67289848Sjkim 68289848Sjkim=cut 69