Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_cert_cb.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_SET_CERT_CB 3SSL"
58 .TH SSL_CTX_SET_CERT_CB 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_CTX_set_cert_cb, SSL_set_cert_cb \- handle certificate callback function
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/ssl.h>
69 \&
70 \& void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg),
71 \& void *arg);
72 \& void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg);
73 .Ve
74 .SH DESCRIPTION
75 .IX Header "DESCRIPTION"
76 \&\fBSSL_CTX_set_cert_cb()\fR and \fBSSL_set_cert_cb()\fR sets the \fIcert_cb\fR callback,
77 \&\fIarg\fR value is pointer which is passed to the application callback.
78 .PP
79 When \fIcert_cb\fR is NULL, no callback function is used.
80 .PP
81 \&\fIcert_cb\fR is the application defined callback. It is called before a
82 certificate will be used by a client or server. The callback can then inspect
83 the passed \fIssl\fR structure and set or clear any appropriate certificates. If
84 the callback is successful it \fBMUST\fR return 1 even if no certificates have
85 been set. A zero is returned on error which will abort the handshake with a
86 fatal internal error alert. A negative return value will suspend the handshake
87 and the handshake function will return immediately.
88 \&\fBSSL_get_error\fR\|(3) will return SSL_ERROR_WANT_X509_LOOKUP to
89 indicate, that the handshake was suspended. The next call to the handshake
90 function will again lead to the call of \fIcert_cb\fR. It is the job of the
91 \&\fIcert_cb\fR to store information about the state of the last call,
92 if required to continue.
93 .SH NOTES
94 .IX Header "NOTES"
95 An application will typically call \fBSSL_use_certificate()\fR and
96 \&\fBSSL_use_PrivateKey()\fR to set the end entity certificate and private key.
97 It can add intermediate and optionally the root CA certificates using
98 \&\fBSSL_add1_chain_cert()\fR.
99 .PP
100 It might also call \fBSSL_certs_clear()\fR to delete any certificates associated
101 with the \fBSSL\fR object.
102 .PP
103 The certificate callback functionality supersedes the (largely broken)
104 functionality provided by the old client certificate callback interface.
105 It is \fBalways\fR called even is a certificate is already set so the callback
106 can modify or delete the existing certificate.
107 .PP
108 A more advanced callback might examine the handshake parameters and set
109 whatever chain is appropriate. For example a legacy client supporting only
110 TLSv1.0 might receive a certificate chain signed using SHA1 whereas a
111 TLSv1.2 or later client which advertises support for SHA256 could receive a
112 chain using SHA256.
113 .PP
114 Normal server sanity checks are performed on any certificates set
115 by the callback. So if an EC chain is set for a curve the client does not
116 support it will \fBnot\fR be used.
117 .SH "RETURN VALUES"
118 .IX Header "RETURN VALUES"
119 \&\fBSSL_CTX_set_cert_cb()\fR and \fBSSL_set_cert_cb()\fR do not return values.
120 .SH "SEE ALSO"
121 .IX Header "SEE ALSO"
122 \&\fBssl\fR\|(7), \fBSSL_use_certificate\fR\|(3),
123 \&\fBSSL_add1_chain_cert\fR\|(3),
124 \&\fBSSL_get_client_CA_list\fR\|(3),
125 \&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3)
126 .SH COPYRIGHT
127 .IX Header "COPYRIGHT"
128 Copyright 2014\-2020 The OpenSSL Project Authors. All Rights Reserved.
129 .PP
130 Licensed under the Apache License 2.0 (the "License"). You may not use
131 this file except in compliance with the License. You can obtain a copy
132 in the file LICENSE in the source distribution or at
133 <https://www.openssl.org/source/license.html>.