eden-emu/mbedtls
19
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

tls13: early data: Improve documentation

Browse source 
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
This commit is contained in:
Ronald Cron 2024-01-30 18:16:47 +01:00
parent 2c4308958d
commit 44d70a5f23
1 changed files with 52 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

75
include/mbedtls/ssl.h
View file

@ -92,11 +92,12 @@
#define MBEDTLS_ERR_SSL_CANNOT_READ_EARLY_DATA -0x7B80 #define MBEDTLS_ERR_SSL_CANNOT_READ_EARLY_DATA -0x7B80
/** /**
* Early data has been received as part of an on-going handshake. * Early data has been received as part of an on-going handshake.
* This error code can be returned only on server side. This error code can be * This error code can be returned only on server side if and only if early
* returned by mbedtls_ssl_handshake(), mbedtls_ssl_handshake_step(), * data has been enabled by means of the mbedtls_ssl_conf_early_data() API.
* mbedtls_ssl_read() and mbedtls_ssl_write() if early data has been received * This error code can then be returned by mbedtls_ssl_handshake(),
* as part of the handshake sequence they triggered. To read the early * mbedtls_ssl_handshake_step(), mbedtls_ssl_read() or mbedtls_ssl_write() if
* data, call mbedtls_ssl_read_early_data(). * early data has been received as part of the handshake sequence they
* triggered. To read the early data, call mbedtls_ssl_read_early_data().
*/ */
#define MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA -0x7C00 #define MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA -0x7C00
/** Not possible to write early data */ /** Not possible to write early data */
@ -2057,14 +2058,23 @@ void mbedtls_ssl_conf_authmode(mbedtls_ssl_config *conf, int authmode);
* \param conf The SSL configuration to use. * \param conf The SSL configuration to use.
* \param early_data_enabled can be: * \param early_data_enabled can be:
* *
* MBEDTLS_SSL_EARLY_DATA_DISABLED: early data functionality is disabled * MBEDTLS_SSL_EARLY_DATA_DISABLED:
* This is the default on client and server. * Early data functionality is disabled. This is the default on client and
* server.
* *
* MBEDTLS_SSL_EARLY_DATA_ENABLED: early data functionality is enabled and * MBEDTLS_SSL_EARLY_DATA_ENABLED:
* may be negotiated in the handshake. Application using * Early data functionality is enabled and may be negotiated in the handshake.
* early data functionality needs to be aware of the * Application using early data functionality needs to be aware that the
* lack of replay protection of the early data application * security properties for early data (also refered to as 0-RTT data) are
* payloads. * weaker than those for other kinds of TLS data. See the documentation of
* mbedtls_ssl_write_early_data() and mbedtls_ssl_read_early_data() for more
* information.
* When early data functionality is enabled on server and only in that case,
* the call to one of the APIs that trigger or resume an handshake sequence,
* namely mbedtls_ssl_handshake(), mbedtls_ssl_handshake_step(),
* mbedtls_ssl_read() or mbedtls_ssl_write() may return with the error code
* MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA indicating that some early data have
* been received. To read the early data, call mbedtls_ssl_read_early_data().
* *
* \warning This interface is experimental and may change without notice. * \warning This interface is experimental and may change without notice.
* *
@ -4791,9 +4801,11 @@ int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl,
* this case you must stop using the context (see below). * this case you must stop using the context (see below).
* \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as
* defined in RFC 8446 (TLS 1.3 specification), has been * defined in RFC 8446 (TLS 1.3 specification), has been
* received as part of the handshake. This is server specific. * received as part of the handshake. This is server specific
* You must call mbedtls_ssl_read_early_data() to read the * and may occur only if the early data feature has been
* early data before resuming the handshake. * enabled on server (see mbedtls_ssl_conf_early_data()
* documentation). You must call mbedtls_ssl_read_early_data()
* to read the early data before resuming the handshake.
* \return Another SSL error code - in this case you must stop using * \return Another SSL error code - in this case you must stop using
* the context (see below). * the context (see below).
* *
@ -4944,10 +4956,11 @@ int mbedtls_ssl_renegotiate(mbedtls_ssl_context *ssl);
* new connection using the same source port. See below. * new connection using the same source port. See below.
* \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as
* defined in RFC 8446 (TLS 1.3 specification), has been * defined in RFC 8446 (TLS 1.3 specification), has been
* received as part of an handshake triggered by the function. * received as part of the handshake. This is server specific
* This is server specific. You must call * and may occur only if the early data feature has been
* mbedtls_ssl_read_early_data() to read the early data before * enabled on server (see mbedtls_ssl_conf_early_data()
* resuming the reading of post handshake application data. * documentation). You must call mbedtls_ssl_read_early_data()
* to read the early data before resuming the handshake.
* \return Another SSL error code - in this case you must stop using * \return Another SSL error code - in this case you must stop using
* the context (see below). * the context (see below).
* *
@ -5025,10 +5038,11 @@ int mbedtls_ssl_read(mbedtls_ssl_context *ssl, unsigned char *buf, size_t len);
* the handshake when you're done attending other tasks. * the handshake when you're done attending other tasks.
* \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as
* defined in RFC 8446 (TLS 1.3 specification), has been * defined in RFC 8446 (TLS 1.3 specification), has been
* received as part of an handshake triggered by the function. * received as part of the handshake. This is server specific
* This is server specific. You must call * and may occur only if the early data feature has been
* mbedtls_ssl_read_early_data() to read the early data before * enabled on server (see mbedtls_ssl_conf_early_data()
* resuming the writing of application data. * documentation). You must call mbedtls_ssl_read_early_data()
* to read the early data before resuming the handshake.
* \return Another SSL error code - in this case you must stop using * \return Another SSL error code - in this case you must stop using
* the context (see below). * the context (see below).
* *
@ -5111,6 +5125,21 @@ int mbedtls_ssl_close_notify(mbedtls_ssl_context *ssl);
* \note This API is server specific. * \note This API is server specific.
* *
* \note Early data is defined in the TLS 1.3 specification, RFC 8446. * \note Early data is defined in the TLS 1.3 specification, RFC 8446.
* IMPORTANT NOTE from section 2.3 of the specification:
*
* The security properties for 0-RTT data are weaker than
* those for other kinds of TLS data. Specifically:
* - This data is not forward secret, as it is encrypted
* solely under keys derived using the offered PSK.
* - There are no guarantees of non-replay between connections.
* Protection against replay for ordinary TLS 1.3 1-RTT data
* is provided via the server's Random value, but 0-RTT data
* does not depend on the ServerHello and therefore has
* weaker guarantees. This is especially relevant if the
* data is authenticated either with TLS client
* authentication or inside the application protocol. The
* same warnings apply to any use of the
* early_exporter_master_secret.
* *
* \note This function behaves mainly as mbedtls_ssl_read(). The * \note This function behaves mainly as mbedtls_ssl_read(). The
* specification of mbedtls_ssl_read() relevant to TLS 1.3 * specification of mbedtls_ssl_read() relevant to TLS 1.3