Debian Codegraph @

upstream/debian-unstable/man3/SSL_set_quic_tls_cbs.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_SET_QUIC_TLS_CBS 3SSL"
58 .TH SSL_SET_QUIC_TLS_CBS 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 OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn,
65 OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn,
66 OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn,
67 OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn,
68 OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn,
69 OSSL_FUNC_SSL_QUIC_TLS_alert_fn,
70 SSL_set_quic_tls_cbs,
71 SSL_set_quic_tls_transport_params,
72 SSL_set_quic_tls_early_data_enabled
73 \&\- Use the OpenSSL TLS implementation for a third party QUIC implementation
74 .SH SYNOPSIS
75 .IX Header "SYNOPSIS"
76 .Vb 1
77 \& #include <openssl/ssl.h>
78 \&
79 \& /* QUIC TLS callbacks available via an OSSL_DISPATCH table */
80 \&
81 \& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND */
82 \& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn)(SSL *s,
83 \& const unsigned char *buf,
84 \& size_t buf_len,
85 \& size_t *consumed,
86 \& void *arg);
87 \&
88 \& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD */
89 \& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn)(SSL *s,
90 \& const unsigned char **buf,
91 \& size_t *bytes_read,
92 \& void *arg);
93 \&
94 \& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD */
95 \& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn)(SSL *,
96 \& size_t bytes_read,
97 \& void *arg);
98 \&
99 \& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET */
100 \& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn)(SSL *s,
101 \& uint32_t prot_level,
102 \& int direction,
103 \& const unsigned char *secret,
104 \& size_t secret_len,
105 \& void *arg);
106 \&
107 \& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS */
108 \& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn)(SSL *s,
109 \& const unsigned char *params,
110 \& size_t params_len,
111 \& void *arg);
112 \&
113 \& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_ALERT */
114 \& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_alert_fn)(SSL *s,
115 \& unsigned char alert_code,
116 \& void *arg);
117 \&
118 \& int SSL_set_quic_tls_cbs(SSL *s, const OSSL_DISPATCH *qtdis, void *arg);
119 \& int SSL_set_quic_tls_transport_params(SSL *s,
120 \& const unsigned char *params,
121 \& size_t params_len);
122 \& int SSL_set_quic_tls_early_data_enabled(SSL *s, int enabled);
123 .Ve
124 .SH DESCRIPTION
125 .IX Header "DESCRIPTION"
126 \&\fBSSL_set_quic_tls_cbs()\fR can be used to replace the standard TLS record layer with
127 a custom record layer for use by a third party QUIC implementation. For the
128 given SSL object \fIs\fR, a set of callbacks are supplied in an \fBOSSL_DISPATCH\fR
129 table via \fIqtdis\fR. The \fIarg\fR parameter will be passed as an argument when the
130 various callbacks are called.
131 .PP
132 The above callbacks are invoked, as needed, by \fBSSL_do_handshake()\fR and \fBSSL_read()\fR (including
133 SSL_read_ex, SSL_peek, SSL_peek_ex). Once the SSL handshake is complete, the QUIC
134 stack must arrange to call one of the \fBSSL_read()\fR variants whenever a post-handshake CRYPTO
135 frame is received. The number of bytes requested may be zero.
136 .PP
137 An \fBOSSL_DISPATCH\fR table should consist of an array of \fBOSSL_DISPATCH\fR entries
138 where each entry is a function id, and a function pointer. The array should be
139 terminated with an empty entry (i.e. a 0 function id, and a NULL function
140 pointer).
141 .PP
142 Calling the \fBSSL_set_quic_tls_cbs()\fR function will switch off the
143 \&\fBSSL_OP_ENABLE_MIDDLEBOX_COMPAT\fR option (if set). See \fBSSL_set_options\fR\|(3).
144 Additionally the minimum TLS protocol version will be set to TLS1_3_VERSION. It
145 is an error to call this function with anything other than a TLS connection SSL
146 object.
147 .PP
148 The OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn callback (function id
149 \&\fBOSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND\fR) is called when CRYPTO frame data should
150 be sent to the peer. The data to be sent is supplied in the buffer \fIbuf\fR which
151 is of length \fIbuf_len\fR. The callback may choose to consume less data than was
152 supplied in the buffer. On successful completion of the callback the \fIconsumed\fR
153 parameter should be populated with the amount of data that the callback
154 consumed. This should be less than or equal to the value in \fIbuf_len\fR. CRYPTO
155 data should be sent using the most recent write encryption level set via the
156 OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn callback (if it has been called).
157 .PP
158 The OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn callback (function id
159 \&\fBOSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD\fR) is used to receive CRYPTO frame data
160 from the peer. When OpenSSL wants to read data from the peer this callback is
161 called. The callback should populate \fI*buf\fR with a pointer to a buffer
162 containing CRYPTO data that has been received from the peer. The size of the
163 buffer should be populated in \fI*bytes_read\fR. The buffer should remain valid
164 until OpenSSL calls the OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn callback.
165 CRYPTO frame data is assumed to have been decrypted using the most recent read
166 protection level set via the yield_secret_cb callback (if it has been called).
167 .PP
168 The OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn callback (function id
169 \&\fBOSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD\fR) is called when data previously
170 read via OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn is no longer required. The
171 \&\fIbytes_read\fR argument is always equal to the size of the buffer previously
172 provided in the crypto_receive_rcd_cb callback. Only one record at a time will
173 ever be read by OpenSSL.
174 .PP
175 The OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn callback (function id
176 \&\fBOSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET\fR) is called when a new secret has been
177 established. The \fIprot_level\fR argument identities the TLS protection level and
178 will be one of \fBOSSL_RECORD_PROTECTION_LEVEL_NONE\fR,
179 \&\fBOSSL_RECORD_PROTECTION_LEVEL_EARLY\fR, \fBOSSL_RECORD_PROTECTION_LEVEL_HANDSHAKE\fR
180 or \fBOSSL_RECORD_PROTECTION_LEVEL_APPLICATION\fR. The \fIdirection\fR will either be
181 0 (for the read secret) or 1 (for the write secret). The secret itself will
182 be in the buffer pointed to by \fIsecret\fR and the buffer will be of length
183 \&\fIsecret_len\fR.
184 .PP
185 The OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn callback (function id
186 \&\fBOSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS\fR) is called when transport
187 parameters have been received from the peer. The parameters are held in the
188 \&\fIparams\fR buffer which is of length \fIparams_len\fR.
189 .PP
190 The OSSL_FUNC_SSL_QUIC_TLS_alert_fn callback (function id
191 \&\fBOSSL_FUNC_SSL_QUIC_TLS_ALERT\fR) is called when OpenSSL is attempting to send an
192 alert to the peer. The code for the alert is supplied in \fIalert_code\fR.
193 .PP
194 The \fBSSL_set_quic_tls_transport_params()\fR function is used to set the transport
195 parameters to be sent by this endpoint. The parameters are in the \fIparams\fR
196 buffer which should be of length \fIparams_len\fR. The buffer containing the
197 parameters should remain valid until after the parameters have been sent. This
198 function must have been called by the time the transport parameters need to be
199 sent. For a client this will be before the connection has been initiated. For a
200 server this might typically occur during the got_transport_params_cb.
201 .PP
202 The \fBSSL_set_quic_tls_early_data_enabled()\fR function is used to enable the 0\-RTT
203 feature for a third party QUIC implementation.
204 .SH "RETURN VALUES"
205 .IX Header "RETURN VALUES"
206 These functions return 1 on success and 0 on failure.
207 .PP
208 All of the callbacks should also return 1 on success and 0 on failure. A
209 failure response is fatal to the connection.
210 .SH EXAMPLES
211 .IX Header "EXAMPLES"
212 A call to \fBSSL_set_quic_tls_cbs()\fR might look something like the following, given
213 suitable definitions of the various callback functions:
214 .PP
215 .Vb 10
216 \& const OSSL_DISPATCH qtdis[] = {
217 \& {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND, (void (*)(void))crypto_send_cb},
218 \& {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD,
219 \& (void (*)(void))crypto_recv_rcd_cb},
220 \& {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD,
221 \& (void (*)(void))crypto_release_rcd_cb},
222 \& {OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET,
223 \& (void (*)(void))yield_secret_cb},
224 \& {OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS,
225 \& (void (*)(void))got_transport_params_cb},
226 \& {OSSL_FUNC_SSL_QUIC_TLS_ALERT, (void (*)(void))alert_cb},
227 \& {0, NULL}
228 \& };
229 \&
230 \& if (!SSL_set_quic_tls_cbs(ssl, qtdis, NULL))
231 \& goto err;
232 .Ve
233 .SH HISTORY
234 .IX Header "HISTORY"
235 These functions were added in OpenSSL 3.5.
236 .SH COPYRIGHT
237 .IX Header "COPYRIGHT"
238 Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved.
239 .PP
240 Licensed under the Apache License 2.0 (the "License"). You may not use
241 this file except in compliance with the License. You can obtain a copy
242 in the file LICENSE in the source distribution or at
243 <https://www.openssl.org/source/license.html>.