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