Debian Codegraph @

upstream/debian-unstable/man3/SSL_extension_supported.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_EXTENSION_SUPPORTED 3SSL"
58 .TH SSL_EXTENSION_SUPPORTED 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_extension_supported,
65 SSL_custom_ext_add_cb_ex,
66 SSL_custom_ext_free_cb_ex,
67 SSL_custom_ext_parse_cb_ex,
68 SSL_CTX_add_custom_ext,
69 SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext,
70 custom_ext_add_cb, custom_ext_free_cb, custom_ext_parse_cb
71 \&\- custom TLS extension handling
72 .SH SYNOPSIS
73 .IX Header "SYNOPSIS"
74 .Vb 1
75 \& #include <openssl/ssl.h>
76 \&
77 \& typedef int (*SSL_custom_ext_add_cb_ex)(SSL *s, unsigned int ext_type,
78 \& unsigned int context,
79 \& const unsigned char **out,
80 \& size_t *outlen, X509 *x,
81 \& size_t chainidx, int *al,
82 \& void *add_arg);
83 \&
84 \& typedef void (*SSL_custom_ext_free_cb_ex)(SSL *s, unsigned int ext_type,
85 \& unsigned int context,
86 \& const unsigned char *out,
87 \& void *add_arg);
88 \&
89 \& typedef int (*SSL_custom_ext_parse_cb_ex)(SSL *s, unsigned int ext_type,
90 \& unsigned int context,
91 \& const unsigned char *in,
92 \& size_t inlen, X509 *x,
93 \& size_t chainidx, int *al,
94 \& void *parse_arg);
95 \&
96 \& int SSL_CTX_add_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
97 \& unsigned int context,
98 \& SSL_custom_ext_add_cb_ex add_cb,
99 \& SSL_custom_ext_free_cb_ex free_cb,
100 \& void *add_arg,
101 \& SSL_custom_ext_parse_cb_ex parse_cb,
102 \& void *parse_arg);
103 \&
104 \& typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type,
105 \& const unsigned char **out,
106 \& size_t *outlen, int *al,
107 \& void *add_arg);
108 \&
109 \& typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type,
110 \& const unsigned char *out,
111 \& void *add_arg);
112 \&
113 \& typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type,
114 \& const unsigned char *in,
115 \& size_t inlen, int *al,
116 \& void *parse_arg);
117 \&
118 \& int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
119 \& custom_ext_add_cb add_cb,
120 \& custom_ext_free_cb free_cb, void *add_arg,
121 \& custom_ext_parse_cb parse_cb,
122 \& void *parse_arg);
123 \&
124 \& int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
125 \& custom_ext_add_cb add_cb,
126 \& custom_ext_free_cb free_cb, void *add_arg,
127 \& custom_ext_parse_cb parse_cb,
128 \& void *parse_arg);
129 \&
130 \& int SSL_extension_supported(unsigned int ext_type);
131 .Ve
132 .SH DESCRIPTION
133 .IX Header "DESCRIPTION"
134 \&\fBSSL_CTX_add_custom_ext()\fR adds a custom extension for a TLS/DTLS client or server
135 for all supported protocol versions with extension type \fBext_type\fR and
136 callbacks \fBadd_cb\fR, \fBfree_cb\fR and \fBparse_cb\fR (see the
137 "EXTENSION CALLBACKS" section below). The \fBcontext\fR value determines
138 which messages and under what conditions the extension will be added/parsed (see
139 the "EXTENSION CONTEXTS" section below).
140 .PP
141 \&\fBSSL_CTX_add_client_custom_ext()\fR adds a custom extension for a TLS/DTLS client
142 with extension type \fBext_type\fR and callbacks \fBadd_cb\fR, \fBfree_cb\fR and
143 \&\fBparse_cb\fR. This function is similar to \fBSSL_CTX_add_custom_ext()\fR except it only
144 applies to clients, uses the older style of callbacks, and implicitly sets the
145 \&\fBcontext\fR value to:
146 .PP
147 .Vb 2
148 \& SSL_EXT_TLS1_2_AND_BELOW_ONLY | SSL_EXT_CLIENT_HELLO
149 \& | SSL_EXT_TLS1_2_SERVER_HELLO | SSL_EXT_IGNORE_ON_RESUMPTION
150 .Ve
151 .PP
152 \&\fBSSL_CTX_add_server_custom_ext()\fR adds a custom extension for a TLS/DTLS server
153 with extension type \fBext_type\fR and callbacks \fBadd_cb\fR, \fBfree_cb\fR and
154 \&\fBparse_cb\fR. This function is similar to \fBSSL_CTX_add_custom_ext()\fR except it
155 only applies to servers, uses the older style of callbacks, and implicitly sets
156 the \fBcontext\fR value to the same as for \fBSSL_CTX_add_client_custom_ext()\fR above.
157 .PP
158 The \fBext_type\fR parameter corresponds to the \fBextension_type\fR field of
159 RFC5246 et al. It is \fBnot\fR a NID. In all cases the extension type must not be
160 handled by OpenSSL internally or an error occurs.
161 .PP
162 \&\fBSSL_extension_supported()\fR returns 1 if the extension \fBext_type\fR is handled
163 internally by OpenSSL and 0 otherwise.
164 .SH "EXTENSION CALLBACKS"
165 .IX Header "EXTENSION CALLBACKS"
166 The callback \fBadd_cb\fR is called to send custom extension data to be
167 included in various TLS messages. The \fBext_type\fR parameter is set to the
168 extension type which will be added and \fBadd_arg\fR to the value set when the
169 extension handler was added. When using the new style callbacks the \fBcontext\fR
170 parameter will indicate which message is currently being constructed e.g. for
171 the ClientHello it will be set to \fBSSL_EXT_CLIENT_HELLO\fR.
172 .PP
173 If the application wishes to include the extension \fBext_type\fR it should
174 set \fB*out\fR to the extension data, set \fB*outlen\fR to the length of the
175 extension data and return 1.
176 .PP
177 If the \fBadd_cb\fR does not wish to include the extension it must return 0.
178 .PP
179 If \fBadd_cb\fR returns \-1 a fatal handshake error occurs using the TLS
180 alert value specified in \fB*al\fR.
181 .PP
182 When constructing the ClientHello, if \fBadd_cb\fR is set to NULL a zero length
183 extension is added for \fBext_type\fR. For all other messages if \fBadd_cb\fR is set
184 to NULL then no extension is added.
185 .PP
186 When constructing a Certificate message the callback will be called for each
187 certificate in the message. The \fBx\fR parameter will indicate the
188 current certificate and the \fBchainidx\fR parameter will indicate the position
189 of the certificate in the message. The first certificate is always the end
190 entity certificate and has a \fBchainidx\fR value of 0. The certificates are in the
191 order that they were received in the Certificate message.
192 .PP
193 For all messages except the ServerHello and EncryptedExtensions every
194 registered \fBadd_cb\fR is always called to see if the application wishes to add an
195 extension (as long as all requirements of the specified \fBcontext\fR are met).
196 .PP
197 For the ServerHello and EncryptedExtension messages every registered \fBadd_cb\fR
198 is called once if and only if the requirements of the specified \fBcontext\fR are
199 met and the corresponding extension was received in the ClientHello. That is, if
200 no corresponding extension was received in the ClientHello then \fBadd_cb\fR will
201 not be called.
202 .PP
203 If an extension is added (that is \fBadd_cb\fR returns 1) \fBfree_cb\fR is called
204 (if it is set) with the value of \fBout\fR set by the add callback. It can be
205 used to free up any dynamic extension data set by \fBadd_cb\fR. Since \fBout\fR is
206 constant (to permit use of constant data in \fBadd_cb\fR) applications may need to
207 cast away const to free the data.
208 .PP
209 The callback \fBparse_cb\fR receives data for TLS extensions. The callback is only
210 called if the extension is present and relevant for the context (see
211 "EXTENSION CONTEXTS" below).
212 .PP
213 The extension data consists of \fBinlen\fR bytes in the buffer \fBin\fR for the
214 extension \fBext_type\fR.
215 .PP
216 If the message being parsed is a TLSv1.3 compatible Certificate message then
217 \&\fBparse_cb\fR will be called for each certificate contained within the message.
218 The \fBx\fR parameter will indicate the current certificate and the \fBchainidx\fR
219 parameter will indicate the position of the certificate in the message. The
220 first certificate is always the end entity certificate and has a \fBchainidx\fR
221 value of 0.
222 .PP
223 If the \fBparse_cb\fR considers the extension data acceptable it must return
224 1. If it returns 0 or a negative value a fatal handshake error occurs
225 using the TLS alert value specified in \fB*al\fR.
226 .PP
227 The buffer \fBin\fR is a temporary internal buffer which will not be valid after
228 the callback returns.
229 .SH "EXTENSION CONTEXTS"
230 .IX Header "EXTENSION CONTEXTS"
231 An extension context defines which messages and under which conditions an
232 extension should be added or expected. The context is built up by performing
233 a bitwise OR of multiple pre-defined values together. The valid context values
234 are:
235 .IP SSL_EXT_TLS_ONLY 4
236 .IX Item "SSL_EXT_TLS_ONLY"
237 The extension is only allowed in TLS
238 .IP SSL_EXT_DTLS_ONLY 4
239 .IX Item "SSL_EXT_DTLS_ONLY"
240 The extension is only allowed in DTLS
241 .IP SSL_EXT_TLS_IMPLEMENTATION_ONLY 4
242 .IX Item "SSL_EXT_TLS_IMPLEMENTATION_ONLY"
243 The extension is allowed in DTLS, but there is only a TLS implementation
244 available (so it is ignored in DTLS).
245 .IP SSL_EXT_SSL3_ALLOWED 4
246 .IX Item "SSL_EXT_SSL3_ALLOWED"
247 Extensions are not typically defined for SSLv3. Setting this value will allow
248 the extension in SSLv3. Applications will not typically need to use this.
249 .IP SSL_EXT_TLS1_2_AND_BELOW_ONLY 4
250 .IX Item "SSL_EXT_TLS1_2_AND_BELOW_ONLY"
251 The extension is only defined for TLSv1.2/DTLSv1.2 and below. Servers will
252 ignore this extension if it is present in the ClientHello and TLSv1.3 is
253 negotiated.
254 .IP SSL_EXT_TLS1_3_ONLY 4
255 .IX Item "SSL_EXT_TLS1_3_ONLY"
256 The extension is only defined for TLS1.3 and above. Servers will ignore this
257 extension if it is present in the ClientHello and TLSv1.2 or below is
258 negotiated.
259 .IP SSL_EXT_IGNORE_ON_RESUMPTION 4
260 .IX Item "SSL_EXT_IGNORE_ON_RESUMPTION"
261 The extension will be ignored during parsing if a previous session is being
262 successfully resumed.
263 .IP SSL_EXT_CLIENT_HELLO 4
264 .IX Item "SSL_EXT_CLIENT_HELLO"
265 The extension may be present in the ClientHello message.
266 .IP SSL_EXT_TLS1_2_SERVER_HELLO 4
267 .IX Item "SSL_EXT_TLS1_2_SERVER_HELLO"
268 The extension may be present in a TLSv1.2 or below compatible ServerHello
269 message.
270 .IP SSL_EXT_TLS1_3_SERVER_HELLO 4
271 .IX Item "SSL_EXT_TLS1_3_SERVER_HELLO"
272 The extension may be present in a TLSv1.3 compatible ServerHello message.
273 .IP SSL_EXT_TLS1_3_ENCRYPTED_EXTENSIONS 4
274 .IX Item "SSL_EXT_TLS1_3_ENCRYPTED_EXTENSIONS"
275 The extension may be present in an EncryptedExtensions message.
276 .IP SSL_EXT_TLS1_3_HELLO_RETRY_REQUEST 4
277 .IX Item "SSL_EXT_TLS1_3_HELLO_RETRY_REQUEST"
278 The extension may be present in a HelloRetryRequest message.
279 .IP SSL_EXT_TLS1_3_CERTIFICATE 4
280 .IX Item "SSL_EXT_TLS1_3_CERTIFICATE"
281 The extension may be present in a TLSv1.3 compatible Certificate message.
282 .IP SSL_EXT_TLS1_3_NEW_SESSION_TICKET 4
283 .IX Item "SSL_EXT_TLS1_3_NEW_SESSION_TICKET"
284 The extension may be present in a TLSv1.3 compatible NewSessionTicket message.
285 .IP SSL_EXT_TLS1_3_CERTIFICATE_REQUEST 4
286 .IX Item "SSL_EXT_TLS1_3_CERTIFICATE_REQUEST"
287 The extension may be present in a TLSv1.3 compatible CertificateRequest message.
288 .PP
289 The context must include at least one message value (otherwise the extension
290 will never be used).
291 .SH NOTES
292 .IX Header "NOTES"
293 The \fBadd_arg\fR and \fBparse_arg\fR parameters can be set to arbitrary values
294 which will be passed to the corresponding callbacks. They can, for example,
295 be used to store the extension data received in a convenient structure or
296 pass the extension data to be added or freed when adding extensions.
297 .PP
298 If the same custom extension type is received multiple times a fatal
299 \&\fBdecode_error\fR alert is sent and the handshake aborts. If a custom extension
300 is received in a ServerHello/EncryptedExtensions message which was not sent in
301 the ClientHello a fatal \fBunsupported_extension\fR alert is sent and the
302 handshake is aborted. The ServerHello/EncryptedExtensions \fBadd_cb\fR callback is
303 only called if the corresponding extension was received in the ClientHello. This
304 is compliant with the TLS specifications. This behaviour ensures that each
305 callback is called at most once and that an application can never send
306 unsolicited extensions.
307 .SH "RETURN VALUES"
308 .IX Header "RETURN VALUES"
309 \&\fBSSL_CTX_add_custom_ext()\fR, \fBSSL_CTX_add_client_custom_ext()\fR and
310 \&\fBSSL_CTX_add_server_custom_ext()\fR return 1 for success and 0 for failure. A
311 failure can occur if an attempt is made to add the same \fBext_type\fR more than
312 once, if an attempt is made to use an extension type handled internally by
313 OpenSSL or if an internal error occurs (for example a memory allocation
314 failure).
315 .PP
316 \&\fBSSL_extension_supported()\fR returns 1 if the extension \fBext_type\fR is handled
317 internally by OpenSSL and 0 otherwise.
318 .SH "SEE ALSO"
319 .IX Header "SEE ALSO"
320 \&\fBssl\fR\|(7)
321 .SH HISTORY
322 .IX Header "HISTORY"
323 The \fBSSL_CTX_add_custom_ext()\fR function was added in OpenSSL 1.1.1.
324 .SH COPYRIGHT
325 .IX Header "COPYRIGHT"
326 Copyright 2014\-2020 The OpenSSL Project Authors. All Rights Reserved.
327 .PP
328 Licensed under the Apache License 2.0 (the "License"). You may not use
329 this file except in compliance with the License. You can obtain a copy
330 in the file LICENSE in the source distribution or at
331 <https://www.openssl.org/source/license.html>.