Document the limitations of TLS handshake message defragmentation
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 597da25..e34e3af 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -4449,6 +4449,24 @@
* with \c mbedtls_ssl_read()), not handshake messages.
* With DTLS, this affects both ApplicationData and handshake.
*
+ * \note Defragmentation of incoming handshake messages in TLS
+ * (excluding DTLS) is supported with some limitations:
+ * - 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).
+ * - A ClientHello message that initiates a renegotiation
+ * must not be fragmented.
+ * - 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 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().