Merge pull request #10055 from gilles-peskine-arm/tls-defragment-doc-3.6
Backport 3.6: Document the limitations of TLS handshake message defragmentation
diff --git a/ChangeLog.d/tls-hs-defrag-in.txt b/ChangeLog.d/tls-hs-defrag-in.txt
index 4fd4a4e..6bab02a 100644
--- a/ChangeLog.d/tls-hs-defrag-in.txt
+++ b/ChangeLog.d/tls-hs-defrag-in.txt
@@ -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.
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 597da25..97b0dcb 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -4449,6 +4449,10 @@
* 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().
@@ -4979,6 +4983,24 @@
* if a negotiation involving TLS 1.3 takes place (this may
* be the case even if TLS 1.3 is offered but eventually
* not selected).
+ *
+ * \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.)
*/
int mbedtls_ssl_handshake(mbedtls_ssl_context *ssl);