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