Merge pull request #1425 from gilles-peskine-arm/restricted-3.6-merge-public-20250916

3.6: : merge public into restricted 2025-09-16

ChangeLog.d/fix-dependency-on-generated-files.txt

@@ -0,0 +1,3 @@
+Bugfix
+    * Fix potential CMake parallel build failure when building both the static
+      and shared libraries.

ChangeLog.d/psa_can_do_cipher.txt

@@ -0,0 +1,5 @@
+API changes
+   * When building the library as a PSA client (MBEDTLS_PSA_CRYPTO_CLIENT
+     enabled and MBEDTLS_PSA_CRYPTO_C disabled), you need to provide the
+     function psa_can_do_cipher() in addition to psa_can_do_hash(). This
+     changed was made in Mbed TLS 3.6.0 but was not announced then.

README.md

@@ -72,7 +72,13 @@ The following tools are required:
     Depending on your Python installation, you may need to invoke `python` instead of `python3`. To install the packages system-wide, omit the `--user` option.
 * A C compiler for the host platform, for some test data.
 
-If you are cross-compiling, you must set the `CC` environment variable to a C compiler for the host platform when generating the configuration-independent files.
+The scripts that generate the configuration-independent files will look for a host C compiler in the following places (in order of preference):
+
+1. The `HOSTCC` environment variable. This can be used if `CC` is pointing to a cross-compiler.
+2. The `CC` environment variable.
+3. An executable called `cc` in the current path.
+
+Note: If you have multiple toolchains installed, it is recommended to set `CC` or `HOSTCC` to the intended host compiler before generating the files.
 
 Any of the following methods are available to generate the configuration-independent files:
 

docs/requirements.txt

@@ -1,84 +1,83 @@
 #
-# This file is autogenerated by pip-compile with Python 3.8
+# This file is autogenerated by pip-compile with Python 3.9
 # by the following command:
 #
-#    pip-compile requirements.in
+#    pip-compile docs/requirements.in
 #
-alabaster==0.7.13
+alabaster==0.7.16
     # via sphinx
-babel==2.15.0
+babel==2.17.0
     # via sphinx
-breathe==4.35.0
-    # via -r requirements.in
-certifi==2024.7.4
+breathe==4.36.0
+    # via -r docs/requirements.in
+certifi==2025.8.3
     # via requests
-charset-normalizer==3.3.2
+charset-normalizer==3.4.3
     # via requests
-click==8.1.7
+click==8.1.8
     # via readthedocs-cli
-docutils==0.20.1
+docutils==0.21.2
     # via
-    #   breathe
     #   sphinx
     #   sphinx-rtd-theme
-idna==3.7
+idna==3.10
     # via requests
 imagesize==1.4.1
     # via sphinx
-importlib-metadata==8.0.0
+importlib-metadata==8.7.0
     # via sphinx
-jinja2==3.1.4
+jinja2==3.1.6
     # via sphinx
 markdown-it-py==3.0.0
     # via rich
-markupsafe==2.1.5
+markupsafe==3.0.2
     # via jinja2
 mdurl==0.1.2
     # via markdown-it-py
-packaging==24.1
+packaging==25.0
     # via sphinx
-pygments==2.18.0
+pygments==2.19.2
     # via
     #   rich
     #   sphinx
-pytz==2024.1
-    # via babel
-pyyaml==6.0.1
+pyyaml==6.0.2
     # via readthedocs-cli
-readthedocs-cli==4
-    # via -r requirements.in
-requests==2.32.3
+readthedocs-cli==5
+    # via -r docs/requirements.in
+requests==2.32.5
     # via
     #   readthedocs-cli
     #   sphinx
-rich==13.7.1
+rich==14.1.0
     # via readthedocs-cli
-snowballstemmer==2.2.0
+snowballstemmer==3.0.1
     # via sphinx
-sphinx==7.1.2
+sphinx==7.4.7
     # via
     #   breathe
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
-sphinx-rtd-theme==2.0.0
-    # via -r requirements.in
-sphinxcontrib-applehelp==1.0.4
+sphinx-rtd-theme==3.0.2
+    # via -r docs/requirements.in
+sphinxcontrib-applehelp==2.0.0
     # via sphinx
-sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-devhelp==2.0.0
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
 sphinxcontrib-jquery==4.1
     # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-qthelp==2.0.0
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
-typing-extensions==4.12.2
-    # via rich
-urllib3==2.2.2
-    # via requests
-zipp==3.19.2
+tomli==2.2.1
+    # via sphinx
+urllib3==2.5.0
+    # via
+    #   readthedocs-cli
+    #   requests
+zipp==3.23.0
     # via importlib-metadata

include/mbedtls/mbedtls_config.h

@@ -2150,7 +2150,19 @@
 /**
  * \def MBEDTLS_THREADING_ALT
  *
- * Provide your own alternate threading implementation.
+ * Provide your own alternate implementation of threading primitives
+ * for mutexes. If you enable this option:
+ *
+ * - Provide a header file `"threading_alt.h"`, defining the
+ *   type `mbedtls_threading_mutex_t` of mutex objects.
+ *
+ * - Call the function mbedtls_threading_set_alt() in your application
+ *   before calling any other library function (in particular before
+ *   calling psa_crypto_init(), performing an asymmetric cryptography
+ *   operation, or starting a TLS connection).
+ *
+ * See mbedtls/threading.h for more details, especially the documentation
+ * of mbedtls_threading_set_alt().
  *
  * Requires: MBEDTLS_THREADING_C
  *

include/mbedtls/threading.h

@@ -51,15 +51,45 @@ typedef struct mbedtls_threading_mutex_t {
  *                  mbedtls_threading_free_alt() must be called once in the main
  *                  thread after all other Mbed TLS functions.
  *
- * \note            mutex_init() and mutex_free() don't return a status code.
- *                  If mutex_init() fails, it should leave its argument (the
- *                  mutex) in a state such that mutex_lock() will fail when
- *                  called with this argument.
+ * \warning         \p mutex_init and \p mutex_free don't return a status code.
+ *                  If \p mutex_init fails, it should leave the mutex in
+ *                  a state such that \p mutex_lock will reliably return
+ *                  #MBEDTLS_ERR_THREADING_MUTEX_ERROR called on this mutex,
+ *                  and \p mutex_free will do nothing.
  *
- * \param mutex_init    the init function implementation
- * \param mutex_free    the free function implementation
- * \param mutex_lock    the lock function implementation
- * \param mutex_unlock  the unlock function implementation
+ * \param mutex_init    The init function implementation. <br>
+ *                      The behavior is undefined if the mutex is already
+ *                      initialized and has not been destroyed.
+ *                      On platforms where mutex initialization can fail,
+ *                      since this function does not return a status code,
+ *                      it must leave the mutex object in a safe state where
+ *                      subsequent function calls will not cause undefined
+ *                      behavior: after a call to \p mutex_init, the
+ *                      function \p mutex_lock must either succeed or
+ *                      fail with a nonzero status code, and the function
+ *                      \p mutex_free must free any resources associated
+ *                      with the mutex..
+ * \param mutex_free    The destroy function implementation. <br>
+ *                      This function must free any resources associated
+ *                      with the mutex object. <br>
+ *                      This function must work reliably if \p mutex_init
+ *                      has been called on the mutex and \p mutex_free
+ *                      has not yet been called. <br>
+ *                      The behavior is undefined if the mutex was not
+ *                      initialized, if it has already been destroyed,
+ *                      if it is currently locked, or if this function
+ *                      is called concurrently from multiple threads.
+ * \param mutex_lock    The lock function implementation. <br>
+ *                      This function must work reliably on any mutex
+ *                      which is not currently locked and on which
+ *                      \p mutex_init has already been called but
+ *                      \p mutex_free has not been called yet. <br>
+ *                      The behavior is undefined if the mutex was not
+ *                      initialized, if it has already been destroyed, or if
+ *                      it is currently locked by the calling thread.
+ * \param mutex_unlock  The unlock function implementation. <br>
+ *                      The behavior is undefined if the mutex is not
+ *                      currently locked by the calling thread.
  */
 void mbedtls_threading_set_alt(void (*mutex_init)(mbedtls_threading_mutex_t *),
                                void (*mutex_free)(mbedtls_threading_mutex_t *),

include/psa/crypto_extra.h

@@ -600,9 +600,10 @@ psa_status_t mbedtls_psa_platform_get_builtin_key(
  * This means that PSA core was built with the corresponding PSA_WANT_ALG_xxx
  * set and that psa_crypto_init has already been called.
  *
- * \note When using Mbed TLS version of PSA core (i.e. MBEDTLS_PSA_CRYPTO_C is
- *       set) for now this function only checks the state of the driver
- *       subsystem, not the algorithm. This might be improved in the future.
+ * \note When using the built-in version of the PSA core (i.e.
+ *       #MBEDTLS_PSA_CRYPTO_C is set), for now, this function only checks
+ *       the state of the driver subsystem, not the algorithm.
+ *       This might be improved in the future.
  *
  * \param hash_alg  The hash algorithm.
  *
@@ -610,6 +611,21 @@ psa_status_t mbedtls_psa_platform_get_builtin_key(
  */
 int psa_can_do_hash(psa_algorithm_t hash_alg);
 
+/**
+ * Tell if PSA is ready for this cipher.
+ *
+ * \note When using the built-in version of the PSA core (i.e.
+ *       #MBEDTLS_PSA_CRYPTO_C is set), for now, this function only checks
+ *       the state of the driver subsystem, not the key type and algorithm.
+ *       This might be improved in the future.
+ *
+ * \param key_type    The key type.
+ * \param cipher_alg  The cipher algorithm.
+ *
+ * \return 1 if the PSA can handle \p cipher_alg, 0 otherwise.
+ */
+int psa_can_do_cipher(psa_key_type_t key_type, psa_algorithm_t cipher_alg);
+
 /**@}*/
 
 /** \addtogroup crypto_types

library/CMakeLists.txt

@@ -188,12 +188,18 @@ if(GEN_FILES)
             ${CMAKE_CURRENT_SOURCE_DIR}/../scripts/data_files/driver_templates/psa_crypto_driver_wrappers_no_static.c.jinja
     )
 
+    add_custom_target(${MBEDTLS_TARGET_PREFIX}mbedcrypto_generated_files_target
+        DEPENDS
+            ${CMAKE_CURRENT_BINARY_DIR}/error.c
+            ${CMAKE_CURRENT_BINARY_DIR}/version_features.c
+            ${CMAKE_CURRENT_BINARY_DIR}/psa_crypto_driver_wrappers.h
+            ${CMAKE_CURRENT_BINARY_DIR}/psa_crypto_driver_wrappers_no_static.c
+    )
 
-else()
-    link_to_source(error.c)
-    link_to_source(version_features.c)
-    link_to_source(ssl_debug_helpers_generated.c)
-    link_to_source(psa_crypto_driver_wrappers_no_static.c)
+    add_custom_target(${MBEDTLS_TARGET_PREFIX}mbedtls_generated_files_target
+        DEPENDS
+            ${CMAKE_CURRENT_BINARY_DIR}/ssl_debug_helpers_generated.c
+    )
 endif()
 
 if(CMAKE_COMPILER_IS_GNUCC)
@@ -295,6 +301,13 @@ if(USE_STATIC_MBEDTLS_LIBRARY)
     add_library(${mbedtls_static_target} STATIC ${src_tls})
     set_target_properties(${mbedtls_static_target} PROPERTIES OUTPUT_NAME mbedtls)
     target_link_libraries(${mbedtls_static_target} PUBLIC ${libs} ${mbedx509_static_target})
+
+    if(GEN_FILES)
+        add_dependencies(${mbedcrypto_static_target}
+            ${MBEDTLS_TARGET_PREFIX}mbedcrypto_generated_files_target)
+        add_dependencies(${mbedtls_static_target}
+            ${MBEDTLS_TARGET_PREFIX}mbedtls_generated_files_target)
+    endif()
 endif(USE_STATIC_MBEDTLS_LIBRARY)
 
 if(USE_SHARED_MBEDTLS_LIBRARY)
@@ -318,6 +331,13 @@ if(USE_SHARED_MBEDTLS_LIBRARY)
     add_library(${mbedtls_target} SHARED ${src_tls})
     set_target_properties(${mbedtls_target} PROPERTIES VERSION 3.6.4 SOVERSION 21)
     target_link_libraries(${mbedtls_target} PUBLIC ${libs} ${mbedx509_target})
+
+    if(GEN_FILES)
+        add_dependencies(${mbedcrypto_target}
+            ${MBEDTLS_TARGET_PREFIX}mbedcrypto_generated_files_target)
+        add_dependencies(${mbedtls_target}
+            ${MBEDTLS_TARGET_PREFIX}mbedtls_generated_files_target)
+    endif()
 endif(USE_SHARED_MBEDTLS_LIBRARY)
 
 foreach(target IN LISTS target_libraries)

library/Makefile

@@ -380,19 +380,21 @@ version_features.c:
 GENERATED_WRAPPER_FILES = \
                     psa_crypto_driver_wrappers.h \
                     psa_crypto_driver_wrappers_no_static.c
-$(GENERATED_WRAPPER_FILES): ../scripts/generate_driver_wrappers.py
-$(GENERATED_WRAPPER_FILES): ../scripts/data_files/driver_templates/psa_crypto_driver_wrappers.h.jinja
-$(GENERATED_WRAPPER_FILES): ../scripts/data_files/driver_templates/psa_crypto_driver_wrappers_no_static.c.jinja
+$(GENERATED_WRAPPER_FILES): $(gen_file_dep) ../scripts/generate_driver_wrappers.py
+$(GENERATED_WRAPPER_FILES): $(gen_file_dep) ../scripts/data_files/driver_templates/psa_crypto_driver_wrappers.h.jinja
+$(GENERATED_WRAPPER_FILES): $(gen_file_dep) ../scripts/data_files/driver_templates/psa_crypto_driver_wrappers_no_static.c.jinja
 $(GENERATED_WRAPPER_FILES):
 	echo "  Gen   $(GENERATED_WRAPPER_FILES)"
 	$(PYTHON) ../scripts/generate_driver_wrappers.py
 
 psa_crypto.o:psa_crypto_driver_wrappers.h
 
+RM ?= rm
+
 clean:
 ifndef WINDOWS
-	rm -f *.o *.s libmbed*
-	rm -f $(THIRDPARTY_CRYPTO_OBJECTS) $(THIRDPARTY_CRYPTO_OBJECTS:.o=.s)
+	$(RM) -f *.o *.s libmbed*
+	$(RM) -f $(THIRDPARTY_CRYPTO_OBJECTS) $(THIRDPARTY_CRYPTO_OBJECTS:.o=.s)
 else
 	if exist *.o del /Q /F *.o
 	if exist *.s del /Q /F *.s
@@ -402,7 +404,7 @@ endif
 
 neat: clean
 ifndef WINDOWS
-	rm -f $(GENERATED_FILES)
+	$(RM) -f $(GENERATED_FILES)
 else
 	for %f in ($(subst /,\,$(GENERATED_FILES))) if exist %f del /Q /F %f
 endif

library/psa_crypto_core.h

@@ -24,18 +24,6 @@
 #include "mbedtls/threading.h"
 #endif
 
-/**
- * Tell if PSA is ready for this cipher.
- *
- * \note            For now, only checks the state of the driver subsystem,
- *                  not the algorithm. Might do more in the future.
- *
- * \param cipher_alg  The cipher algorithm (ignored for now).
- *
- * \return 1 if the driver subsytem is ready, 0 otherwise.
- */
-int psa_can_do_cipher(psa_key_type_t key_type, psa_algorithm_t cipher_alg);
-
 typedef enum {
     PSA_SLOT_EMPTY = 0,
     PSA_SLOT_FILLING,

library/threading.c

@@ -17,7 +17,7 @@
 
 #if defined(MBEDTLS_THREADING_C)
 
-#include "mbedtls/threading.h"
+#include "threading_internal.h"
 
 #if defined(MBEDTLS_HAVE_TIME_DATE) && !defined(MBEDTLS_PLATFORM_GMTIME_R_ALT)
 

library/threading_internal.h

@@ -0,0 +1,28 @@
+/**
+ * \file threading_internal.h
+ *
+ * \brief Threading interfaces used by the test framework
+ */
+/*
+ *  Copyright The Mbed TLS Contributors
+ *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
+ */
+
+#ifndef MBEDTLS_THREADING_INTERNAL_H
+#define MBEDTLS_THREADING_INTERNAL_H
+
+#include "common.h"
+
+#include <mbedtls/threading.h>
+
+/* A version number for the internal threading interface.
+ * This is meant to allow the framework to remain compatible with
+ * multiple versions, to facilitate transitions.
+ *
+ * Conventionally, this is the Mbed TLS version number when the
+ * threading interface was last changed in a way that may impact the
+ * test framework, with the lower byte incremented as necessary
+ * if multiple changes happened between releases. */
+#define MBEDTLS_THREADING_INTERNAL_VERSION 0x03060000
+
+#endif /* MBEDTLS_THREADING_INTERNAL_H */

tests/scripts/components-build-system.sh

@@ -25,6 +25,66 @@ component_test_cmake_shared () {
     $FRAMEWORK/tests/programs/dlopen_demo.sh
 }
 
+component_build_make_no_gen_files () {
+    msg "prepare for building in a minimal environment"
+
+    # Ensure that the generated files are present (should be a no-op
+    # since the all.sh infrastructure already does it).
+    make generated_files
+
+    # Arrange for the non-generated sources to be more recent than any
+    # generated file. This allows us to detect if the makefile tries
+    # to rebuild the generated files from their dependencies when it
+    # shouldn't.
+    # Wait 1 second so this test is effective even if the filesystem
+    # only has a granularity of 1 second for timestamps.
+    sleep 1
+    git ls-files -z | xargs -0 touch --
+
+    # The setup code of all.sh sets up a "quiet" wrapper for `make`.
+    # We want to bypass it and just use the normal make program,
+    # so that this test mimics a normal user's platform.
+    # And anyway we need to bypass it because it wouldn't work without bash
+    # and other tools in the $PATH.
+    # The wrapper is used because the setup code adds the
+    # `.../framework/scripts/quiet` directlry to the beginning of the $PATH.
+    # So here we remove that.
+    shopt -s extglob
+    # Strip off all entries in $PATH that ends with `/quiet`. (This misses
+    # the very last element, but we know we'll never need to remove the last
+    # element, since we just want to remove the wrapper directory that comes
+    # before the normal programs.)
+    PATH=${PATH//*([!:])\/quiet:/}
+
+    # Locate the minimum programs needed for the build: ${CC} and ${AR}.
+    AR="$(command -v ar)"
+    # GCC needs "as" in $PATH by default. To use GCC, we need to tell it where
+    # to find the assembler. Or we can use clang which just works.
+    CC="$(command -v clang)"
+    # For cleaning.
+    RM="$(command -v rm)"
+
+    # Test the build with make.
+    # Preferably we should also test with CMake. Note that a CMake test
+    # would be harder to set up, because CMake will find e.g. /usr/bin/python
+    # even if it isn't on $PATH.
+    msg "build: make lib with GEN_FILES off in minimal environment"
+    env PATH=/no/such/directory "$(command -v make)" GEN_FILES= AR="$AR" CC="$CC" lib
+
+    msg "build: make -C library clean with GEN_FILES off in minimal environment"
+    env PATH=/no/such/directory "$(command -v make)" GEN_FILES= RM="$RM" -C library clean
+
+    msg "build: make lib with GEN_FILES off with generated files missing"
+    make neat
+    # Check that a sample generated file is absent
+    not test -f library/error.c
+    PERL="$(command -v perl)"
+    PYTHON="$(command -v python3)"
+    # We take whatever Python environment we're in. For a future improvement,
+    # make a venv with just scripts/basic.requirements.txt.
+    env PATH=/no/such/directory "$(command -v make)" GEN_FILES= AR="$AR" CC="$CC" PERL="$PERL" PYTHON="$PYTHON" lib
+}
+
 support_test_cmake_out_of_source () {
     distrib_id=""
     distrib_ver=""

tests/suites/test_suite_platform_threading.data

@@ -0,0 +1,8 @@
+Mutex usage: init, free
+mutex_usage_nominal:0
+
+Mutex usage: lock 1
+mutex_usage_nominal:1
+
+Mutex usage: lock 2
+mutex_usage_nominal:2

tests/suites/test_suite_platform_threading.function

@@ -0,0 +1,32 @@
+/* BEGIN_HEADER */
+/* Basic tests for the threading interface.
+ */
+
+#include "mbedtls/threading.h"
+
+#include "test/threading_helpers.h"
+
+/* END_HEADER */
+
+/* BEGIN_DEPENDENCIES
+ * depends_on:MBEDTLS_THREADING_C
+ * END_DEPENDENCIES
+ */
+
+/* BEGIN_CASE */
+void mutex_usage_nominal(int lock_cycles)
+{
+    mbedtls_threading_mutex_t mutex;
+
+    mbedtls_mutex_init(&mutex);
+
+    for (int i = 0; i < lock_cycles; i++) {
+        mbedtls_test_set_step(i);
+        TEST_EQUAL(mbedtls_mutex_lock(&mutex), 0);
+        TEST_EQUAL(mbedtls_mutex_unlock(&mutex), 0);
+    }
+
+exit:
+    mbedtls_mutex_free(&mutex);
+}
+/* END_CASE */