Improve documentation of MBEDTLS_SSL_{MAX/IN/OUT}_CONTENT_LEN

Fixes #2062.
This commit is contained in:
Hanno Becker 2018-10-23 09:59:19 +01:00
parent 0592ea772a
commit b5d835f062

View file

@ -2977,31 +2977,65 @@
/** \def MBEDTLS_SSL_MAX_CONTENT_LEN /** \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 * To configure incoming and outgoing I/O buffers separately, use
* will override this length by setting maximum incoming and/or outgoing * #MBEDTLS_SSL_IN_CONTENT_LEN and #MBEDTLS_SSL_OUT_CONTENT_LEN,
* fragment length, respectively. * 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 //#define MBEDTLS_SSL_MAX_CONTENT_LEN 16384
/** \def MBEDTLS_SSL_IN_CONTENT_LEN /** \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 * This determines the size of the incoming TLS I/O buffer in such a way
* outward buffer. * 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 //#define MBEDTLS_SSL_IN_CONTENT_LEN 16384
/** \def MBEDTLS_SSL_OUT_CONTENT_LEN /** \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 * This determines the size of the outgoing TLS I/O buffer in such a way
* inward buffer. * 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 * 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. * 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 * The specific size requirement depends on the configured ciphers and any
* certificate data which is sent during the handshake. * certificate data which is sent during the handshake.
* *
* For absolute minimum RAM usage, it's best to enable * Uncomment to set the maximum plaintext size of the outgoing I/O buffer
* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH and reduce MBEDTLS_SSL_MAX_CONTENT_LEN. This * independently of the incoming I/O buffer.
* 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.
*/ */
//#define MBEDTLS_SSL_OUT_CONTENT_LEN 16384 //#define MBEDTLS_SSL_OUT_CONTENT_LEN 16384