From 730be78ce51479a352c596718bf62fc37ee7349f Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 20 Feb 2025 20:20:19 +0100 Subject: [PATCH 1/2] Document PSA's need for threading Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 43 +++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index ebc9276d20..3300f5f86c 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1807,6 +1807,11 @@ * running handshake hash) only use PSA crypto if * #MBEDTLS_USE_PSA_CRYPTO is enabled. * + * \note In multithreaded applications, you must also enable + * #MBEDTLS_THREADING_C, even if individual TLS contexts are not + * shared between threads, unless only one thread ever calls + * TLS functions. + * * Uncomment this macro to enable the support for TLS 1.3. */ #define MBEDTLS_SSL_PROTO_TLS1_3 @@ -2134,6 +2139,10 @@ * * \note See docs/use-psa-crypto.md for a complete description this option. * + * \note In multithreaded applications, you must also enable + * #MBEDTLS_THREADING_C, unless only one thread ever calls + * `psa_xxx()`, PK, X.509 or TLS functions. + * * Requires: MBEDTLS_PSA_CRYPTO_C. * * Uncomment this to enable internal use of PSA Crypto and new associated APIs. @@ -3211,7 +3220,10 @@ /** * \def MBEDTLS_PSA_CRYPTO_C * - * Enable the Platform Security Architecture cryptography API. + * Enable the Platform Security Architecture (PSA) cryptography API. + * + * \note In multithreaded applications, you must enable #MBEDTLS_THREADING_C, + * unless only one thread ever calls `psa_xxx()` functions. * * Module: library/psa_crypto.c * @@ -3631,10 +3643,33 @@ * \def MBEDTLS_THREADING_C * * Enable the threading abstraction layer. - * By default Mbed TLS assumes it is used in a non-threaded environment or that - * contexts are not shared between threads. If you do intend to use contexts + * + * Traditionally, Mbed TLS assumes it is used in a non-threaded environment or + * that contexts are not shared between threads. If you do intend to use contexts * between threads, you will need to enable this layer to prevent race - * conditions. See also our Knowledge Base article about threading: + * conditions. + * + * The PSA subsystem has an implicit shared context. Therefore, you must + * enable this option if more than one thread may use any part of + * Mbed TLS that is implemented on top of the PSA subsystem. + * + * You must enable this option in multithreaded applications where more than + * one thread performs any of the following operations: + * + * - Any call to a PSA function (`psa_xxx()`). + * - Any call to a TLS, X.509 or PK function (`mbedtls_ssl_xxx()`, + * `mbedtls_x509_xxx()`, `mbedtls_pkcs7_xxx()`, `mbedtls_pk_xxx()`) + * if `MBEDTLS_USE_PSA_CRYPTO` is enabled (regardless of whether individual + * TLS, X.509 or PK contexts are shared between threads). + * - A TLS 1.3 connection, regardless of the compile-time configuration. + * - Any library feature that calculates a hash, except for algorithm-specific + * low-level modules, if `MBEDTLS_MD_C` is disabled. + * - Any library feature that calculates a hash, except for algorithm-specific + * low-level modules, if `MBEDTLS_CIPHER_C` is disabled. + * - Any use of a cryptographic context if the same context is used in + * multiple threads. + * + * See also our Knowledge Base article about threading: * https://mbed-tls.readthedocs.io/en/latest/kb/development/thread-safety-and-multi-threading * * Module: library/threading.c From d3b3c6740f95c8141913e9627089a75d6e08d150 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 11 Mar 2025 14:45:54 +0100 Subject: [PATCH 2/2] More generally, what needs psa_crypto_init also needs threading Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 3300f5f86c..e16f31a64a 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -2130,6 +2130,10 @@ * before calling any function from the SSL/TLS, X.509 or PK modules, except * for the various mbedtls_xxx_init() functions which can be called at any time. * + * \warning In multithreaded applications, you must also enable + * #MBEDTLS_THREADING_C, unless only one thread ever calls PSA functions + * (`psa_xxx()`), including indirect calls through SSL/TLS, X.509 or PK. + * * \note An important and desirable effect of this option is that it allows * PK, X.509 and TLS to take advantage of PSA drivers. For example, enabling * this option is what allows use of drivers for ECDSA, ECDH and EC J-PAKE in @@ -2139,10 +2143,6 @@ * * \note See docs/use-psa-crypto.md for a complete description this option. * - * \note In multithreaded applications, you must also enable - * #MBEDTLS_THREADING_C, unless only one thread ever calls - * `psa_xxx()`, PK, X.509 or TLS functions. - * * Requires: MBEDTLS_PSA_CRYPTO_C. * * Uncomment this to enable internal use of PSA Crypto and new associated APIs. @@ -3224,6 +3224,14 @@ * * \note In multithreaded applications, you must enable #MBEDTLS_THREADING_C, * unless only one thread ever calls `psa_xxx()` functions. + * That includes indirect calls, such as: + * - performing a TLS handshake if support for TLS 1.3 is enabled; + * - using a TLS 1.3 connection; + * - indirect calls from PK, X.509 or SSL functions when + * #MBEDTLS_USE_PSA_CRYPTO is enabled; + * - indirect calls to calculate a hash when #MBEDTLS_MD_C is disabled; + * - any other call to a function that requires calling psa_crypto_init() + * beforehand. * * Module: library/psa_crypto.c * @@ -3662,12 +3670,17 @@ * if `MBEDTLS_USE_PSA_CRYPTO` is enabled (regardless of whether individual * TLS, X.509 or PK contexts are shared between threads). * - A TLS 1.3 connection, regardless of the compile-time configuration. - * - Any library feature that calculates a hash, except for algorithm-specific - * low-level modules, if `MBEDTLS_MD_C` is disabled. - * - Any library feature that calculates a hash, except for algorithm-specific - * low-level modules, if `MBEDTLS_CIPHER_C` is disabled. + * - Any library feature that calculates a hash, if `MBEDTLS_MD_C` is disabled. + * As an exception, algorithm-specific low-level modules do not require + * threading protection unless the contexts are shared between threads. + * - Any library feature that performs symmetric encryption or decryption, + * if `MBEDTLS_CIPHER_C` is disabled. + * As an exception, algorithm-specific low-level modules do not require + * threading protection unless the contexts are shared between threads. * - Any use of a cryptographic context if the same context is used in * multiple threads. + * - Any call to a function where the documentation specifies that + * psa_crypto_init() must be called prior to that function. * * See also our Knowledge Base article about threading: * https://mbed-tls.readthedocs.io/en/latest/kb/development/thread-safety-and-multi-threading