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>

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.
  */

include/mbedtls/ssl.h

@@ -4684,6 +4684,11 @@ int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl,
  *                 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);