From 8c2830a06a70c62b4e0dd4a4a029390623ceef8f Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 4 Aug 2022 23:37:51 +0200 Subject: [PATCH] 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 --- include/mbedtls/mbedtls_config.h | 13 ++++++++----- include/mbedtls/ssl.h | 5 +++++ 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 5aff9c5b6..2dd370601 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 4b954bb45..2594964e1 100644 --- a/include/mbedtls/ssl.h +++ b/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);