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