From b5d835f062f41ca75ff9773e16a610d0bb41f589 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Tue, 23 Oct 2018 09:59:19 +0100 Subject: [PATCH 1/2] Improve documentation of MBEDTLS_SSL_{MAX/IN/OUT}_CONTENT_LEN Fixes #2062. --- include/mbedtls/config.h | 63 ++++++++++++++++++++++++++++++---------- 1 file changed, 47 insertions(+), 16 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 81438c5b1..96166c676 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -2977,31 +2977,65 @@ /** \def MBEDTLS_SSL_MAX_CONTENT_LEN * - * Maximum fragment length in bytes. + * Maximum length (in bytes) of incoming and outgoing plaintext fragments. * - * Determines the size of both the incoming and outgoing TLS I/O buffers. + * This determines the size of both the incoming and outgoing TLS I/O buffers + * in such a way that both are capable of holding the specified amount of + * plaintext data, regardless of the protection mechanism used. * - * Uncommenting MBEDTLS_SSL_IN_CONTENT_LEN and/or MBEDTLS_SSL_OUT_CONTENT_LEN - * will override this length by setting maximum incoming and/or outgoing - * fragment length, respectively. + * To configure incoming and outgoing I/O buffers separately, use + * #MBEDTLS_SSL_IN_CONTENT_LEN and #MBEDTLS_SSL_OUT_CONTENT_LEN, + * which overwrite the value set by this option. + * + * \note When using a value less than the default of 16KB on the client, it is + * recommended to use the Maximum Fragment Length (MFL) extension to + * to inform the server about this limitation. On the server, there + * is no supported, standardized way of informing the client about + * restriction on the maximum size of incoming messages, and unless + * the limitation has been communicated by other means, it is recommended + * to only change the outgoing buffer size #MBEDTLS_SSL_OUT_CONTENT_LEN + * while keeping the default value of 16KB for the incoming buffer. + * + * Uncomment to set the maximum plaintext size of both + * incoming and outgoing I/O buffers. */ //#define MBEDTLS_SSL_MAX_CONTENT_LEN 16384 /** \def MBEDTLS_SSL_IN_CONTENT_LEN * - * Maximum incoming fragment length in bytes. + * Maximum length (in bytes) of incoming plaintext fragments. * - * Uncomment to set the size of the inward TLS buffer independently of the - * outward buffer. + * This determines the size of the incoming TLS I/O buffer in such a way + * that it is capable of holding the specified amount of plaintext data, + * regardless of the protection mechanism used. + * + * If this option is undefined, it inherits its value from + * #MBEDTLS_SSL_MAX_CONTENT_LEN. + * + * \note When using a value less than the default of 16KB on the client, it is + * recommended to use the Maximum Fragment Length (MFL) extension to + * to inform the server about this limitation. On the server, there + * is no supported, standardized way of informing the client about + * restriction on the maximum size of incoming messages, and unless + * the limitation has been communicated by other means, it is recommended + * to only change the outgoing buffer size #MBEDTLS_SSL_OUT_CONTENT_LEN + * while keeping the default value of 16KB for the incoming buffer. + * + * Uncomment to set the maximum plaintext size of the incoming I/O buffer + * independently of the outgoing I/O buffer. */ //#define MBEDTLS_SSL_IN_CONTENT_LEN 16384 /** \def MBEDTLS_SSL_OUT_CONTENT_LEN * - * Maximum outgoing fragment length in bytes. + * Maximum length (in bytes) of outgoing plaintext fragments. * - * Uncomment to set the size of the outward TLS buffer independently of the - * inward buffer. + * This determines the size of the outgoing TLS I/O buffer in such a way + * that it is capable of holding the specified amount of plaintext data, + * regardless of the protection mechanism used. + * + * If this option undefined, it inherits its value from + * #MBEDTLS_SSL_MAX_CONTENT_LEN. * * It is possible to save RAM by setting a smaller outward buffer, while keeping * the default inward 16384 byte buffer to conform to the TLS specification. @@ -3011,11 +3045,8 @@ * The specific size requirement depends on the configured ciphers and any * certificate data which is sent during the handshake. * - * For absolute minimum RAM usage, it's best to enable - * MBEDTLS_SSL_MAX_FRAGMENT_LENGTH and reduce MBEDTLS_SSL_MAX_CONTENT_LEN. This - * reduces both incoming and outgoing buffer sizes. However this is only - * guaranteed if the other end of the connection also supports the TLS - * max_fragment_len extension. Otherwise the connection may fail. + * Uncomment to set the maximum plaintext size of the outgoing I/O buffer + * independently of the incoming I/O buffer. */ //#define MBEDTLS_SSL_OUT_CONTENT_LEN 16384 From 8e5301165e9e74055a55a6ccfd21b6ea6e5693e1 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Thu, 25 Oct 2018 14:01:41 +0100 Subject: [PATCH 2/2] Correct typo in documentation of MBEDTLS_SSL_MAX_CONTENT_LEN --- include/mbedtls/config.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 96166c676..415ac6352 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -2989,7 +2989,7 @@ * * \note When using a value less than the default of 16KB on the client, it is * recommended to use the Maximum Fragment Length (MFL) extension to - * to inform the server about this limitation. On the server, there + * inform the server about this limitation. On the server, there * is no supported, standardized way of informing the client about * restriction on the maximum size of incoming messages, and unless * the limitation has been communicated by other means, it is recommended @@ -3014,7 +3014,7 @@ * * \note When using a value less than the default of 16KB on the client, it is * recommended to use the Maximum Fragment Length (MFL) extension to - * to inform the server about this limitation. On the server, there + * inform the server about this limitation. On the server, there * is no supported, standardized way of informing the client about * restriction on the maximum size of incoming messages, and unless * the limitation has been communicated by other means, it is recommended