Debian Codegraph @

upstream/debian-trixie/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.5.6 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 \&\- OCSP Certificate Status Request functions
75 .SH SYNOPSIS
76 .IX Header "SYNOPSIS"
77 .Vb 1
78 \& #include <openssl/tls1.h>
79 \&
80 \& long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx, int (*callback)(SSL *, void *));
81 \& long SSL_CTX_get_tlsext_status_cb(SSL_CTX *ctx, int (**callback)(SSL *, void *));
82 \&
83 \& long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg);
84 \& long SSL_CTX_get_tlsext_status_arg(SSL_CTX *ctx, void **arg);
85 \&
86 \& long SSL_CTX_set_tlsext_status_type(SSL_CTX *ctx, int type);
87 \& long SSL_CTX_get_tlsext_status_type(SSL_CTX *ctx);
88 \&
89 \& long SSL_set_tlsext_status_type(SSL *s, int type);
90 \& long SSL_get_tlsext_status_type(SSL *s);
91 \&
92 \& long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp);
93 \& long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len);
94 .Ve
95 .SH DESCRIPTION
96 .IX Header "DESCRIPTION"
97 A client application may request that a server send back an OCSP status response
98 (also known as OCSP stapling). To do so the client should call the
99 \&\fBSSL_CTX_set_tlsext_status_type()\fR function prior to the creation of any SSL
100 objects. Alternatively an application can call the \fBSSL_set_tlsext_status_type()\fR
101 function on an individual SSL object prior to the start of the handshake.
102 Currently the only supported type is \fBTLSEXT_STATUSTYPE_ocsp\fR. This value
103 should be passed in the \fBtype\fR argument. Calling
104 \&\fBSSL_CTX_get_tlsext_status_type()\fR will return the type \fBTLSEXT_STATUSTYPE_ocsp\fR
105 previously set via \fBSSL_CTX_set_tlsext_status_type()\fR or \-1 if not set.
106 .PP
107 The client should additionally provide a callback function to decide what to do
108 with the returned OCSP response by calling \fBSSL_CTX_set_tlsext_status_cb()\fR. The
109 callback function should determine whether the returned OCSP response is
110 acceptable or not. The callback will be passed as an argument the value
111 previously set via a call to \fBSSL_CTX_set_tlsext_status_arg()\fR. Note that the
112 callback will not be called in the event of a handshake where session resumption
113 occurs (because there are no Certificates exchanged in such a handshake).
114 The callback previously set via \fBSSL_CTX_set_tlsext_status_cb()\fR can be retrieved
115 by calling \fBSSL_CTX_get_tlsext_status_cb()\fR, and the argument by calling
116 \&\fBSSL_CTX_get_tlsext_status_arg()\fR.
117 .PP
118 On the client side \fBSSL_get_tlsext_status_type()\fR can be used to determine whether
119 the client has previously called \fBSSL_set_tlsext_status_type()\fR. It will return
120 \&\fBTLSEXT_STATUSTYPE_ocsp\fR if it has been called or \-1 otherwise. On the server
121 side \fBSSL_get_tlsext_status_type()\fR can be used to determine whether the client
122 requested OCSP stapling. If the client requested it then this function will
123 return \fBTLSEXT_STATUSTYPE_ocsp\fR, or \-1 otherwise.
124 .PP
125 The response returned by the server can be obtained via a call to
126 \&\fBSSL_get_tlsext_status_ocsp_resp()\fR. The value \fB*resp\fR will be updated to point
127 to the OCSP response data and the return value will be the length of that data.
128 Typically a callback would obtain an OCSP_RESPONSE object from this data via a
129 call to the \fBd2i_OCSP_RESPONSE()\fR function. If the server has not provided any
130 response data then \fB*resp\fR will be NULL and the return value from
131 \&\fBSSL_get_tlsext_status_ocsp_resp()\fR will be \-1.
132 .PP
133 A server application must also call the \fBSSL_CTX_set_tlsext_status_cb()\fR function
134 if it wants to be able to provide clients with OCSP Certificate Status
135 responses. Typically the server callback would obtain the server certificate
136 that is being sent back to the client via a call to \fBSSL_get_certificate()\fR;
137 obtain the OCSP response to be sent back; and then set that response data by
138 calling \fBSSL_set_tlsext_status_ocsp_resp()\fR. A pointer to the response data should
139 be provided in the \fBresp\fR argument, and the length of that data should be in
140 the \fBlen\fR argument.
141 .SH "RETURN VALUES"
142 .IX Header "RETURN VALUES"
143 The callback when used on the client side should return a negative value on
144 error; 0 if the response is not acceptable (in which case the handshake will
145 fail) or a positive value if it is acceptable.
146 .PP
147 The callback when used on the server side should return with either
148 SSL_TLSEXT_ERR_OK (meaning that the OCSP response that has been set should be
149 returned), SSL_TLSEXT_ERR_NOACK (meaning that an OCSP response should not be
150 returned) or SSL_TLSEXT_ERR_ALERT_FATAL (meaning that a fatal error has
151 occurred).
152 .PP
153 \&\fBSSL_CTX_set_tlsext_status_cb()\fR, \fBSSL_CTX_set_tlsext_status_arg()\fR,
154 \&\fBSSL_CTX_set_tlsext_status_type()\fR, \fBSSL_set_tlsext_status_type()\fR and
155 \&\fBSSL_set_tlsext_status_ocsp_resp()\fR return 0 on error or 1 on success.
156 .PP
157 \&\fBSSL_CTX_get_tlsext_status_type()\fR returns the value previously set by
158 \&\fBSSL_CTX_set_tlsext_status_type()\fR, or \-1 if not set.
159 .PP
160 \&\fBSSL_get_tlsext_status_ocsp_resp()\fR returns the length of the OCSP response data
161 or \-1 if there is no OCSP response data.
162 .PP
163 \&\fBSSL_get_tlsext_status_type()\fR returns \fBTLSEXT_STATUSTYPE_ocsp\fR on the client
164 side if \fBSSL_set_tlsext_status_type()\fR was previously called, or on the server
165 side if the client requested OCSP stapling. Otherwise \-1 is returned.
166 .SH "SEE ALSO"
167 .IX Header "SEE ALSO"
168 \&\fBssl\fR\|(7)
169 .SH HISTORY
170 .IX Header "HISTORY"
171 The \fBSSL_get_tlsext_status_type()\fR, \fBSSL_CTX_get_tlsext_status_type()\fR
172 and \fBSSL_CTX_set_tlsext_status_type()\fR functions were added in OpenSSL 1.1.0.
173 .SH COPYRIGHT
174 .IX Header "COPYRIGHT"
175 Copyright 2015\-2016 The OpenSSL Project Authors. All Rights Reserved.
176 .PP
177 Licensed under the Apache License 2.0 (the "License"). You may not use
178 this file except in compliance with the License. You can obtain a copy
179 in the file LICENSE in the source distribution or at
180 <https://www.openssl.org/source/license.html>.