Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_tlsext_status_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_TLSEXT_STATUS_CB 3SSL"
58 .TH SSL_CTX_SET_TLSEXT_STATUS_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_tlsext_status_cb,
65 SSL_CTX_get_tlsext_status_cb,
66 SSL_CTX_set_tlsext_status_arg,
67 SSL_CTX_get_tlsext_status_arg,
68 SSL_CTX_set_tlsext_status_type,
69 SSL_CTX_get_tlsext_status_type,
70 SSL_set_tlsext_status_type,
71 SSL_get_tlsext_status_type,
72 SSL_get_tlsext_status_ocsp_resp,
73 SSL_set_tlsext_status_ocsp_resp,
74 SSL_get0_tlsext_status_ocsp_resp_ex,
75 SSL_set0_tlsext_status_ocsp_resp_ex
76 \&\- OCSP Certificate Status Request functions
77 .SH SYNOPSIS
78 .IX Header "SYNOPSIS"
79 .Vb 1
80 \& #include <openssl/tls1.h>
81 \&
82 \& long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx, int (*callback)(SSL *, void *));
83 \& long SSL_CTX_get_tlsext_status_cb(SSL_CTX *ctx, int (**callback)(SSL *, void *));
84 \&
85 \& long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg);
86 \& long SSL_CTX_get_tlsext_status_arg(SSL_CTX *ctx, void **arg);
87 \&
88 \& long SSL_CTX_set_tlsext_status_type(SSL_CTX *ctx, int type);
89 \& long SSL_CTX_get_tlsext_status_type(SSL_CTX *ctx);
90 \&
91 \& long SSL_set_tlsext_status_type(SSL *s, int type);
92 \& long SSL_get_tlsext_status_type(SSL *s);
93 \&
94 \& long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp);
95 \& long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len);
96 \&
97 \& long SSL_get0_tlsext_status_ocsp_resp_ex(ssl, STACK_OF(OCSP_RESPONSE) **resp);
98 \& long SSL_set0_tlsext_status_ocsp_resp_ex(ssl, STACK_OF(OCSP_RESPONSE) *resp);
99 .Ve
100 .SH DESCRIPTION
101 .IX Header "DESCRIPTION"
102 A client application may request that a server send back OCSP status response(s)
103 (also known as OCSP stapling). To do so the client should call the
104 \&\fBSSL_CTX_set_tlsext_status_type()\fR function prior to the creation of any SSL
105 objects. Alternatively an application can call the \fBSSL_set_tlsext_status_type()\fR
106 function on an individual SSL object prior to the start of the handshake.
107 Currently the only supported type is \fBTLSEXT_STATUSTYPE_ocsp\fR. This value
108 should be passed in the \fBtype\fR argument. Calling
109 \&\fBSSL_CTX_get_tlsext_status_type()\fR will return the type \fBTLSEXT_STATUSTYPE_ocsp\fR
110 previously set via \fBSSL_CTX_set_tlsext_status_type()\fR or \-1 if not set.
111 .PP
112 For TLS versions before 1.3 only a single OCSP status response is sent back
113 by the server. TLS 1.3 specifies that the server can send OCSP status responses
114 for the whole chain (OCSP multi-stapling).
115 .PP
116 The client should additionally provide a callback function to decide what to do
117 with the returned OCSP response by calling \fBSSL_CTX_set_tlsext_status_cb()\fR. The
118 callback function should determine whether the returned OCSP response(s) are
119 acceptable or not. The callback will be passed as an argument the value
120 previously set via a call to \fBSSL_CTX_set_tlsext_status_arg()\fR. Note that the
121 callback will not be called in the event of a handshake where session resumption
122 occurs (because there are no Certificates exchanged in such a handshake).
123 The callback previously set via \fBSSL_CTX_set_tlsext_status_cb()\fR can be retrieved
124 by calling \fBSSL_CTX_get_tlsext_status_cb()\fR, and the argument by calling
125 \&\fBSSL_CTX_get_tlsext_status_arg()\fR.
126 .PP
127 On the client side \fBSSL_get_tlsext_status_type()\fR can be used to determine whether
128 the client has previously called \fBSSL_set_tlsext_status_type()\fR. It will return
129 \&\fBTLSEXT_STATUSTYPE_ocsp\fR if it has been called or \-1 otherwise. On the server
130 side \fBSSL_get_tlsext_status_type()\fR can be used to determine whether the client
131 requested OCSP stapling. If the client requested it then this function will
132 return \fBTLSEXT_STATUSTYPE_ocsp\fR, or \-1 otherwise.
133 .PP
134 A single response returned by the server (TLS < 1.3) can be obtained via a call
135 to \fBSSL_get_tlsext_status_ocsp_resp()\fR. The value \fB*resp\fR will be updated to
136 point to the OCSP response data and the return value will be the length of that
137 data. Typically a callback would obtain an OCSP_RESPONSE object from this data
138 via a call to the \fBd2i_OCSP_RESPONSE()\fR function. If the server has not provided
139 any response data then \fB*resp\fR will be NULL and the return value from
140 \&\fBSSL_get_tlsext_status_ocsp_resp()\fR will be \-1.
141 .PP
142 A server application must also call the \fBSSL_CTX_set_tlsext_status_cb()\fR function
143 if it wants to be able to provide clients with (single) OCSP response for the
144 server certificate. Typically the server callback would obtain the server
145 certificate that is being sent back to the client via a call to
146 \&\fBSSL_get_certificate()\fR; retrieve the related OCSP response to be sent back; and
147 then set that response data by calling \fBSSL_set_tlsext_status_ocsp_resp()\fR. A
148 pointer to the response data should be provided in the \fBresp\fR argument, and
149 the length of that data should be in the \fBlen\fR argument. The ownership of
150 the data is transferred to the \fBssl\fR object.
151 .PP
152 In the case of multi-stapling the responses to be returned by the server can be
153 obtained via a call to \fBSSL_get0_tlsext_status_ocsp_resp_ex()\fR. The value \fB*resp\fR
154 will be updated to point to the OCSP response stack and the return value will
155 be the number of responses on the stack.
156 The OCSP responses on the stack are expected to be in the same order as the
157 certificates in the chain. If no OCSP response is available for a certificate
158 in the chain, a NULL element in the stack will represent this.
159 Typically a callback would obtain an OCSP_RESPONSE object from the stack via a
160 call to sk_OCSP_RESPONSE_pop. If the server has not provided any response data
161 then \fB*resp\fR will be NULL and the return value from
162 \&\fBSSL_get0_tlsext_status_ocsp_resp_ex()\fR will be \-1.
163 .PP
164 A server application must also call the \fBSSL_CTX_set_tlsext_status_cb()\fR function
165 if it wants to be able to provide clients with OCSP Certificate Status
166 responses, where TLS 1.3 allows for multi-stapling, i.e., providing responses
167 for all certificates in the chain of the server certificate (excluding the root
168 CA certificate).
169 The certificates sent back to the client and for which OCSP response(s)
170 should be acquired could be obtained via call to \fBSSL_get_certificate()\fR resp.
171 \&\fBSSL_get0_chain_certs()\fR. OCSP response(s) then set by calling
172 \&\fBSSL_set0_tlsext_status_ocsp_resp_ex()\fR. A stack of OCSP responses should be
173 provided in the \fBresp\fR argument.
174 The OCSP responses on the stack are expected to be in the same order as the
175 certificate in the chain. If no OCSP response is available for a certificate in
176 the chain, a NULL element in the stack will represent this.
177 .SH "RETURN VALUES"
178 .IX Header "RETURN VALUES"
179 The callback when used on the client side should return a negative value on
180 error; 0 if the response is not acceptable (in which case the handshake will
181 fail) or a positive value if it is acceptable.
182 .PP
183 The callback when used on the server side should return with either
184 SSL_TLSEXT_ERR_OK (meaning that the OCSP response that has been set should be
185 returned), SSL_TLSEXT_ERR_NOACK (meaning that an OCSP response should not be
186 returned) or SSL_TLSEXT_ERR_ALERT_FATAL (meaning that a fatal error has
187 occurred).
188 .PP
189 \&\fBSSL_CTX_set_tlsext_status_cb()\fR, \fBSSL_CTX_set_tlsext_status_arg()\fR,
190 \&\fBSSL_CTX_set_tlsext_status_type()\fR, \fBSSL_set_tlsext_status_type()\fR,
191 \&\fBSSL_set_tlsext_status_ocsp_resp()\fR return 0 on error or 1 on success.
192 \&\fBSSL_set0_tlsext_status_ocsp_resp_ex()\fR will return always 1.
193 .PP
194 \&\fBSSL_CTX_get_tlsext_status_type()\fR returns the value previously set by
195 \&\fBSSL_CTX_set_tlsext_status_type()\fR, or \-1 if not set.
196 .PP
197 \&\fBSSL_get_tlsext_status_ocsp_resp()\fR returns the length of the OCSP response data
198 or \-1 if there is no OCSP response data.
199 .PP
200 \&\fBSSL_get0_tlsext_status_ocsp_resp_ex()\fR returns the number of the OCSP responses
201 on the stack or \-1 if there is no OCSP response data.
202 .PP
203 \&\fBSSL_get_tlsext_status_type()\fR returns \fBTLSEXT_STATUSTYPE_ocsp\fR on the client
204 side if \fBSSL_set_tlsext_status_type()\fR was previously called, or on the server
205 side if the client requested OCSP stapling. Otherwise \-1 is returned.
206 .SH "SEE ALSO"
207 .IX Header "SEE ALSO"
208 \&\fBssl\fR\|(7)
209 .SH HISTORY
210 .IX Header "HISTORY"
211 The \fBSSL_get_tlsext_status_type()\fR, \fBSSL_CTX_get_tlsext_status_type()\fR
212 and \fBSSL_CTX_set_tlsext_status_type()\fR functions were added in OpenSSL 1.1.0.
213 .PP
214 The \fBSSL_get0_tlsext_status_ocsp_resp_ex()\fR and \fBSSL_set0_tlsext_status_ocsp_resp_ex()\fR
215 macros were added in OpenSSL 3.6.
216 .SH COPYRIGHT
217 .IX Header "COPYRIGHT"
218 Copyright 2015\-2025 The OpenSSL Project Authors. All Rights Reserved.
219 .PP
220 Licensed under the Apache License 2.0 (the "License"). You may not use
221 this file except in compliance with the License. You can obtain a copy
222 in the file LICENSE in the source distribution or at
223 <https://www.openssl.org/source/license.html>.