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