1SSL_CTX_SET_CERT_CB(3ossl)          OpenSSL         SSL_CTX_SET_CERT_CB(3ossl)
2
3
4

NAME

6       SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback
7       function
8

SYNOPSIS

10        #include <openssl/ssl.h>
11
12        void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg),
13                                 void *arg);
14        void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg);
15

DESCRIPTION

17       SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the cert_cb callback,
18       arg value is pointer which is passed to the application callback.
19
20       When cert_cb is NULL, no callback function is used.
21
22       cert_cb is the application defined callback. It is called before a
23       certificate will be used by a client or server. The callback can then
24       inspect the passed ssl structure and set or clear any appropriate
25       certificates. If the callback is successful it MUST return 1 even if no
26       certificates have been set. A zero is returned on error which will
27       abort the handshake with a fatal internal error alert. A negative
28       return value will suspend the handshake and the handshake function will
29       return immediately.  SSL_get_error(3) will return
30       SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was
31       suspended. The next call to the handshake function will again lead to
32       the call of cert_cb. It is the job of the cert_cb to store information
33       about the state of the last call, if required to continue.
34

NOTES

36       An application will typically call SSL_use_certificate() and
37       SSL_use_PrivateKey() to set the end entity certificate and private key.
38       It can add intermediate and optionally the root CA certificates using
39       SSL_add1_chain_cert().
40
41       It might also call SSL_certs_clear() to delete any certificates
42       associated with the SSL object.
43
44       The certificate callback functionality supersedes the (largely broken)
45       functionality provided by the old client certificate callback
46       interface.  It is always called even is a certificate is already set so
47       the callback can modify or delete the existing certificate.
48
49       A more advanced callback might examine the handshake parameters and set
50       whatever chain is appropriate. For example a legacy client supporting
51       only TLSv1.0 might receive a certificate chain signed using SHA1
52       whereas a TLSv1.2 or later client which advertises support for SHA256
53       could receive a chain using SHA256.
54
55       Normal server sanity checks are performed on any certificates set by
56       the callback. So if an EC chain is set for a curve the client does not
57       support it will not be used.
58

RETURN VALUES

60       SSL_CTX_set_cert_cb() and SSL_set_cert_cb() do not return values.
61

SEE ALSO

63       ssl(7), SSL_use_certificate(3), SSL_add1_chain_cert(3),
64       SSL_get_client_CA_list(3), SSL_clear(3), SSL_free(3)
65

67       Copyright 2014-2020 The OpenSSL Project Authors. All Rights Reserved.
68
69       Licensed under the Apache License 2.0 (the "License").  You may not use
70       this file except in compliance with the License.  You can obtain a copy
71       in the file LICENSE in the source distribution or at
72       <https://www.openssl.org/source/license.html>.
73
74
75
763.0.9                             2023-07-27        SSL_CTX_SET_CERT_CB(3ossl)
Impressum