1=pod 2 3=head1 NAME 4 5OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn, 6OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn, 7OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn, 8OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn, 9OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn, 10OSSL_FUNC_SSL_QUIC_TLS_alert_fn, 11SSL_set_quic_tls_cbs, 12SSL_set_quic_tls_transport_params, 13SSL_set_quic_tls_early_data_enabled 14- Use the OpenSSL TLS implementation for a third party QUIC implementation 15 16=head1 SYNOPSIS 17 18 #include <openssl/ssl.h> 19 20 /* QUIC TLS callbacks available via an OSSL_DISPATCH table */ 21 22 /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND */ 23 typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn)(SSL *s, 24 const unsigned char *buf, 25 size_t buf_len, 26 size_t *consumed, 27 void *arg); 28 29 /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD */ 30 typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn)(SSL *s, 31 const unsigned char **buf, 32 size_t *bytes_read, 33 void *arg); 34 35 /* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD */ 36 typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn)(SSL *, 37 size_t bytes_read, 38 void *arg); 39 40 /* Function id: OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET */ 41 typedef int (*OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn)(SSL *s, 42 uint32_t prot_level, 43 int direction, 44 const unsigned char *secret, 45 size_t secret_len, 46 void *arg); 47 48 /* Function id: OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS */ 49 typedef int (*OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn)(SSL *s, 50 const unsigned char *params, 51 size_t params_len, 52 void *arg); 53 54 /* Function id: OSSL_FUNC_SSL_QUIC_TLS_ALERT */ 55 typedef int (*OSSL_FUNC_SSL_QUIC_TLS_alert_fn)(SSL *s, 56 unsigned char alert_code, 57 void *arg); 58 59 int SSL_set_quic_tls_cbs(SSL *s, const OSSL_DISPATCH *qtdis, void *arg); 60 int SSL_set_quic_tls_transport_params(SSL *s, 61 const unsigned char *params, 62 size_t params_len); 63 int SSL_set_quic_tls_early_data_enabled(SSL *s, int enabled); 64 65=head1 DESCRIPTION 66 67SSL_set_quic_tls_cbs() can be used to replace the standard TLS record layer with 68a custom record layer for use by a third party QUIC implementation. For the 69given SSL object I<s>, a set of callbacks are supplied in an B<OSSL_DISPATCH> 70table via I<qtdis>. The I<arg> parameter will be passed as an argument when the 71various callbacks are called. 72 73An B<OSSL_DISPATCH> table should consist of an array of B<OSSL_DISPATCH> entries 74where each entry is a function id, and a function pointer. The array should be 75terminated with an empty entry (i.e. a 0 function id, and a NULL function 76pointer). 77 78Calling the SSL_set_quic_tls_cbs() function will switch off the 79B<SSL_OP_ENABLE_MIDDLEBOX_COMPAT> option (if set). See L<SSL_set_options(3)>. 80Additionally the minimum TLS protocol version will be set to TLS1_3_VERSION. It 81is an error to call this function with anything other than a TLS connection SSL 82object. 83 84The OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn callback (function id 85B<OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND>) is called when CRYPTO frame data should 86be sent to the peer. The data to be sent is supplied in the buffer I<buf> which 87is of length I<buf_len>. The callback may choose to consume less data than was 88supplied in the buffer. On successful completion of the callback the I<consumed> 89parameter should be populated with the amount of data that the callback 90consumed. This should be less than or equal to the value in I<buf_len>. CRYPTO 91data should be sent using the most recent write encryption level set via the 92OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn callback (if it has been called). 93 94The OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn callback (function id 95B<OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD>) is used to receive CRYPTO frame data 96from the peer. When OpenSSL wants to read data from the peer this callback is 97called. The callback should populate I<*buf> with a pointer to a buffer 98containing CRYPTO data that has been received from the peer. The size of the 99buffer should be populated in I<*bytes_read>. The buffer should remain valid 100until OpenSSL calls the OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn callback. 101CRYPTO frame data is assumed to have been decrypted using the most recent read 102protection level set via the yield_secret_cb callback (if it has been called). 103 104The OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn callback (function id 105B<OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD>) is called when data previously 106read via OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn is no longer required. The 107I<bytes_read> argument is always equal to the size of the buffer previously 108provided in the crypto_receive_rcd_cb callback. Only one record at a time will 109ever be read by OpenSSL. 110 111The OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn callback (function id 112B<OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET>) is called when a new secret has been 113established. The I<prot_level> argument identities the TLS protection level and 114will be one of B<OSSL_RECORD_PROTECTION_LEVEL_NONE>, 115B<OSSL_RECORD_PROTECTION_LEVEL_EARLY>, B<OSSL_RECORD_PROTECTION_LEVEL_HANDSHAKE> 116or B<OSSL_RECORD_PROTECTION_LEVEL_APPLICATION>. The I<direction> will either be 1170 (for the read secret) or 1 (for the write secret). The secret itself will 118be in the buffer pointed to by I<secret> and the buffer will be of length 119I<secret_len>. 120 121The OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn callback (function id 122B<OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS>) is called when transport 123parameters have been received from the peer. The parameters are held in the 124I<params> buffer which is of length I<params_len>. 125 126The OSSL_FUNC_SSL_QUIC_TLS_alert_fn callback (function id 127B<OSSL_FUNC_SSL_QUIC_TLS_ALERT>) is called when OpenSSL is attempting to send an 128alert to the peer. The code for the alert is supplied in I<alert_code>. 129 130The SSL_set_quic_tls_transport_params() function is used to set the transport 131parameters to be sent by this endpoint. The parameters are in the I<params> 132buffer which should be of length I<params_len>. The buffer containing the 133parameters should remain valid until after the parameters have been sent. This 134function must have been called by the time the transport parameters need to be 135sent. For a client this will be before the connection has been initiated. For a 136server this might typically occur during the got_transport_params_cb. 137 138The SSL_set_quic_tls_early_data_enabled() function is used to enable the 0-RTT 139feature for a third party QUIC implementation. 140 141=head1 RETURN VALUES 142 143These functions return 1 on success and 0 on failure. 144 145All of the callbacks should also return 1 on success and 0 on failure. A 146failure response is fatal to the connection. 147 148=head1 EXAMPLES 149 150A call to SSL_set_quic_tls_cbs() might look something like the following, given 151suitable definitions of the various callback functions: 152 153 const OSSL_DISPATCH qtdis[] = { 154 {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND, (void (*)(void))crypto_send_cb}, 155 {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD, 156 (void (*)(void))crypto_recv_rcd_cb}, 157 {OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD, 158 (void (*)(void))crypto_release_rcd_cb}, 159 {OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET, 160 (void (*)(void))yield_secret_cb}, 161 {OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS, 162 (void (*)(void))got_transport_params_cb}, 163 {OSSL_FUNC_SSL_QUIC_TLS_ALERT, (void (*)(void))alert_cb}, 164 {0, NULL} 165 }; 166 167 if (!SSL_set_quic_tls_cbs(ssl, qtdis, NULL)) 168 goto err; 169 170=head1 HISTORY 171 172These functions were added in OpenSSL 3.5. 173 174=head1 COPYRIGHT 175 176Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved. 177 178Licensed under the Apache License 2.0 (the "License"). You may not use 179this file except in compliance with the License. You can obtain a copy 180in the file LICENSE in the source distribution or at 181L<https://www.openssl.org/source/license.html>. 182 183=cut 184