1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
.\" $NetBSD: SSL_set_quic_tls_cbs.3,v 1.5 2026/04/08 17:06:49 christos Exp $
.\"
.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "SSL_set_quic_tls_cbs 3"
.TH SSL_set_quic_tls_cbs 3 2026-04-07 3.5.6 OpenSSL
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn,
OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn,
OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn,
OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn,
OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn,
OSSL_FUNC_SSL_QUIC_TLS_alert_fn,
SSL_set_quic_tls_cbs,
SSL_set_quic_tls_transport_params,
SSL_set_quic_tls_early_data_enabled
\&\- Use the OpenSSL TLS implementation for a third party QUIC implementation
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/ssl.h>
\&
\& /* QUIC TLS callbacks available via an OSSL_DISPATCH table */
\&
\& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND */
\& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn)(SSL *s,
\& const unsigned char *buf,
\& size_t buf_len,
\& size_t *consumed,
\& void *arg);
\&
\& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD */
\& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn)(SSL *s,
\& const unsigned char **buf,
\& size_t *bytes_read,
\& void *arg);
\&
\& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD */
\& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn)(SSL *,
\& size_t bytes_read,
\& void *arg);
\&
\& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET */
\& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn)(SSL *s,
\& uint32_t prot_level,
\& int direction,
\& const unsigned char *secret,
\& size_t secret_len,
\& void *arg);
\&
\& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS */
\& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn)(SSL *s,
\& const unsigned char *params,
\& size_t params_len,
\& void *arg);
\&
\& /* Function id: OSSL_FUNC_SSL_QUIC_TLS_ALERT */
\& typedef int (*OSSL_FUNC_SSL_QUIC_TLS_alert_fn)(SSL *s,
\& unsigned char alert_code,
\& void *arg);
\&
\& int SSL_set_quic_tls_cbs(SSL *s, const OSSL_DISPATCH *qtdis, void *arg);
\& int SSL_set_quic_tls_transport_params(SSL *s,
\& const unsigned char *params,
\& size_t params_len);
\& int SSL_set_quic_tls_early_data_enabled(SSL *s, int enabled);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBSSL_set_quic_tls_cbs()\fR can be used to replace the standard TLS record layer with
a custom record layer for use by a third party QUIC implementation. For the
given SSL object \fIs\fR, a set of callbacks are supplied in an \fBOSSL_DISPATCH\fR
table via \fIqtdis\fR. The \fIarg\fR parameter will be passed as an argument when the
various callbacks are called.
.PP
The above callbacks are invoked, as needed, by \fBSSL_do_handshake()\fR and \fBSSL_read()\fR (including
SSL_read_ex, SSL_peek, SSL_peek_ex). Once the SSL handshake is complete, the QUIC
stack must arrange to call one of the \fBSSL_read()\fR variants whenever a post\-handshake CRYPTO
frame is received. The number of bytes requested may be zero.
.PP
An \fBOSSL_DISPATCH\fR table should consist of an array of \fBOSSL_DISPATCH\fR entries
where each entry is a function id, and a function pointer. The array should be
terminated with an empty entry (i.e. a 0 function id, and a NULL function
pointer).
.PP
Calling the \fBSSL_set_quic_tls_cbs()\fR function will switch off the
\&\fBSSL_OP_ENABLE_MIDDLEBOX_COMPAT\fR option (if set). See \fBSSL_set_options\fR\|(3).
Additionally the minimum TLS protocol version will be set to TLS1_3_VERSION. It
is an error to call this function with anything other than a TLS connection SSL
object.
.PP
The OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn callback (function id
\&\fBOSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND\fR) is called when CRYPTO frame data should
be sent to the peer. The data to be sent is supplied in the buffer \fIbuf\fR which
is of length \fIbuf_len\fR. The callback may choose to consume less data than was
supplied in the buffer. On successful completion of the callback the \fIconsumed\fR
parameter should be populated with the amount of data that the callback
consumed. This should be less than or equal to the value in \fIbuf_len\fR. CRYPTO
data should be sent using the most recent write encryption level set via the
OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn callback (if it has been called).
.PP
The OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn callback (function id
\&\fBOSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD\fR) is used to receive CRYPTO frame data
from the peer. When OpenSSL wants to read data from the peer this callback is
called. The callback should populate \fI*buf\fR with a pointer to a buffer
containing CRYPTO data that has been received from the peer. The size of the
buffer should be populated in \fI*bytes_read\fR. The buffer should remain valid
until OpenSSL calls the OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn callback.
CRYPTO frame data is assumed to have been decrypted using the most recent read
protection level set via the yield_secret_cb callback (if it has been called).
.PP
The OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn callback (function id
\&\fBOSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD\fR) is called when data previously
read via OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn is no longer required. The
\&\fIbytes_read\fR argument is always equal to the size of the buffer previously
provided in the crypto_receive_rcd_cb callback. Only one record at a time will
ever be read by OpenSSL.
.PP
The OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn callback (function id
\&\fBOSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET\fR) is called when a new secret has been
established. The \fIprot_level\fR argument identities the TLS protection level and
will be one of \fBOSSL_RECORD_PROTECTION_LEVEL_NONE\fR,
\&\fBOSSL_RECORD_PROTECTION_LEVEL_EARLY\fR, \fBOSSL_RECORD_PROTECTION_LEVEL_HANDSHAKE\fR
or \fBOSSL_RECORD_PROTECTION_LEVEL_APPLICATION\fR. The \fIdirection\fR will either be
0 (for the read secret) or 1 (for the write secret). The secret itself will
be in the buffer pointed to by \fIsecret\fR and the buffer will be of length
\&\fIsecret_len\fR.
.PP
The OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn callback (function id
\&\fBOSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS\fR) is called when transport
parameters have been received from the peer. The parameters are held in the
\&\fIparams\fR buffer which is of length \fIparams_len\fR.
.PP
The OSSL_FUNC_SSL_QUIC_TLS_alert_fn callback (function id
\&\fBOSSL_FUNC_SSL_QUIC_TLS_ALERT\fR) is called when OpenSSL is attempting to send an
alert to the peer. The code for the alert is supplied in \fIalert_code\fR.
.PP
The \fBSSL_set_quic_tls_transport_params()\fR function is used to set the transport
parameters to be sent by this endpoint. The parameters are in the \fIparams\fR
buffer which should be of length \fIparams_len\fR. The buffer containing the
parameters should remain valid until after the parameters have been sent. This
function must have been called by the time the transport parameters need to be
sent. For a client this will be before the connection has been initiated. For a
server this might typically occur during the got_transport_params_cb.
.PP
The \fBSSL_set_quic_tls_early_data_enabled()\fR function is used to enable the 0\-RTT
feature for a third party QUIC implementation.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
These functions return 1 on success and 0 on failure.
.PP
All of the callbacks should also return 1 on success and 0 on failure. A
failure response is fatal to the connection.
.SH EXAMPLES
.IX Header "EXAMPLES"
A call to \fBSSL_set_quic_tls_cbs()\fR might look something like the following, given
suitable definitions of the various callback functions:
.PP
.Vb 10
\& const OSSL_DISPATCH qtdis[] = {
\& {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND, (void (*)(void))crypto_send_cb},
\& {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD,
\& (void (*)(void))crypto_recv_rcd_cb},
\& {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD,
\& (void (*)(void))crypto_release_rcd_cb},
\& {OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET,
\& (void (*)(void))yield_secret_cb},
\& {OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS,
\& (void (*)(void))got_transport_params_cb},
\& {OSSL_FUNC_SSL_QUIC_TLS_ALERT, (void (*)(void))alert_cb},
\& {0, NULL}
\& };
\&
\& if (!SSL_set_quic_tls_cbs(ssl, qtdis, NULL))
\& goto err;
.Ve
.SH HISTORY
.IX Header "HISTORY"
These functions were added in OpenSSL 3.5.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
<https://www.openssl.org/source/license.html>.
|
