]>
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 | ||
e9b77246 BB |
11 | void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), |
12 | void *arg); | |
46ab9bbd DSH |
13 | void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg); |
14 | ||
15 | int (*cert_cb)(SSL *ssl, void *arg); | |
16 | ||
17 | =head1 DESCRIPTION | |
18 | ||
35cb565a | 19 | SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the cert_cb() callback, |
46ab9bbd DSH |
20 | B<arg> value is pointer which is passed to the application callback. |
21 | ||
35cb565a | 22 | When cert_cb() is NULL, no callback function is used. |
46ab9bbd DSH |
23 | |
24 | cert_cb() is the application defined callback. It is called before a | |
25 | certificate will be used by a client or server. The callback can then inspect | |
26 | the passed B<ssl> structure and set or clear any appropriate certificates. If | |
27 | the callback is successful it B<MUST> return 1 even if no certificates have | |
28 | been set. A zero is returned on error which will abort the handshake with a | |
29 | fatal internal error alert. A negative return value will suspend the handshake | |
fc1d88f0 | 30 | and the handshake function will return immediately. |
9b86974e | 31 | L<SSL_get_error(3)> will return SSL_ERROR_WANT_X509_LOOKUP to |
46ab9bbd DSH |
32 | indicate, that the handshake was suspended. The next call to the handshake |
33 | function will again lead to the call of cert_cb(). It is the job of the | |
34 | cert_cb() to store information about the state of the last call, | |
35 | if required to continue. | |
36 | ||
37 | =head1 NOTES | |
38 | ||
39 | An application will typically call SSL_use_certificate() and | |
40 | SSL_use_PrivateKey() to set the end entity certificate and private key. | |
41 | It can add intermediate and optionally the root CA certificates using | |
42 | SSL_add1_chain_cert(). | |
43 | ||
44 | It might also call SSL_certs_clear() to delete any certificates associated | |
45 | with the B<SSL> object. | |
46 | ||
5812e6f1 | 47 | The certificate callback functionality supersedes the (largely broken) |
46ab9bbd DSH |
48 | functionality provided by the old client certificate callback interface. |
49 | It is B<always> called even is a certificate is already set so the callback | |
50 | can modify or delete the existing certificate. | |
51 | ||
52 | A more advanced callback might examine the handshake parameters and set | |
53 | whatever chain is appropriate. For example a legacy client supporting only | |
322755cc HK |
54 | TLSv1.0 might receive a certificate chain signed using SHA1 whereas a |
55 | TLSv1.2 or later client which advertises support for SHA256 could receive a | |
56 | chain using SHA256. | |
46ab9bbd DSH |
57 | |
58 | Normal server sanity checks are performed on any certificates set | |
59 | by the callback. So if an EC chain is set for a curve the client does not | |
60 | support it will B<not> be used. | |
61 | ||
1f13ad31 PY |
62 | =head1 RETURN VALUES |
63 | ||
64 | SSL_CTX_set_cert_cb() and SSL_set_cert_cb() do not return values. | |
65 | ||
46ab9bbd DSH |
66 | =head1 SEE ALSO |
67 | ||
b97fdb57 | 68 | L<ssl(7)>, L<SSL_use_certificate(3)>, |
9b86974e RS |
69 | L<SSL_add1_chain_cert(3)>, |
70 | L<SSL_get_client_CA_list(3)>, | |
71 | L<SSL_clear(3)>, L<SSL_free(3)> | |
46ab9bbd | 72 | |
e2f92610 RS |
73 | =head1 COPYRIGHT |
74 | ||
61f805c1 | 75 | Copyright 2014-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 76 | |
4746f25a | 77 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
78 | this file except in compliance with the License. You can obtain a copy |
79 | in the file LICENSE in the source distribution or at | |
80 | L<https://www.openssl.org/source/license.html>. | |
81 | ||
82 | =cut |