Document what "TLS 1.3 depends on PSA" entails
Explicitly document that when using TLS 1.3, you must initialize PSA crypto
before starting a handshake.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h
index 5aff9c5..2dd3706 100644
--- a/include/mbedtls/mbedtls_config.h
+++ b/include/mbedtls/mbedtls_config.h
@@ -1578,11 +1578,14 @@
* Requires: MBEDTLS_SSL_KEEP_PEER_CERTIFICATE
* Requires: MBEDTLS_PSA_CRYPTO_C
*
- * Note: even though TLS 1.3 depends on PSA Crypto, and uses it unconditionally
- * for most operations, if you want it to only use PSA for all crypto
- * operations, you need to also enable MBEDTLS_USE_PSA_CRYPTO; otherwise X.509
- * operations, and functions that are common with TLS 1.2 (record protection,
- * running handshake hash) will still use non-PSA crypto.
+ * \note TLS 1.3 uses PSA crypto for cryptographic operations that are
+ * directly performed by TLS 1.3 code. As a consequence, you must
+ * call psa_crypto_init() before the first TLS 1.3 handshake.
+ *
+ * \note Cryptographic operations performed indirectly via another module
+ * (X.509, PK) or by code shared with TLS 1.2 (record protection,
+ * running handshake hash) only use PSA crypto if
+ * #MBEDTLS_USE_PSA_CRYPTO is enabled.
*
* Uncomment this macro to enable the support for TLS 1.3.
*/
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 4b954bb..2594964 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -4684,6 +4684,11 @@
* in which case the datagram of the underlying transport that is
* currently being processed might or might not contain further
* DTLS records.
+ *
+ * \note If the context is configured to allow TLS 1.3, or if
+ * #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
+ * subsystem must have been initialized by calling
+ * psa_crypto_init() before calling this function.
*/
int mbedtls_ssl_handshake(mbedtls_ssl_context *ssl);