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

Backport 3.6: Document the limitations of TLS handshake message defragmentation

ChangeLog.d/tls-hs-defrag-in.txt

@@ -1,12 +1,7 @@
 Bugfix
-   * Support re-assembly of fragmented handshake messages in TLS, as mandated
+   * Support re-assembly of fragmented handshake messages in TLS (both
-     by the spec. Lack of support was causing handshake failures with some
+     1.2 and 1.3). The lack of support was causing handshake failures with
-     servers, especially with TLS 1.3 in practice (though both protocol
+     some servers, especially with TLS 1.3 in practice. There are a few
-     version could be affected in principle, and both are fixed now).
+     limitations, notably a fragmented ClientHello is only supported when
-     The initial fragment for each handshake message must be at least 4 bytes.
+     TLS 1.3 support is enabled. See the documentation of
-
+     mbedtls_ssl_handshake() for details.
-     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.

include/mbedtls/ssl.h

@@ -4449,6 +4449,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().
@@ -4979,6 +4983,24 @@ int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl,
  *                 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);