diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/SSL_set_quic_tls_cbs.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/SSL_set_quic_tls_cbs.3 | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man3/SSL_set_quic_tls_cbs.3 b/secure/lib/libcrypto/man/man3/SSL_set_quic_tls_cbs.3 new file mode 100644 index 000000000000..5313795cd952 --- /dev/null +++ b/secure/lib/libcrypto/man/man3/SSL_set_quic_tls_cbs.3 @@ -0,0 +1,238 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (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 +.\" ======================================================================== +.\" +.IX Title "SSL_SET_QUIC_TLS_CBS 3ossl" +.TH SSL_SET_QUIC_TLS_CBS 3ossl 2025-07-01 3.5.1 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 +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>. |