tls13: early data: Improve documentation

Signed-off-by: Ronald Cron <[email protected]>

Author: ronald-cron-arm

include/mbedtls/ssl.h

@@ -92,11 +92,12 @@
 #define MBEDTLS_ERR_SSL_CANNOT_READ_EARLY_DATA            -0x7B80
 /**
  * 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
- * returned by mbedtls_ssl_handshake(), mbedtls_ssl_handshake_step(),
- * mbedtls_ssl_read() and mbedtls_ssl_write() if early data has been received
- * as part of the handshake sequence they triggered. To read the early
- * data, call mbedtls_ssl_read_early_data().
+ * This error code can be returned only on server side if and only if early
+ * data has been enabled by means of the mbedtls_ssl_conf_early_data() API.
+ * This error code can then be returned by mbedtls_ssl_handshake(),
+ * mbedtls_ssl_handshake_step(), mbedtls_ssl_read() or mbedtls_ssl_write() if
+ * 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
 /** Not possible to write early data */
@@ -5101,6 +5102,21 @@ int mbedtls_ssl_close_notify(mbedtls_ssl_context *ssl);
  * \note           This API is server specific.
  *
  * \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
  *                 specification of mbedtls_ssl_read() relevant to TLS 1.3