From: Matt Caswell Date: Tue, 20 Aug 2024 15:19:10 +0000 (+0100) Subject: Add documentation for the new third party QUIC stack API X-Git-Tag: openssl-3.5.0-alpha1~642 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=e6bb7eaee057c195f2f512bd5e28d094b36d6855;p=thirdparty%2Fopenssl.git Add documentation for the new third party QUIC stack API Reviewed-by: Tim Hudson Reviewed-by: Neil Horman Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/26683) --- diff --git a/doc/build.info b/doc/build.info index 9003540be42..8e6e4ea30c7 100644 --- a/doc/build.info +++ b/doc/build.info @@ -2783,6 +2783,10 @@ DEPEND[html/man3/SSL_set_incoming_stream_policy.html]=man3/SSL_set_incoming_stre GENERATE[html/man3/SSL_set_incoming_stream_policy.html]=man3/SSL_set_incoming_stream_policy.pod DEPEND[man/man3/SSL_set_incoming_stream_policy.3]=man3/SSL_set_incoming_stream_policy.pod GENERATE[man/man3/SSL_set_incoming_stream_policy.3]=man3/SSL_set_incoming_stream_policy.pod +DEPEND[html/man3/SSL_set_quic_tls_cbs.html]=man3/SSL_set_quic_tls_cbs.pod +GENERATE[html/man3/SSL_set_quic_tls_cbs.html]=man3/SSL_set_quic_tls_cbs.pod +DEPEND[man/man3/SSL_set_quic_tls_cbs.3]=man3/SSL_set_quic_tls_cbs.pod +GENERATE[man/man3/SSL_set_quic_tls_cbs.3]=man3/SSL_set_quic_tls_cbs.pod DEPEND[html/man3/SSL_set_retry_verify.html]=man3/SSL_set_retry_verify.pod GENERATE[html/man3/SSL_set_retry_verify.html]=man3/SSL_set_retry_verify.pod DEPEND[man/man3/SSL_set_retry_verify.3]=man3/SSL_set_retry_verify.pod @@ -3707,6 +3711,7 @@ html/man3/SSL_set_connect_state.html \ html/man3/SSL_set_default_stream_mode.html \ html/man3/SSL_set_fd.html \ html/man3/SSL_set_incoming_stream_policy.html \ +html/man3/SSL_set_quic_tls_cbs.html \ html/man3/SSL_set_retry_verify.html \ html/man3/SSL_set_session.html \ html/man3/SSL_set_session_secret_cb.html \ @@ -4372,6 +4377,7 @@ man/man3/SSL_set_connect_state.3 \ man/man3/SSL_set_default_stream_mode.3 \ man/man3/SSL_set_fd.3 \ man/man3/SSL_set_incoming_stream_policy.3 \ +man/man3/SSL_set_quic_tls_cbs.3 \ man/man3/SSL_set_retry_verify.3 \ man/man3/SSL_set_session.3 \ man/man3/SSL_set_session_secret_cb.3 \ diff --git a/doc/designs/quic-design/quic-tls.md b/doc/designs/quic-design/quic-tls.md index 122e3deb9da..064748d8d56 100644 --- a/doc/designs/quic-design/quic-tls.md +++ b/doc/designs/quic-design/quic-tls.md @@ -74,8 +74,8 @@ typedef struct quic_tls_args_st { size_t *bytes_read, void *arg); void *crypto_recv_cb_arg; - /* Called when a traffic secret is available for a given encryption level. */ - int (*yield_secret_cb)(uint32_t enc_level, int direction /* 0=RX, 1=TX */, + /* Called when a traffic secret is available for a given TLS protection level. */ + int (*yield_secret_cb)(uint32_t prot_level, int direction /* 0=RX, 1=TX */, uint32_t suite_id, EVP_MD *md, const unsigned char *secret, size_t secret_len, void *arg); diff --git a/doc/man3/SSL_set_quic_tls_cbs.pod b/doc/man3/SSL_set_quic_tls_cbs.pod new file mode 100644 index 00000000000..87a4d3a2142 --- /dev/null +++ b/doc/man3/SSL_set_quic_tls_cbs.pod @@ -0,0 +1,178 @@ +=pod + +=head1 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 +- Use the OpenSSL TLS implementation for a third party QUIC implementation + +=head1 SYNOPSIS + + #include + + /* 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); + +=head1 DESCRIPTION + +SSL_set_quic_tls_cbs() 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 I, a set of callbacks are supplied in an B +table via I. The I parameter will be passed as an argument when the +various callbacks are called. + +An B table should consist of an array of B 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). + +Calling the SSL_set_quic_tls_cbs() function will switch off the +B option (if set). See L. +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. + +The OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn callback (function id +B) is called when CRYPTO frame data should +be sent to the peer. The data to be sent is supplied in the buffer I which +is of length I. The callback may choose to consume less data than was +supplied in the buffer. On successful completion of the callback the I +parameter should be populated with the amount of data that the callback +consumed. This should be less than or equal to the value in I. 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). + +The OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn callback (function id +B) 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 I<*buf> 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 I<*bytes_read>. 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). + +The OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn callback (function id +B) is called when data previously +read via OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn is no longer required. The +I 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. + +The OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn callback (function id +B) is called when a new secret has been +established. The I argument identies the TLS protection level and +will be one of B, +B, B +or B. The I 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 I and the buffer will be of length +I. + +The OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn callback (function id +B) is called when transport +parameters have been received from the peer. The parameters are held in the +I buffer which is of length I. + +The OSSL_FUNC_SSL_QUIC_TLS_alert_fn callback (function id +B) is called when OpenSSL is attempting to send an +alert to the peer. The code for the alert is supplied in I. + +The SSL_set_quic_tls_transport_params() function is used to set the transport +parameters to be sent by this endpoint. The parameters are in the I +buffer which should be of length I. 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. + +=head1 RETURN VALUES + +These functions return 1 on success and 0 on failure. + +All of the callbacks should also return 1 on success and 0 on failure. A +failure response is fatal to the connection. + +=head1 EXAMPLES + +A call to SSL_set_quic_tls_cbs() might look something like the following, given +suitable definitions of the various callback functions: + + 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; + +=head1 HISTORY + +These functions were added in OpenSSL 3.5. + +=head1 COPYRIGHT + +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. + +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 +L. + +=cut diff --git a/util/other.syms b/util/other.syms index f8177792822..896592875a7 100644 --- a/util/other.syms +++ b/util/other.syms @@ -70,6 +70,12 @@ OSSL_ENCODER_CTX datatype OSSL_ENCODER_CONSTRUCT datatype OSSL_ENCODER_CLEANUP datatype OSSL_ENCODER_INSTANCE datatype +OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn datatype +OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn datatype +OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn datatype +OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn datatype +OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn datatype +OSSL_FUNC_SSL_QUIC_TLS_alert_fn datatype OSSL_HTTP_bio_cb_t datatype OSSL_HTTP_REQ_CTX datatype OSSL_IETF_ATTR_SYNTAX datatype