Merge pull request #10040 from gilles-peskine-arm/tls-defragment-doc

Document the limitations of TLS handshake message defragmentation
This commit is contained in:
Manuel Pégourié-Gonnard 2025-03-12 13:00:15 +01:00 committed by GitHub
commit 70bab4e61f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 28 additions and 11 deletions

View File

@ -1,12 +1,7 @@
Bugfix
* Support re-assembly of fragmented handshake messages in TLS, as mandated
by the spec. Lack of support was causing handshake failures with some
servers, especially with TLS 1.3 in practice (though both protocol
version could be affected in principle, and both are fixed now).
The initial fragment for each handshake message must be at least 4 bytes.
Server-side, defragmentation of the ClientHello message is only
supported if the server accepts TLS 1.3 (regardless of whether the
ClientHello is 1.3 or 1.2). That is, servers configured (either
at compile time or at runtime) to only accept TLS 1.2 will
still fail the handshake if the ClientHello message is fragmented.
* Support re-assembly of fragmented handshake messages in TLS (both
1.2 and 1.3). The lack of support was causing handshake failures with
some servers, especially with TLS 1.3 in practice. There are a few
limitations, notably a fragmented ClientHello is only supported when
TLS 1.3 support is enabled. See the documentation of
mbedtls_ssl_handshake() for details.

View File

@ -4360,6 +4360,10 @@ void mbedtls_ssl_conf_cert_req_ca_list(mbedtls_ssl_config *conf,
* with \c mbedtls_ssl_read()), not handshake messages.
* With DTLS, this affects both ApplicationData and handshake.
*
* \note Defragmentation of TLS handshake messages is supported
* with some limitations. See the documentation of
* mbedtls_ssl_handshake() for details.
*
* \note This sets the maximum length for a record's payload,
* excluding record overhead that will be added to it, see
* \c mbedtls_ssl_get_record_expansion().
@ -4849,6 +4853,24 @@ int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl,
* currently being processed might or might not contain further
* DTLS records.
*
* \note In TLS, reception of fragmented handshake messages is
* supported with some limitations (those limitations do
* not apply to DTLS, where defragmentation is fully
* supported):
* - On an Mbed TLS server that only accepts TLS 1.2,
* the initial ClientHello message must not be fragmented.
* A TLS 1.2 ClientHello may be fragmented if the server
* also accepts TLS 1.3 connections (meaning
* that #MBEDTLS_SSL_PROTO_TLS1_3 enabled, and the
* accepted versions have not been restricted with
* mbedtls_ssl_conf_max_tls_version() or the like).
* - The first fragment of a handshake message must be
* at least 4 bytes long.
* - Non-handshake records must not be interleaved between
* the fragments of a handshake message. (This is permitted
* in TLS 1.2 but not in TLS 1.3, but Mbed TLS rejects it
* even in TLS 1.2.)
*
* \note The PSA crypto subsystem must have been initialized by
* calling psa_crypto_init() before calling this function.
*/