From 3f48668e5a3c216039832be276315ed09db025c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 29 Jul 2025 09:24:03 +0200 Subject: [PATCH 01/47] Update crypto pointer to development-restricted MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- tf-psa-crypto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tf-psa-crypto b/tf-psa-crypto index 19edaa785d..ae71e1e43f 160000 --- a/tf-psa-crypto +++ b/tf-psa-crypto @@ -1 +1 @@ -Subproject commit 19edaa785dd71ec8f0c9f72235243314c3d895fa +Subproject commit ae71e1e43f0dbb7ff54a6dcdd4ddc89ba4c2b600 From 6569cc63dedbd634506dc8aae97bc02f2426cf5e Mon Sep 17 00:00:00 2001 From: Felix Conway Date: Mon, 11 Aug 2025 09:12:37 +0100 Subject: [PATCH 02/47] Update framework pointer Signed-off-by: Felix Conway --- tf-psa-crypto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tf-psa-crypto b/tf-psa-crypto index ae71e1e43f..52691f95e9 160000 --- a/tf-psa-crypto +++ b/tf-psa-crypto @@ -1 +1 @@ -Subproject commit ae71e1e43f0dbb7ff54a6dcdd4ddc89ba4c2b600 +Subproject commit 52691f95e9235dff461836a2c440e70d44661a7f From 73728d56cf69fb0d0564a9ae1cc5b903dd590f92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 14 Aug 2025 09:30:52 +0200 Subject: [PATCH 03/47] Make test more robust MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This will be needed when we change how many times some functions are callled in ecp.c, making them more susceptible to inlining. Signed-off-by: Manuel Pégourié-Gonnard --- tests/scripts/components-configuration-crypto.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/scripts/components-configuration-crypto.sh b/tests/scripts/components-configuration-crypto.sh index da776e70b8..5a13d5102a 100644 --- a/tests/scripts/components-configuration-crypto.sh +++ b/tests/scripts/components-configuration-crypto.sh @@ -854,7 +854,8 @@ common_test_psa_crypto_config_accel_ecc_some_curves () { ALG_SHA3_224 ALG_SHA3_256 ALG_SHA3_384 ALG_SHA3_512" helper_libtestdriver1_make_drivers "$loc_accel_list" "$loc_extra_list" - helper_libtestdriver1_make_main "$loc_accel_list" + # For grep to work below we need less inlining in ecp.c + ASAN_CFLAGS="$ASAN_CFLAGS -O0" helper_libtestdriver1_make_main "$loc_accel_list" # We expect ECDH to be re-enabled for the missing curves grep mbedtls_ecdh_ ${BUILTIN_SRC_PATH}/ecdh.o From 710869bd340178f3e9ec805310f88a4bb6ff4b69 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 16 Sep 2025 16:24:17 +0200 Subject: [PATCH 04/47] Update framework to the merge of main and main-restricted Signed-off-by: Gilles Peskine --- framework | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework b/framework index d0d817541a..82a7962c5f 160000 --- a/framework +++ b/framework @@ -1 +1 @@ -Subproject commit d0d817541ae3f449b8cd51afc165668179659699 +Subproject commit 82a7962c5f7cbe6e8a60c239cbb477ee06f94182 From 2fe29ab54155b370db0fcb88660c223d9b3b0ce1 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 17 Sep 2025 18:37:54 +0200 Subject: [PATCH 05/47] Update submodules to the merge of the merge PR Signed-off-by: Gilles Peskine --- framework | 2 +- tf-psa-crypto | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/framework b/framework index 82a7962c5f..4f962bfcb3 160000 --- a/framework +++ b/framework @@ -1 +1 @@ -Subproject commit 82a7962c5f7cbe6e8a60c239cbb477ee06f94182 +Subproject commit 4f962bfcb30f565e7c995366b13fc8ec6194a0d2 diff --git a/tf-psa-crypto b/tf-psa-crypto index ed6f6b5b0b..a0cb5a0ffa 160000 --- a/tf-psa-crypto +++ b/tf-psa-crypto @@ -1 +1 @@ -Subproject commit ed6f6b5b0bc72eb789ee62cd7ac87bbf953e0685 +Subproject commit a0cb5a0ffa4cf506f01a797ffce555c5c2e49500 From 28d1d61d72721ae0128184a39b3edf21bf7af8c0 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 30 Sep 2025 10:42:05 +0200 Subject: [PATCH 06/47] Update BRANCHES.md Signed-off-by: Ronald Cron --- BRANCHES.md | 26 +++----------------------- 1 file changed, 3 insertions(+), 23 deletions(-) diff --git a/BRANCHES.md b/BRANCHES.md index 806629721c..5945f95d9c 100644 --- a/BRANCHES.md +++ b/BRANCHES.md @@ -6,9 +6,8 @@ At any point in time, we have a number of maintained branches, currently consist this always contains the latest release, including all publicly available security fixes. - The [`development`](https://github.com/Mbed-TLS/mbedtls/tree/development) branch: - this is where the next major version of Mbed TLS (version 4.0) is being - prepared. It has API changes that make it incompatible with Mbed TLS 3.x, - as well as all the new features and bug fixes and security fixes. + this is where the next minor version of Mbed TLS 4 is prepared. It contains + new features, bug fixes, and security fixes. - One or more long-time support (LTS) branches: these only get bug fixes and security fixes. Currently, the supported LTS branches are: - [`mbedtls-3.6`](https://github.com/Mbed-TLS/mbedtls/tree/mbedtls-3.6). @@ -19,7 +18,7 @@ These branches will not receive any changes or updates. We use [Semantic Versioning](https://semver.org/). In particular, we maintain API compatibility in the `main` branch across minor version changes (e.g. -the API of 3.(x+1) is backward compatible with 3.x). We only break API +the API of 4.(x+1) is backward compatible with 4.x). We only break API compatibility on major version changes (e.g. from 3.x to 4.0). We also maintain ABI compatibility within LTS branches; see the next section for details. @@ -66,25 +65,6 @@ crypto that was found to be weak) may need to be changed. In case security comes in conflict with backwards compatibility, we will put security first, but always attempt to provide a compatibility option. -## Backward compatibility for the key store - -We maintain backward compatibility with previous versions of the -PSA Crypto persistent storage since Mbed TLS 2.25.0, provided that the -storage backend (PSA ITS implementation) is configured in a compatible way. -We intend to maintain this backward compatibility throughout a major version -of Mbed TLS (for example, all Mbed TLS 3.y versions will be able to read -keys written under any Mbed TLS 3.x with x <= y). - -Mbed TLS 3.x can also read keys written by Mbed TLS 2.25.0 through 2.28.x -LTS, but future major version upgrades (for example from 2.28.x/3.x to 4.y) -may require the use of an upgrade tool. - -Note that this guarantee does not currently fully extend to drivers, which -are an experimental feature. We intend to maintain compatibility with the -basic use of drivers from Mbed TLS 2.28.0 onwards, even if driver APIs -change. However, for more experimental parts of the driver interface, such -as the use of driver state, we do not yet guarantee backward compatibility. - ## Long-time support branches For the LTS branches, additionally we try very hard to also maintain ABI From 94f102c06cf8e7b6b13ff882d287940537148c54 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 30 Sep 2025 12:19:29 +0200 Subject: [PATCH 07/47] Update SECURITY.md Signed-off-by: Ronald Cron --- SECURITY.md | 37 ------------------------------------- 1 file changed, 37 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 4682f7aacc..4e7bb14316 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -37,10 +37,6 @@ being implemented. (For example Mbed TLS alone won't guarantee that the messages will arrive without delay, as the TLS protocol doesn't guarantee that either.) -**Warning!** Block ciphers do not yet achieve full protection against attackers -who can measure the timing of packets with sufficient precision. For details -and workarounds see the [Block Ciphers](#block-ciphers) section. - ### Local attacks In this section, we consider an attacker who can run software on the same @@ -69,9 +65,6 @@ physical side channels as well. Remote and physical timing attacks are covered in the [Remote attacks](remote-attacks) and [Physical attacks](physical-attacks) sections respectively. -**Warning!** Block ciphers do not yet achieve full protection. For -details and workarounds see the [Block Ciphers](#block-ciphers) section. - #### Local non-timing side channels The attacker code running on the platform has access to some sensor capable of @@ -115,36 +108,6 @@ protection against a class of attacks outside of the above described threat model. Neither does it mean that the failure of such a countermeasure is considered a vulnerability. -#### Block ciphers - -Currently there are four block ciphers in Mbed TLS: AES, CAMELLIA, ARIA and -DES. The pure software implementation in Mbed TLS implementation uses lookup -tables, which are vulnerable to timing attacks. - -These timing attacks can be physical, local or depending on network latency -even a remote. The attacks can result in key recovery. - -**Workarounds:** - -- Turn on hardware acceleration for AES. This is supported only on selected - architectures and currently only available for AES. See configuration options - `MBEDTLS_AESCE_C`, `MBEDTLS_AESNI_C` for details. -- Add a secure alternative implementation (typically hardware acceleration) for - the vulnerable cipher. See the [Alternative Implementations -Guide](docs/architecture/alternative-implementations.md) for more information. -- Use cryptographic mechanisms that are not based on block ciphers. In - particular, for authenticated encryption, use ChaCha20/Poly1305 instead of - block cipher modes. For random generation, use HMAC\_DRBG instead of CTR\_DRBG. - -#### Everest - -The HACL* implementation of X25519 taken from the Everest project only protects -against remote timing attacks. (See their [Security -Policy](https://github.com/hacl-star/hacl-star/blob/main/SECURITY.md).) - -The Everest variant is only used when `MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED` -configuration option is defined. This option is off by default. - #### Formatting of X.509 certificates and certificate signing requests When parsing X.509 certificates and certificate signing requests (CSRs), From d196cbd3e529faffe10bee2f0a8e74aac9da24df Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 30 Sep 2025 09:58:08 +0200 Subject: [PATCH 08/47] README.md: The crypto code is provided by TF-PSA-Crypto Signed-off-by: Ronald Cron --- README.md | 46 +++------------------------------------------- 1 file changed, 3 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 7326a3ebe5..449926c738 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,8 @@ README for Mbed TLS =================== -Mbed TLS is a C library that implements cryptographic primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems. - -Mbed TLS includes a reference implementation of the [PSA Cryptography API](#psa-cryptography-api). This is currently a preview for evaluation purposes only. +Mbed TLS is a C library that implements X.509 certificate manipulation and the TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems. +Mbed TLS includes the [TF-PSA-Crypto repository](https://github.com/Mbed-TLS/TF-PSA-Crypto) that provides an implementation of the [PSA Cryptography API](https://arm-software.github.io/psa-api). Configuration ------------- @@ -19,8 +18,6 @@ Documentation The main Mbed TLS documentation is available via [ReadTheDocs](https://mbed-tls.readthedocs.io/). -Documentation for the PSA Cryptography API is available [on GitHub](https://arm-software.github.io/psa-api/crypto/). - To generate a local copy of the library documentation in HTML format, tailored to your compile-time configuration: 1. Make sure that [Doxygen](http://www.doxygen.nl/) is installed. @@ -43,7 +40,7 @@ You need the following tools to build the library: * CMake 3.10.2 or later. * A build system that CMake supports. * A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, Arm Compiler 6, IAR 8 and Visual Studio 2017. More recent versions should work. Slightly older versions may work. -* Python 3.8 to generate the test code. Python is also needed to integrate PSA drivers and to build the development branch (see next section). +* Python 3.8 to generate the test code. Python is also needed to build the development branch (see next section). * Perl to run the tests, and to generate some source files in the development branch. * Doxygen 1.8.11 or later (if building the documentation; slightly older versions should work). @@ -236,48 +233,11 @@ Mbed TLS is mostly written in portable C99; however, it has a few platform requi - Mixed-endian platforms are not supported. - SIZE_MAX must be at least as big as INT_MAX and UINT_MAX. -PSA cryptography API --------------------- - -### PSA API - -Arm's [Platform Security Architecture (PSA)](https://developer.arm.com/architectures/security-architectures/platform-security-architecture) is a holistic set of threat models, security analyses, hardware and firmware architecture specifications, and an open source firmware reference implementation. PSA provides a recipe, based on industry best practice, that allows security to be consistently designed in, at both a hardware and firmware level. - -The [PSA cryptography API](https://arm-software.github.io/psa-api/crypto/) provides access to a set of cryptographic primitives. It has a dual purpose. First, it can be used in a PSA-compliant platform to build services, such as secure boot, secure storage and secure communication. Second, it can also be used independently of other PSA components on any platform. - -The design goals of the PSA cryptography API include: - -* The API distinguishes caller memory from internal memory, which allows the library to be implemented in an isolated space for additional security. Library calls can be implemented as direct function calls if isolation is not desired, and as remote procedure calls if isolation is desired. -* The structure of internal data is hidden to the application, which allows substituting alternative implementations at build time or run time, for example, in order to take advantage of hardware accelerators. -* All access to the keys happens through key identifiers, which allows support for external cryptoprocessors that is transparent to applications. -* The interface to algorithms is generic, favoring algorithm agility. -* The interface is designed to be easy to use and hard to accidentally misuse. - -Arm welcomes feedback on the design of the API. If you think something could be improved, please open an issue on our Github repository. Alternatively, if you prefer to provide your feedback privately, please email us at [`mbed-crypto@arm.com`](mailto:mbed-crypto@arm.com). All feedback received by email is treated confidentially. - -### PSA implementation in Mbed TLS - -Mbed TLS includes a reference implementation of the PSA Cryptography API. -However, it does not aim to implement the whole specification; in particular it does not implement all the algorithms. - -### PSA drivers - -Mbed TLS supports drivers for cryptographic accelerators, secure elements and random generators. This is work in progress. Please note that the driver interfaces are not fully stable yet and may change without notice. We intend to preserve backward compatibility for application code (using the PSA Crypto API), but the code of the drivers may have to change in future minor releases of Mbed TLS. - -Please see the [PSA driver example and guide](https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/psa-driver-example-and-guide.md) for information on writing a driver. - License ------- Unless specifically indicated otherwise in a file, Mbed TLS files are provided under a dual [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) OR [GPL-2.0-or-later](https://spdx.org/licenses/GPL-2.0-or-later.html) license. See the [LICENSE](LICENSE) file for the full text of these licenses, and [the 'License and Copyright' section in the contributing guidelines](CONTRIBUTING.md#License-and-Copyright) for more information. -### Third-party code included in Mbed TLS - -This project contains code from other projects. This code is located within the `tf-psa-crypto/drivers/` directory. The original license text is included within project subdirectories, where it differs from the normal Mbed TLS license, and/or in source files. The projects are listed below: - -* `drivers/everest/`: Files stem from [Project Everest](https://project-everest.github.io/) and are distributed under the Apache 2.0 license. -* `drivers/p256-m/p256-m/`: Files have been taken from the [p256-m](https://github.com/mpg/p256-m) repository. The code in the original repository is distributed under the Apache 2.0 license. It is distributed in Mbed TLS under a dual Apache-2.0 OR GPL-2.0-or-later license with permission from the author. - Contributing ------------ From eef87b348f2e84e7d62734376781245192a738a6 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 30 Sep 2025 13:06:32 +0200 Subject: [PATCH 09/47] README.md: Microsoft Visual Studio is not directly supported anymore Signed-off-by: Ronald Cron --- README.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/README.md b/README.md index 449926c738..0e35fe9aa8 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ The source code of Mbed TLS includes some files that are automatically generated The following tools are required: -* Perl, for some library source files and for Visual Studio build files. +* Perl, for some library source files. * Python 3.8 and some Python packages, for some library source files, sample programs and test data. To install the necessary packages, run: ``` python3 -m pip install --user -r scripts/basic.requirements.txt @@ -185,14 +185,6 @@ Mbed TLS supports being built as a CMake subproject. One can use `add_subdirectory()` from a parent CMake project to include Mbed TLS as a subproject. -### Microsoft Visual Studio - -The build files for Microsoft Visual Studio are generated for Visual Studio 2017. - -The solution file `mbedTLS.sln` contains all the basic projects needed to build the library and all the programs. The files in tests are not generated and compiled, as these need Python and perl environments as well. However, the selftest program in `programs/test/` is still available. - -In the development branch of Mbed TLS, the Visual Studio solution files need to be generated first as described in [“Generated source files in the development branch”](#generated-source-files-in-the-development-branch). - Example programs ---------------- From 0f2ef4a896dff5f2d53affbc3b083032e8326cac Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 30 Sep 2025 18:30:32 +0200 Subject: [PATCH 10/47] README.md: Update Configuration section Signed-off-by: Ronald Cron --- README.md | 7 ++++--- configs/README.txt | 34 ++++++++++++++++++---------------- 2 files changed, 22 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 0e35fe9aa8..171323c7d0 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,13 @@ Mbed TLS includes the [TF-PSA-Crypto repository](https://github.com/Mbed-TLS/TF- Configuration ------------- +Configuration options related to X.509 and TLS are available in `include/mbedtls/mbedtls_config.h`, while cryptography and platform options are located in the TF-PSA-Crypto configuration file `tf-psa-crypto/include/psa/crypto_config.h`. -Mbed TLS should build out of the box on most systems. Some platform specific options are available in the fully documented configuration file `include/mbedtls/mbedtls_config.h`, which is also the place where features can be selected. This file can be edited manually, or in a more programmatic way using the Python 3 script `scripts/config.py` (use `--help` for usage instructions). +With the default platform options, Mbed TLS should build out of the box on most systems. -Compiler options can be set using conventional environment variables such as `CC` and `CFLAGS`. +These configuration files can be edited manually, or programmatically using the Python 3 script scripts/config.py (run with --help for usage instructions). -We provide some non-standard configurations focused on specific use cases in the `configs/` directory. You can read more about those in `configs/README.txt` +We provide some non-standard configurations focused on specific use cases in the `configs/` directory. You can read more about those in `configs/README.txt`. Documentation ------------- diff --git a/configs/README.txt b/configs/README.txt index 86496db013..9e471344ef 100644 --- a/configs/README.txt +++ b/configs/README.txt @@ -1,24 +1,26 @@ This directory contains example configuration files. -The examples are generally focused on a particular usage case (eg, support for -a restricted number of ciphersuites) and aim at minimizing resource usage for -this target. They can be used as a basis for custom configurations. +The examples are generally focused on a particular use case (eg, support for +a restricted set of ciphersuites) and aim to minimize resource usage for +the target. They can be used as a basis for custom configurations. -These files are complete replacements for the default mbedtls_config.h. To use one of -them, you can pick one of the following methods: +These files come in pairs and are complete replacements for the default +mbedtls_config.h and crypto_config.h. The two files of a pair share the same or +very similar name, with the crypto file prefixed by "crypto-". Note +that some of the cryptography configuration files may be located in +tf-psa-crypto/configs. -1. Replace the default file include/mbedtls/mbedtls_config.h with the chosen one. +To use one of these pairs, you can pick one of the following methods: -2. Define MBEDTLS_CONFIG_FILE and adjust the include path accordingly. - For example, using make: +1. Replace the default files include/mbedtls/mbedtls_config.h and + tf-psa-crypto/include/psa/crypto_config.h with the chosen ones. - CFLAGS="-I$PWD/configs -DMBEDTLS_CONFIG_FILE=''" make +2. Use the MBEDTLS_CONFIG_FILE and TF_PSA_CRYPTO_CONFIG_FILE options of the + CMake build system: - Or, using cmake: + cmake -DMBEDTLS_CONFIG_FILE="path-to-your-mbedtls-config-file" \ + -DTF_PSA_CRYPTO_CONFIG_FILE="path-to-your-tf-psa-crypto-config-file" . + make - find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} + - CFLAGS="-I$PWD/configs -DMBEDTLS_CONFIG_FILE=''" cmake . - make - -Note that the second method also works if you want to keep your custom -configuration file outside the Mbed TLS tree. +The second method also works if you want to keep your custom configuration +files outside the Mbed TLS tree. From 200b89bb87849192b96d1c4d3e631489c83eb370 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 1 Oct 2025 10:05:34 +0200 Subject: [PATCH 11/47] README.md: Update/Fix documentation section Signed-off-by: Ronald Cron --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 171323c7d0..1e07fd8018 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,8 @@ The main Mbed TLS documentation is available via [ReadTheDocs](https://mbed-tls. To generate a local copy of the library documentation in HTML format, tailored to your compile-time configuration: 1. Make sure that [Doxygen](http://www.doxygen.nl/) is installed. -1. Run `mkdir /path/to/build_dir && cd /path/to/build_dir` -1. Run `cmake /path/to/mbedtls/source` -1. Run `make apidoc` +1. Run `cmake -B /path/to/build_dir /path/to/mbedtls/source` +1. Run `cmake --build /path/to/build_dir --target mbedtls-apidoc` 1. Browse `apidoc/index.html` or `apidoc/modules.html`. For other sources of documentation, see the [SUPPORT](SUPPORT.md) document. From 7cf78b4c2cacddf77f76e5e612e22ee24be7c94f Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 1 Oct 2025 10:28:17 +0200 Subject: [PATCH 12/47] README.md: Update build sections Signed-off-by: Ronald Cron --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1e07fd8018..9ba6ae36ac 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ For other sources of documentation, see the [SUPPORT](SUPPORT.md) document. Compiling --------- -We use CMake to configure and drive our build process. Three libraries are built: libtfpsacrypto, libmbedx509, and libmbedtls. Note that libmbedtls depends on libmbedx509 and libtfpsacrypto, and libmbedx509 depends on libtfpsacrypto. As a result, some linkers will expect flags to be in a specific order, for example the GNU linker wants `-lmbedtls -lmbedx509 -ltfpsacrypto`. +We use CMake to configure and drive our build process. Three libraries are built: `libtfpsacrypto`, `libmbedx509`, and `libmbedtls`. Note that `libmbedtls` depends on `libmbedx509` and `libtfpsacrypto`, and `libmbedx509` depends on `libtfpsacrypto`. As a result, some linkers will expect flags to be in a specific order, for example the GNU linker wants `-lmbedtls -lmbedx509 -ltfpsacrypto`. The cryptographic library `libtfpsacrypto` is also provided under its legacy name, `libmbedcrypto`. ### Tool versions @@ -106,9 +106,11 @@ There are many different build types available with CMake. Most of them are avai - `Coverage`. This generates code coverage information in addition to debug information. - `ASan`. This instruments the code with AddressSanitizer to check for memory errors. (This includes LeakSanitizer, with recent version of gcc and clang.) (With recent version of clang, this mode also instruments the code with UndefinedSanitizer to check for undefined behaviour.) - `ASanDbg`. Same as ASan but slower, with debug information and better stack traces. -- `MemSan`. This instruments the code with MemorySanitizer to check for uninitialised memory reads. Experimental, needs recent clang on Linux/x86\_64. +- `MemSan`. This instruments the code with MemorySanitizer to check for uninitialised memory reads. - `MemSanDbg`. Same as MemSan but slower, with debug information, better stack traces and origin tracking. - `Check`. This activates the compiler warnings that depend on optimization and treats all warnings as errors. +- `TSan`. This instruments the code with ThreadSanitizer to detect data races and other threading-related concurrency issues at runtime. +- `TSanDbg`. Same as TSan but slower, with debug information, better stack traces and origin tracking. Switching build types in CMake is simple. For debug mode, enter at the command line: From 4ccdaf1cd5d3c5426b6d58b921edfbd000a0a5cc Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 1 Oct 2025 12:40:27 +0200 Subject: [PATCH 13/47] README.md: Update minimum version of tools Signed-off-by: Ronald Cron --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9ba6ae36ac..ddf2dbf6bc 100644 --- a/README.md +++ b/README.md @@ -35,14 +35,14 @@ We use CMake to configure and drive our build process. Three libraries are built ### Tool versions -You need the following tools to build the library: +You need the following tools to build the library from the main branch with the provided CMake files. Mbed TLS minimum tool version requirements are set based on the versions shipped in the latest or penultimate (depending on the release cadence) long-term support releases of major Linux distributions, namely at time of writing: Ubuntu 22.04, RHEL 9, and SLES 15 SP4. -* CMake 3.10.2 or later. +* CMake 3.20.4 or later. * A build system that CMake supports. * A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, Arm Compiler 6, IAR 8 and Visual Studio 2017. More recent versions should work. Slightly older versions may work. * Python 3.8 to generate the test code. Python is also needed to build the development branch (see next section). * Perl to run the tests, and to generate some source files in the development branch. -* Doxygen 1.8.11 or later (if building the documentation; slightly older versions should work). +* Doxygen 1.8.14 or later (if building the documentation; slightly older versions should work). ### Git usage @@ -55,7 +55,7 @@ The source code of Mbed TLS includes some files that are automatically generated The following tools are required: * Perl, for some library source files. -* Python 3.8 and some Python packages, for some library source files, sample programs and test data. To install the necessary packages, run: +* Python 3 and some Python packages, for some library source files, sample programs and test data. To install the necessary packages, run: ``` python3 -m pip install --user -r scripts/basic.requirements.txt ``` From e2d4684ec401e27e5679c139846c641c2322e236 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 1 Oct 2025 13:04:49 +0200 Subject: [PATCH 14/47] README.md: Update tests section Signed-off-by: Ronald Cron --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index ddf2dbf6bc..1c6bc42885 100644 --- a/README.md +++ b/README.md @@ -202,7 +202,6 @@ For machines with a Unix shell and OpenSSL (and optionally GnuTLS) installed, ad - `tests/ssl-opt.sh` runs integration tests for various TLS options (renegotiation, resumption, etc.) and tests interoperability of these options with other implementations. - `tests/compat.sh` tests interoperability of every ciphersuite with other implementations. -- `tests/scripts/test-ref-configs.pl` test builds in various reduced configurations. - `tests/scripts/depends.py` test builds in configurations with a single curve, key exchange, hash, cipher, or pkalg on. - `tests/scripts/all.sh` runs a combination of the above tests, plus some more, with various build options (such as ASan, full `mbedtls_config.h`, etc). From c9d79ff0d493d5c33b68d641da0ecf3460d34566 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 2 Oct 2025 19:14:14 +0200 Subject: [PATCH 15/47] README.md: Various small improvements Signed-off-by: Ronald Cron --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 1c6bc42885..d745b24bef 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Configuration options related to X.509 and TLS are available in `include/mbedtls With the default platform options, Mbed TLS should build out of the box on most systems. -These configuration files can be edited manually, or programmatically using the Python 3 script scripts/config.py (run with --help for usage instructions). +These configuration files can be edited manually, or programmatically using the Python 3 script `scripts/config.py` (run with --help for usage instructions). We provide some non-standard configurations focused on specific use cases in the `configs/` directory. You can read more about those in `configs/README.txt`. @@ -38,7 +38,7 @@ We use CMake to configure and drive our build process. Three libraries are built You need the following tools to build the library from the main branch with the provided CMake files. Mbed TLS minimum tool version requirements are set based on the versions shipped in the latest or penultimate (depending on the release cadence) long-term support releases of major Linux distributions, namely at time of writing: Ubuntu 22.04, RHEL 9, and SLES 15 SP4. * CMake 3.20.4 or later. -* A build system that CMake supports. +* A build system like Make or Ninja for which CMake can generate build files. * A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, Arm Compiler 6, IAR 8 and Visual Studio 2017. More recent versions should work. Slightly older versions may work. * Python 3.8 to generate the test code. Python is also needed to build the development branch (see next section). * Perl to run the tests, and to generate some source files in the development branch. @@ -138,7 +138,7 @@ showing them as modified). In order to do so, from the Mbed TLS source directory, use: cmake . - make + cmake --build . If you want to change `CC` or `CFLAGS` afterwards, you will need to remove the CMake cache. This can be done with the following command using GNU find: @@ -148,10 +148,10 @@ CMake cache. This can be done with the following command using GNU find: You can now make the desired change: CC=your_cc cmake . - make + cmake --build . Regarding variables, also note that if you set CFLAGS when invoking cmake, -your value of CFLAGS doesn't override the content provided by cmake (depending +your value of CFLAGS doesn't override the content provided by CMake (depending on the build mode as seen above), it's merely prepended to it. #### Consuming Mbed TLS @@ -196,13 +196,13 @@ Please note that the goal of these sample programs is to demonstrate specific fe Tests ----- -Mbed TLS includes an elaborate test suite in `tests/` that initially requires Python to generate the tests files (e.g. `test\_suite\_ssl.c`). These files are generated from a `function file` (e.g. `suites/test\_suite\_ssl.function`) and a `data file` (e.g. `suites/test\_suite\_ssl.data`). The `function file` contains the test functions. The `data file` contains the test cases, specified as parameters that will be passed to the test function. +Mbed TLS includes an elaborate test suite in `tests/` that initially requires Python to generate the tests files (e.g. `test_suite_ssl.c`). These files are generated from a `function file` (e.g. `suites/test_suite_ssl.function`) and a `data file` (e.g. `suites/test_suite_ssl.data`). The `function file` contains the test functions. The `data file` contains the test cases, specified as parameters that will be passed to the test function. For machines with a Unix shell and OpenSSL (and optionally GnuTLS) installed, additional test scripts are available: - `tests/ssl-opt.sh` runs integration tests for various TLS options (renegotiation, resumption, etc.) and tests interoperability of these options with other implementations. - `tests/compat.sh` tests interoperability of every ciphersuite with other implementations. -- `tests/scripts/depends.py` test builds in configurations with a single curve, key exchange, hash, cipher, or pkalg on. +- `tests/scripts/depends.py` tests builds in configurations with a single curve, key exchange, hash, cipher, or pkalg on. - `tests/scripts/all.sh` runs a combination of the above tests, plus some more, with various build options (such as ASan, full `mbedtls_config.h`, etc). Instead of manually installing the required versions of all tools required for testing, it is possible to use the Docker images from our CI systems, as explained in [our testing infrastructure repository](https://github.com/Mbed-TLS/mbedtls-test/blob/main/README.md#quick-start). From c9998d399b7f8814994721e516107a5733d97741 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Fri, 3 Oct 2025 10:03:20 +0200 Subject: [PATCH 16/47] README.md: Fix/Update the "Git usage" section Signed-off-by: Ronald Cron --- README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d745b24bef..33ad4ac23d 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,15 @@ You need the following tools to build the library from the main branch with the ### Git usage -The `development` branch and the `mbedtls-3.6` long-term support branch of Mbed TLS use a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules#_cloning_submodules) ([framework](https://github.com/Mbed-TLS/mbedtls-framework)). This is not needed to merely compile the library at a release tag. This is not needed to consume a release archive (zip or tar). +The supported branches (see [`BRANCHES.md`](BRANCHES.md)) use [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules#_cloning_submodules). They contain two submodules: the [framework](https://github.com/Mbed-TLS/mbedtls-framework) submodule and the [tf-psa-crypto](https://github.com/Mbed-TLS/TF-PSA-Crypto) submodule, except for the 3.6 LTS branch, which contains only the framework submodule. Release tags also use Git submodules. + +After cloning or checking out a branch or tag, run: + ``` + git submodule update --init --recursive + ``` + to initialize and update the submodules before building. + +However, the official source release tarballs (e.g. [mbedtls-4.0.0-beta.tar.bz2](https://github.com/Mbed-TLS/mbedtls/releases/download/mbedtls-4.0.0-beta/mbedtls-4.0.0-beta.tar.bz2)) include the contents of the submodules. ### Generated source files in the development branch From 74a4984eacfd40e2d026359b0dcb29ed38b1b486 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Fri, 3 Oct 2025 11:13:44 +0200 Subject: [PATCH 17/47] README.md: Fix/Improve CMake section Signed-off-by: Ronald Cron --- README.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 33ad4ac23d..40e9e579c3 100644 --- a/README.md +++ b/README.md @@ -95,14 +95,10 @@ In order to run the tests, enter: ctest -The test suites need Python to be built and Perl to be executed. If you don't have one of these installed, you'll want to disable the test suites with: +The test suites need Python to be built. If you don't have Python installed, you'll want to disable the test suites with: cmake -DENABLE_TESTING=Off /path/to/mbedtls_source -If you disabled the test suites, but kept the programs enabled, you can still run a much smaller set of tests with: - - programs/test/selftest - To configure CMake for building shared libraries, use: cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source @@ -137,7 +133,7 @@ for example: CC=your_cc cmake /path/to/mbedtls_source If you already invoked cmake and want to change those settings, you need to -remove the build directory and create it again. +invoke the configuration phase of CMake again with the new settings. Note that it is possible to build in-place; this will however overwrite the legacy Makefiles still used for testing purposes (see @@ -164,17 +160,23 @@ on the build mode as seen above), it's merely prepended to it. #### Consuming Mbed TLS -Mbed TLS provides a package config file for consumption as a dependency in other -CMake projects. You can include Mbed TLS's CMake targets yourself with: +Mbed TLS provides a CMake package configuration file for consumption as a +dependency in other CMake projects. You can load its CMake targets with: - find_package(MbedTLS) + find_package(MbedTLS REQUIRED) -If prompted, set `MbedTLS_DIR` to `${YOUR_MBEDTLS_INSTALL_DIR}/cmake`. This -creates the following targets: +You can help CMake find the package: -- `MbedTLS::tfpsacrypto` (Crypto library) -- `MbedTLS::mbedtls` (TLS library) -- `MbedTLS::mbedx509` (X509 library) +- By setting the variable `MbedTLS_DIR` to `${YOUR_MBEDTLS_BUILD_DIR}/cmake`, + as shown in `programs/test/cmake_package/CMakeLists.txt`, or +- By adding the Mbed TLS installation prefix to `CMAKE_PREFIX_PATH`, + as shown in `programs/test/cmake_package_install/CMakeLists.txt`. + +After a successful `find_package(MbedTLS)`, the following imported targets are available: + +- `MbedTLS::tfpsacrypto`, the crypto library +- `MbedTLS::mbedtls`, the TLS library +- `MbedTLS::mbedx509`, the X.509 library You can then use these directly through `target_link_libraries()`: From e943bd73ac83dc5ac472d42203d5f7df8aacac9a Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Sun, 5 Oct 2025 16:46:20 +0200 Subject: [PATCH 18/47] configs/README.txt: Improve example with MBEDTLS/TF_PSA_CRYPTO_CONFIG_FILE Signed-off-by: Ronald Cron --- configs/README.txt | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/configs/README.txt b/configs/README.txt index 9e471344ef..38348dda0e 100644 --- a/configs/README.txt +++ b/configs/README.txt @@ -15,12 +15,14 @@ To use one of these pairs, you can pick one of the following methods: 1. Replace the default files include/mbedtls/mbedtls_config.h and tf-psa-crypto/include/psa/crypto_config.h with the chosen ones. -2. Use the MBEDTLS_CONFIG_FILE and TF_PSA_CRYPTO_CONFIG_FILE options of the - CMake build system: +2. Use the MBEDTLS_CONFIG_FILE and TF_PSA_CRYPTO_CONFIG_FILE CMake options. For + example, to build out-of-tree with the config-ccm-psk-tls1_2.h and + crypto-config-ccm-psk-tls1_2.h configuration pair: - cmake -DMBEDTLS_CONFIG_FILE="path-to-your-mbedtls-config-file" \ - -DTF_PSA_CRYPTO_CONFIG_FILE="path-to-your-tf-psa-crypto-config-file" . - make + cmake -DMBEDTLS_CONFIG_FILE="configs/config-ccm-psk-tls1_2.h" \ + -DTF_PSA_CRYPTO_CONFIG_FILE="configs/crypto-config-ccm-psk-tls1_2.h" + -B build-psktls12 . + cmake --build build-psktls12 The second method also works if you want to keep your custom configuration files outside the Mbed TLS tree. From 8267196b8bb77df0da538ec32ae657fdd9164924 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Sun, 5 Oct 2025 16:58:41 +0200 Subject: [PATCH 19/47] README.md: Add mention to topics.html for Doxygen documentation Signed-off-by: Ronald Cron --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 40e9e579c3..3f905c1322 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,9 @@ To generate a local copy of the library documentation in HTML format, tailored t 1. Make sure that [Doxygen](http://www.doxygen.nl/) is installed. 1. Run `cmake -B /path/to/build_dir /path/to/mbedtls/source` 1. Run `cmake --build /path/to/build_dir --target mbedtls-apidoc` -1. Browse `apidoc/index.html` or `apidoc/modules.html`. +1. Open one of the main generated HTML files: + * `apidoc/index.html` + * `apidoc/modules.html` or `apidoc/topics.html` For other sources of documentation, see the [SUPPORT](SUPPORT.md) document. From b906301e10b7e4df40077526658aa808d2a8c19a Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Sun, 5 Oct 2025 16:47:45 +0200 Subject: [PATCH 20/47] Various minor improvements Signed-off-by: Ronald Cron --- BRANCHES.md | 2 +- README.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/BRANCHES.md b/BRANCHES.md index 5945f95d9c..c781704977 100644 --- a/BRANCHES.md +++ b/BRANCHES.md @@ -6,7 +6,7 @@ At any point in time, we have a number of maintained branches, currently consist this always contains the latest release, including all publicly available security fixes. - The [`development`](https://github.com/Mbed-TLS/mbedtls/tree/development) branch: - this is where the next minor version of Mbed TLS 4 is prepared. It contains + this is where the next minor version of Mbed TLS 4.x is prepared. It contains new features, bug fixes, and security fixes. - One or more long-time support (LTS) branches: these only get bug fixes and security fixes. Currently, the supported LTS branches are: diff --git a/README.md b/README.md index 3f905c1322..4b1188e3b3 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Configuration options related to X.509 and TLS are available in `include/mbedtls With the default platform options, Mbed TLS should build out of the box on most systems. -These configuration files can be edited manually, or programmatically using the Python 3 script `scripts/config.py` (run with --help for usage instructions). +These configuration files can be edited manually, or programmatically using the Python script `scripts/config.py` (run with --help for usage instructions). We provide some non-standard configurations focused on specific use cases in the `configs/` directory. You can read more about those in `configs/README.txt`. @@ -41,8 +41,8 @@ You need the following tools to build the library from the main branch with the * CMake 3.20.4 or later. * A build system like Make or Ninja for which CMake can generate build files. -* A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, Arm Compiler 6, IAR 8 and Visual Studio 2017. More recent versions should work. Slightly older versions may work. -* Python 3.8 to generate the test code. Python is also needed to build the development branch (see next section). +* A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, Arm Compiler 6, IAR 8, and Visual Studio 2017 Compiler. More recent versions should work. Slightly older versions may work. +* Python 3.8 or later to generate the test code. Python is also needed to build the development branch (see next section). * Perl to run the tests, and to generate some source files in the development branch. * Doxygen 1.8.14 or later (if building the documentation; slightly older versions should work). @@ -69,7 +69,7 @@ The following tools are required: ``` python3 -m pip install --user -r scripts/basic.requirements.txt ``` - Depending on your Python installation, you may need to invoke `python` instead of `python3`. To install the packages system-wide, omit the `--user` option. + Depending on your Python installation, you may need to invoke `python` instead of `python3`. To install the packages system-wide or in a virtual environment, omit the `--user` option. * A C compiler for the host platform, for some test data. The scripts that generate the configuration-independent files will look for a host C compiler in the following places (in order of preference): From 864c31a1f8042b858d0e427548fbe83dbe57959e Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Sun, 5 Oct 2025 17:28:11 +0200 Subject: [PATCH 21/47] README.md: IAR not currently used in our testing Signed-off-by: Ronald Cron --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4b1188e3b3..0638cd8385 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ You need the following tools to build the library from the main branch with the * CMake 3.20.4 or later. * A build system like Make or Ninja for which CMake can generate build files. -* A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, Arm Compiler 6, IAR 8, and Visual Studio 2017 Compiler. More recent versions should work. Slightly older versions may work. +* A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, Arm Compiler 6, and Visual Studio 2017 Compiler. More recent versions should work. Slightly older versions may work. * Python 3.8 or later to generate the test code. Python is also needed to build the development branch (see next section). * Perl to run the tests, and to generate some source files in the development branch. * Doxygen 1.8.14 or later (if building the documentation; slightly older versions should work). From 63180eb1323834d43d32880a171bfb1c9d6efd78 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Sun, 5 Oct 2025 17:41:01 +0200 Subject: [PATCH 22/47] README.md: Adjust CMake minimum version Adjust CMake minimum version to 3.20.2. That is the version in CentOS which is the rolling-delivery upstream of RHEL 9. Signed-off-by: Ronald Cron --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0638cd8385..69f2dcb26e 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ We use CMake to configure and drive our build process. Three libraries are built You need the following tools to build the library from the main branch with the provided CMake files. Mbed TLS minimum tool version requirements are set based on the versions shipped in the latest or penultimate (depending on the release cadence) long-term support releases of major Linux distributions, namely at time of writing: Ubuntu 22.04, RHEL 9, and SLES 15 SP4. -* CMake 3.20.4 or later. +* CMake 3.20.2 or later. * A build system like Make or Ninja for which CMake can generate build files. * A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, Arm Compiler 6, and Visual Studio 2017 Compiler. More recent versions should work. Slightly older versions may work. * Python 3.8 or later to generate the test code. Python is also needed to build the development branch (see next section). From 9228e4a794076dc92e8ce212bd5f40a0db65de99 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Sun, 5 Oct 2025 16:25:43 +0200 Subject: [PATCH 23/47] Add repo-split migration guide Also a section about the CMake being now the only build system. Signed-off-by: Ronald Cron --- docs/4.0-migration-guide/repo-split.md | 101 +++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 docs/4.0-migration-guide/repo-split.md diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md new file mode 100644 index 0000000000..4e8da82e3d --- /dev/null +++ b/docs/4.0-migration-guide/repo-split.md @@ -0,0 +1,101 @@ +## CMake as the only build system +CMake is now the only supported build system for Mbed TLS. +Support for the legacy GNU Make and Microsoft Visual Studio project-based build systems has been removed. + +The GNU Make build system is still used internally for testing, but it will be removed once all test components have been migrated to CMake. +The previous .sln/.vcxproj files are no longer distributed or generated. + +Builds must now be configured and executed through CMake. See `Compiling` section in README.md for initial build instructions. +If you develop in Microsoft Visual Studio, you could either generate a Visual Studio solution using a CMake generator, or open the CMake project directly in Visual Studio. + +## Repository split +In Mbed TLS 4.0, the project was split into two repositories: +- [Mbed TLS](https://github.com/Mbed-TLS/mbedtls): provides TLS and X.509 functionality. +- [TF-PSA-Crypto](https://github.com/Mbed-TLS/TF-PSA-Crypto): provides the standalone cryptography library, implementing the PSA Cryptography API. +Mbed TLS consumes TF-PSA-Crypto as a submodule. +You should stay with Mbed TLS if you use TLS or X.509 functionality. You still have direct access to the PSA Cryptography API through the `tf-psa-crypto` submodule. + +### File and directory relocations + +The following table summarizes the file and directory relocations resulting from the repository split between Mbed TLS and TF-PSA-Crypto. +These changes reflect the move of cryptographic, cryptographic-adjacent, and platform components from Mbed TLS into the new TF-PSA-Crypto repository. + +| Original location | New location(s) | Notes | +|--------------------------------------|--------------------------------------------------------------------------------------|-------| +| `library/` | `tf-psa-crypto/core/`
`tf-psa-crypto/drivers/builtin/src/` | Contains cryptographic, cryptographic-adjacent (e.g., ASN.1, Base64), and platform C modules and headers. | +| `include/mbedtls/` | `tf-psa-crypto/include/mbedtls/`
`tf-psa-crypto/drivers/builtin/include/private/` | Public headers moved to `include/mbedtls`; now internal headers moved to `include/private`. | +| `include/psa/` | `tf-psa-crypto/include/` | All PSA headers consolidated here. | +| `3rdparty/everest/`
`3rdparty/p256-m/` | `tf-psa-crypto/drivers/` | Third-party crypto driver implementations. | + +If you use your own build system to build Mbed TLS libraries, you will need to adapt to the new tree. + +### Configuration file split +Cryptography and platform configuration options have been moved from `mbedtls_config.h` to `crypto_config.h`, which is now mandatory. See [Compile-time configuration](#compile-time-confiuration). + +### Impact on some usages of the library + +#### Checking out a branch or a tag +After checking out a branch or tag of the Mbed TLS repository, you must now recursively update the submodules, as TF-PSA-Crypto contains itself a nested submodule: +``` +git submodule update --init --recursive +``` + +#### Linking directly to a built library +The Mbed TLS CMake build system still provides the cryptography libraries under their legacy name, `libmbedcrypto.`, so you can continue linking against them. +The cryptography libraries are also now provided as `libtfpsacrypto.` like in the TF-PSA-Crypto repository. + +#### Linking through a CMake target of the cryptography library +The base name of the CMake cryptography library target has been changed from `mbedcrypto` to `tfpsacrypto`. +If no target prefix is specified through the MBEDTLS_TARGET_PREFIX option, the associated CMake target is thus now `tfpsacrypto`. + +The same renaming applies to the cryptography library targets declared as part of the Mbed TLS CMake package. +When no global target prefix is defined, use `MbedTLS::tfpsacrypto` instead of `MbedTLS::mbedcrypto`. + +As an example, the following CMake code: +``` +find_package(MbedTLS REQUIRED) +target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::mbedcrypto) + +``` +would be updated to something like +``` +find_package(MbedTLS REQUIRED) +target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::tfpsacrypto) +``` + +For more information, see the CMake section of `README.md`. +You can also refer to the following example programs demonstrating how to consume Mbed TLS via CMake: +* `programs/test/cmake_subproject` +* `programs/test/cmake_package` +* `programs/test/cmake_package_install`. + +#### Using Mbed TLS Crypto pkg-config file +The Mbed TLS CMake build system still provides the pkg-config file mbedcrypto.pc, so you can continue using it. Internally, it now references the `tfpsacrypto` library. +A new pkg-config file, `tfpsacrypto.pc`, is also provided. +Both `mbedcrypto.pc` and `tfpsacrypto.pc` are functionally equivalent, providing the same compiler and linker flags. + +### Audience-Specific Notes + +#### Application Developers using a distribution package +You should stay with Mbed TLS if you use TLS or X.509 functionality. +- See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on: + - Linking against the cryptography library or CMake targets. + - Use the updated `pkg-config` files (`mbedcrypto.pc` / `tfpsacrypto.pc`). + +### Developer or package maintainers +If you build or distribute Mbed TLS: +- The build system is now CMake only, Makefiles and Visual Studio projects are removed. +- You may need to adapt packaging scripts to handle the TF-PSA-Crypto submodule. +- You should update submodules recursively after checkout. +- Review [File and directory relocations](#file-and-directory-relocations) for updated paths. +- See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on: + - Linking against the cryptography library or CMake targets. + - Use the updated `pkg-config` files (`mbedcrypto.pc` / `tfpsacrypto.pc`). +- Configuration note: cryptography and platform options are now in `crypto_config.h` (see [Configuration file split](#configuration-file-split)). + +### Platform Integrators +If you integrate Mbed TLS with a platform or hardware drivers: +- TF-PSA-Crypto is now a submodule, update integration scripts to initialize submodules recursively. +- The PSA driver wrapper is now generated in TF-PSA-Crypto. +- Platform-specific configuration are now handled in `crypto_config.h`. +- See [Repository split](#repository-split) for how platform components moved to TF-PSA-Crypto. From a5e1b6d32859bb1bb983b3f7b0f493d225b94afc Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 8 Oct 2025 09:10:54 +0200 Subject: [PATCH 24/47] Rework "CMake as the only build system" section Signed-off-by: Ronald Cron --- docs/4.0-migration-guide/repo-split.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md index 4e8da82e3d..880d1f4746 100644 --- a/docs/4.0-migration-guide/repo-split.md +++ b/docs/4.0-migration-guide/repo-split.md @@ -1,11 +1,10 @@ ## CMake as the only build system -CMake is now the only supported build system for Mbed TLS. -Support for the legacy GNU Make and Microsoft Visual Studio project-based build systems has been removed. +Mbed TLS now uses CMake exclusively to configure and drive its build process. +Support for the GNU Make and Microsoft Visual Studio project-based build systems has been removed. -The GNU Make build system is still used internally for testing, but it will be removed once all test components have been migrated to CMake. -The previous .sln/.vcxproj files are no longer distributed or generated. +The previous `.sln` and `.vcxproj` files are no longer distributed or generated. -Builds must now be configured and executed through CMake. See `Compiling` section in README.md for initial build instructions. +See the `Compiling` section in README.md for instructions on building the Mbed TLS libraries and tests with CMake. If you develop in Microsoft Visual Studio, you could either generate a Visual Studio solution using a CMake generator, or open the CMake project directly in Visual Studio. ## Repository split From c7646249bb6d452636b5cc3365cfe7d307517ce9 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 8 Oct 2025 09:59:01 +0200 Subject: [PATCH 25/47] Various small changes Signed-off-by: Ronald Cron --- docs/4.0-migration-guide/repo-split.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md index 880d1f4746..6be9396cc7 100644 --- a/docs/4.0-migration-guide/repo-split.md +++ b/docs/4.0-migration-guide/repo-split.md @@ -12,7 +12,7 @@ In Mbed TLS 4.0, the project was split into two repositories: - [Mbed TLS](https://github.com/Mbed-TLS/mbedtls): provides TLS and X.509 functionality. - [TF-PSA-Crypto](https://github.com/Mbed-TLS/TF-PSA-Crypto): provides the standalone cryptography library, implementing the PSA Cryptography API. Mbed TLS consumes TF-PSA-Crypto as a submodule. -You should stay with Mbed TLS if you use TLS or X.509 functionality. You still have direct access to the PSA Cryptography API through the `tf-psa-crypto` submodule. +You should stay with Mbed TLS if you use TLS or X.509 functionality. You still have direct access to the cryptography library. ### File and directory relocations @@ -70,13 +70,12 @@ You can also refer to the following example programs demonstrating how to consum #### Using Mbed TLS Crypto pkg-config file The Mbed TLS CMake build system still provides the pkg-config file mbedcrypto.pc, so you can continue using it. Internally, it now references the `tfpsacrypto` library. -A new pkg-config file, `tfpsacrypto.pc`, is also provided. +A new pkg-config file, `tfpsacrypto.pc`, is also provided. Both `mbedcrypto.pc` and `tfpsacrypto.pc` are functionally equivalent, providing the same compiler and linker flags. ### Audience-Specific Notes #### Application Developers using a distribution package -You should stay with Mbed TLS if you use TLS or X.509 functionality. - See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on: - Linking against the cryptography library or CMake targets. - Use the updated `pkg-config` files (`mbedcrypto.pc` / `tfpsacrypto.pc`). From d3f02cddd469bf4b73802408216bf730d2e926ed Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 8 Oct 2025 09:52:59 +0200 Subject: [PATCH 26/47] Improve file and directory relocation table Signed-off-by: Ronald Cron --- docs/4.0-migration-guide/repo-split.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md index 6be9396cc7..76443beff9 100644 --- a/docs/4.0-migration-guide/repo-split.md +++ b/docs/4.0-migration-guide/repo-split.md @@ -19,14 +19,14 @@ You should stay with Mbed TLS if you use TLS or X.509 functionality. You still h The following table summarizes the file and directory relocations resulting from the repository split between Mbed TLS and TF-PSA-Crypto. These changes reflect the move of cryptographic, cryptographic-adjacent, and platform components from Mbed TLS into the new TF-PSA-Crypto repository. -| Original location | New location(s) | Notes | -|--------------------------------------|--------------------------------------------------------------------------------------|-------| -| `library/` | `tf-psa-crypto/core/`
`tf-psa-crypto/drivers/builtin/src/` | Contains cryptographic, cryptographic-adjacent (e.g., ASN.1, Base64), and platform C modules and headers. | -| `include/mbedtls/` | `tf-psa-crypto/include/mbedtls/`
`tf-psa-crypto/drivers/builtin/include/private/` | Public headers moved to `include/mbedtls`; now internal headers moved to `include/private`. | -| `include/psa/` | `tf-psa-crypto/include/` | All PSA headers consolidated here. | -| `3rdparty/everest/`
`3rdparty/p256-m/` | `tf-psa-crypto/drivers/` | Third-party crypto driver implementations. | +| Original location | New location(s) | Notes | +|-----------------------------------------|--------------------------------------------------------------------------------------|-------| +| `library/*` (\*) | `tf-psa-crypto/core/`
`tf-psa-crypto/drivers/builtin/src/` | Contains cryptographic, cryptographic-adjacent (e.g., ASN.1, Base64), and platform C modules and headers. | +| `include/mbedtls/*` (\*) | `tf-psa-crypto/include/mbedtls/`
`tf-psa-crypto/drivers/builtin/include/private/` | Public headers moved to `include/mbedtls`; now internal headers moved to `include/private`. | +| `include/psa` | `tf-psa-crypto/include/psa` | All PSA headers consolidated here. | +| `3rdparty/everest`
`3rdparty/p256-m` | `tf-psa-crypto/drivers/everest`
`tf-psa-crypto/drivers/p256-m` | Third-party crypto driver implementations. | -If you use your own build system to build Mbed TLS libraries, you will need to adapt to the new tree. +(\*) The `library` and `include/mbedtls` directories still exist in Mbed TLS, but not contain only TLS and X.509 components. ### Configuration file split Cryptography and platform configuration options have been moved from `mbedtls_config.h` to `crypto_config.h`, which is now mandatory. See [Compile-time configuration](#compile-time-confiuration). From 79a2631a1128f2fcef5db6b2be8eebaa7feb8ab9 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 8 Oct 2025 11:29:52 +0200 Subject: [PATCH 27/47] Expand "Configuration file split" section Signed-off-by: Ronald Cron --- docs/4.0-migration-guide/repo-split.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md index 76443beff9..c7d0b0c3b4 100644 --- a/docs/4.0-migration-guide/repo-split.md +++ b/docs/4.0-migration-guide/repo-split.md @@ -29,7 +29,23 @@ These changes reflect the move of cryptographic, cryptographic-adjacent, and pla (\*) The `library` and `include/mbedtls` directories still exist in Mbed TLS, but not contain only TLS and X.509 components. ### Configuration file split -Cryptography and platform configuration options have been moved from `mbedtls_config.h` to `crypto_config.h`, which is now mandatory. See [Compile-time configuration](#compile-time-confiuration). +Cryptography and platform configuration options have been moved from `include/mbedtls/mbedtls_config.h` to `tf-psa-crypto/include/psa/crypto_config.h`, which is now mandatory. +See [Compile-time configuration](#compile-time-configuration). + +The header `include/mbedtls/mbedtls_config.h` still exists and now contains only the TLS and X.509 configuration options. + +If you use the Python script `scripts/config.py` to adjust your configuration, you do not need to modify your scripts to specify which configuration file to edit, the script automatically updates the correct file. + +There has been significant changes in the configuration options, primarily affecting cryptography. + +#### Cryptography configuration +- See [psa-transition.md](https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/psa-transition.md#compile-time-configuration). +- See also the following sections in the TF-PSA-Crypto 1.0 migration guide: + - *PSA as the Only Cryptography API* and its sub-section *Impact on the Library Configuration* + - *Random Number Generation Configuration* + +#### TLS configuration +For details about TLS-related changes, see [Changes to TLS options](#changes-to-tls-options). ### Impact on some usages of the library From 5d069c99891ac4ec3713219b84f93a60e727debd Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 8 Oct 2025 12:08:55 +0200 Subject: [PATCH 28/47] Add Make to CMake migration section Signed-off-by: Ronald Cron --- docs/4.0-migration-guide/repo-split.md | 48 ++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md index c7d0b0c3b4..466c9a0124 100644 --- a/docs/4.0-migration-guide/repo-split.md +++ b/docs/4.0-migration-guide/repo-split.md @@ -7,6 +7,54 @@ The previous `.sln` and `.vcxproj` files are no longer distributed or generated. See the `Compiling` section in README.md for instructions on building the Mbed TLS libraries and tests with CMake. If you develop in Microsoft Visual Studio, you could either generate a Visual Studio solution using a CMake generator, or open the CMake project directly in Visual Studio. +### Translating Make commands to CMake + +With the removal of GNU Make support, all build, test, and installation operations must now be performed using CMake. +This section provides a quick reference for translating common `make` commands into their CMake equivalents. + +#### Basic build workflow + +Run `cmake -S . -B build` once before building to configure the build and generate native build files (e.g., Makefiles) in the `build` directory. +This sets up an out-of-tree build, which is recommended. + +| Make command | CMake equivalent | Description | +|----------------|------------------------------------------------|--------------------------------------------------------------------| +| `make` | `cmake --build build` | Build the libraries, programs, and tests in the `build` directory. | +| `make test` | `ctest --test-dir build` | Run the tests produced by the previous build. | +| `make clean` | `cmake --build build --target clean` | Remove build artifacts produced by the previous build. | +| `make install` | `cmake --install build --prefix build/install` | Install the built libraries, headers, and tests to `build/install`. | + +#### Building specific targets + +Unless otherwise specified, the CMake command in the table below should be preceded by a `cmake -S . -B build` call to configure the build and generate build files in the `build` directory. + +| Make command | CMake equivalent | Description | +|-----------------|---------------------------------------------------------------------|---------------------------| +| `make lib` | `cmake --build build --target lib` | Build only the libraries. | +| `make tests` | `cmake -S . -B build -DENABLE_PROGRAMS=Off && cmake --build build` | Build test suites. | +| `make programs` | `cmake --build build --target programs` | Build example programs. | +| `make apidoc` | `cmake --build build --target mbedtls-apidoc` | Build documentation. | + +Target names may differ slightly; use `cmake --build build --target help` to list all available CMake targets. + +There is no CMake equivalent for `make generated_files` or `make neat`. +Generated files are automatically created in the build tree with `cmake --build build` and removed with `cmake --build build --target clean`. +If you need to build the generated files in the source tree without involving CMake, you can call `framework/scripts/make_generated_files.py`. + +There is no CMake equivalent for `make uninstall`. +To remove an installation, simply delete the directory specified as the installation prefix. + +#### Common build options + +| Make usage | CMake usage | Description | +|----------------------------|-------------------------------------------------------|----------------------| +| `make DEBUG=1` | `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug` | Build in debug mode. | +| `make SHARED=1` | `cmake -S . -B build -DUSE_SHARED_MBEDTLS_LIBRARY=On` | Also build shared libraries. | +| `make GEN_FILES=""` | `cmake -S . -B build -DGEN_FILES=OFF` | Skip generating files (not a strict equivalent). | +| `make DESTDIR=install_dir` | `cmake --install build --prefix install_dir` | Specify installation path. | +| `make CC=clang` | `cmake -S . -B build -DCMAKE_C_COMPILER=clang` | Set the compiler. | +| `make CFLAGS='-O2 -Wall'` | `cmake -S . -B build -DCMAKE_C_FLAGS="-O2 -Wall"` | Set compiler flags. | + ## Repository split In Mbed TLS 4.0, the project was split into two repositories: - [Mbed TLS](https://github.com/Mbed-TLS/mbedtls): provides TLS and X.509 functionality. From 25b1a0245491451865734322543d2e1d703fc91c Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 8 Oct 2025 17:15:30 +0200 Subject: [PATCH 29/47] Rework "Impact on some usages of the library" section Signed-off-by: Ronald Cron --- docs/4.0-migration-guide/repo-split.md | 56 ++++++++++++++++++-------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md index 466c9a0124..4f51f7b676 100644 --- a/docs/4.0-migration-guide/repo-split.md +++ b/docs/4.0-migration-guide/repo-split.md @@ -104,38 +104,62 @@ git submodule update --init --recursive ``` #### Linking directly to a built library -The Mbed TLS CMake build system still provides the cryptography libraries under their legacy name, `libmbedcrypto.`, so you can continue linking against them. -The cryptography libraries are also now provided as `libtfpsacrypto.` like in the TF-PSA-Crypto repository. -#### Linking through a CMake target of the cryptography library +The Mbed TLS CMake build system still provides the cryptography libraries under their legacy name, `libmbedcrypto.`, so you can continue linking against them. +These libraries are still located in the `library` directory within the build tree. + +The cryptography libraries are also now provided as `libtfpsacrypto.`, consistent with the naming used in the TF-PSA-Crypto repository. + +You may need to update include paths to the public header files, see [File and Directory Relocations](#file-and-directory-relocations) for details. + +#### Using Mbed TLS as a CMake subproject + The base name of the CMake cryptography library target has been changed from `mbedcrypto` to `tfpsacrypto`. -If no target prefix is specified through the MBEDTLS_TARGET_PREFIX option, the associated CMake target is thus now `tfpsacrypto`. +If no target prefix is specified through the `MBEDTLS_TARGET_PREFIX` option, the associated CMake target is now `tfpsacrypto`, and you will need to update it in your CMake scripts. + +You can refer to the following example demonstrating how to consume Mbed TLS as a CMake subproject: +- `programs/test/cmake_subproject` + +#### Using Mbed TLS as a CMake package The same renaming applies to the cryptography library targets declared as part of the Mbed TLS CMake package. When no global target prefix is defined, use `MbedTLS::tfpsacrypto` instead of `MbedTLS::mbedcrypto`. -As an example, the following CMake code: +For example, the following CMake code: ``` find_package(MbedTLS REQUIRED) target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::mbedcrypto) - ``` -would be updated to something like +should be updated to: ``` find_package(MbedTLS REQUIRED) target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::tfpsacrypto) ``` +You can also refer to the following example programs demonstrating how to consume Mbed TLS as a CMake package: +- programs/test/cmake_package +- programs/test/cmake_package_install -For more information, see the CMake section of `README.md`. -You can also refer to the following example programs demonstrating how to consume Mbed TLS via CMake: -* `programs/test/cmake_subproject` -* `programs/test/cmake_package` -* `programs/test/cmake_package_install`. +#### Using the Mbed TLS Crypto pkg-config file -#### Using Mbed TLS Crypto pkg-config file -The Mbed TLS CMake build system still provides the pkg-config file mbedcrypto.pc, so you can continue using it. Internally, it now references the `tfpsacrypto` library. -A new pkg-config file, `tfpsacrypto.pc`, is also provided. -Both `mbedcrypto.pc` and `tfpsacrypto.pc` are functionally equivalent, providing the same compiler and linker flags. +The Mbed TLS CMake build system still provides the pkg-config file mbedcrypto.pc, so you can continue using it. +Internally, it now references the tfpsacrypto library. + +A new pkg-config file, tfpsacrypto.pc, is also provided. +Both mbedcrypto.pc and tfpsacrypto.pc are functionally equivalent, providing the same compiler and linker flags. + +#### Using Mbed TLS as an installed library + +The Mbed TLS CMake build system still installs the cryptography libraries under their legacy name, `libmbedcrypto.`, so you can continue linking against them. +The cryptography library is also now provided as `libtfpsacrypto.`. + +Regarding the headers, the main change is the relocation of some headers to private directories. +These headers are installed primarily to satisfy compiler dependencies. +Others remain for historical reasons and may be cleaned up in later versions of the library. + +We strongly recommend not relying on the declarations in these headers, as they may be removed or modified without notice. +See the section Private Declarations in the TF-PSA-Crypto 1.0 migration guide for more information. + +Finally, note the new include/tf-psa-crypto directory, which contains the TF-PSA-Crypto version and build-time configuration headers. ### Audience-Specific Notes From de8bb9628dfc4b468de5d692f6df29558e055c4d Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 9 Oct 2025 10:45:36 +0200 Subject: [PATCH 30/47] Change footnote indication Signed-off-by: Ronald Cron --- docs/4.0-migration-guide/repo-split.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md index 4f51f7b676..ca4403b5a2 100644 --- a/docs/4.0-migration-guide/repo-split.md +++ b/docs/4.0-migration-guide/repo-split.md @@ -69,12 +69,12 @@ These changes reflect the move of cryptographic, cryptographic-adjacent, and pla | Original location | New location(s) | Notes | |-----------------------------------------|--------------------------------------------------------------------------------------|-------| -| `library/*` (\*) | `tf-psa-crypto/core/`
`tf-psa-crypto/drivers/builtin/src/` | Contains cryptographic, cryptographic-adjacent (e.g., ASN.1, Base64), and platform C modules and headers. | -| `include/mbedtls/*` (\*) | `tf-psa-crypto/include/mbedtls/`
`tf-psa-crypto/drivers/builtin/include/private/` | Public headers moved to `include/mbedtls`; now internal headers moved to `include/private`. | +| `library/*` (†) | `tf-psa-crypto/core/`
`tf-psa-crypto/drivers/builtin/src/` | Contains cryptographic, cryptographic-adjacent (e.g., ASN.1, Base64), and platform C modules and headers. | +| `include/mbedtls/*` (†) | `tf-psa-crypto/include/mbedtls/`
`tf-psa-crypto/drivers/builtin/include/private/` | Public headers moved to `include/mbedtls`; now internal headers moved to `include/private`. | | `include/psa` | `tf-psa-crypto/include/psa` | All PSA headers consolidated here. | | `3rdparty/everest`
`3rdparty/p256-m` | `tf-psa-crypto/drivers/everest`
`tf-psa-crypto/drivers/p256-m` | Third-party crypto driver implementations. | -(\*) The `library` and `include/mbedtls` directories still exist in Mbed TLS, but not contain only TLS and X.509 components. +(†) The `library` and `include/mbedtls` directories still exist in Mbed TLS, but not contain only TLS and X.509 components. ### Configuration file split Cryptography and platform configuration options have been moved from `include/mbedtls/mbedtls_config.h` to `tf-psa-crypto/include/psa/crypto_config.h`, which is now mandatory. From f37dbf67cb68964fd1ca2fa726ca8e555a0198b9 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 9 Oct 2025 11:00:38 +0200 Subject: [PATCH 31/47] Add missing typesettings Signed-off-by: Ronald Cron --- docs/4.0-migration-guide/repo-split.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md index ca4403b5a2..98c646258b 100644 --- a/docs/4.0-migration-guide/repo-split.md +++ b/docs/4.0-migration-guide/repo-split.md @@ -136,16 +136,16 @@ find_package(MbedTLS REQUIRED) target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::tfpsacrypto) ``` You can also refer to the following example programs demonstrating how to consume Mbed TLS as a CMake package: -- programs/test/cmake_package -- programs/test/cmake_package_install +- `programs/test/cmake_package` +- `programs/test/cmake_package_install` #### Using the Mbed TLS Crypto pkg-config file The Mbed TLS CMake build system still provides the pkg-config file mbedcrypto.pc, so you can continue using it. Internally, it now references the tfpsacrypto library. -A new pkg-config file, tfpsacrypto.pc, is also provided. -Both mbedcrypto.pc and tfpsacrypto.pc are functionally equivalent, providing the same compiler and linker flags. +A new pkg-config file, `tfpsacrypto.pc`, is also provided. +Both `mbedcrypto.pc` and `tfpsacrypto.pc` are functionally equivalent, providing the same compiler and linker flags. #### Using Mbed TLS as an installed library @@ -159,7 +159,7 @@ Others remain for historical reasons and may be cleaned up in later versions of We strongly recommend not relying on the declarations in these headers, as they may be removed or modified without notice. See the section Private Declarations in the TF-PSA-Crypto 1.0 migration guide for more information. -Finally, note the new include/tf-psa-crypto directory, which contains the TF-PSA-Crypto version and build-time configuration headers. +Finally, note the new `include/tf-psa-crypto` directory, which contains the TF-PSA-Crypto version and build-time configuration headers. ### Audience-Specific Notes From 15557d0d0370a819a703fe860c92b33fef3acfb4 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 9 Oct 2025 11:05:25 +0200 Subject: [PATCH 32/47] Various improvements Signed-off-by: Ronald Cron --- docs/4.0-migration-guide/repo-split.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md index 98c646258b..7f966ac0d4 100644 --- a/docs/4.0-migration-guide/repo-split.md +++ b/docs/4.0-migration-guide/repo-split.md @@ -41,8 +41,7 @@ There is no CMake equivalent for `make generated_files` or `make neat`. Generated files are automatically created in the build tree with `cmake --build build` and removed with `cmake --build build --target clean`. If you need to build the generated files in the source tree without involving CMake, you can call `framework/scripts/make_generated_files.py`. -There is no CMake equivalent for `make uninstall`. -To remove an installation, simply delete the directory specified as the installation prefix. +There is currently no equivalent for `make uninstall` in the Mbed TLS CMake build system. #### Common build options @@ -74,7 +73,7 @@ These changes reflect the move of cryptographic, cryptographic-adjacent, and pla | `include/psa` | `tf-psa-crypto/include/psa` | All PSA headers consolidated here. | | `3rdparty/everest`
`3rdparty/p256-m` | `tf-psa-crypto/drivers/everest`
`tf-psa-crypto/drivers/p256-m` | Third-party crypto driver implementations. | -(†) The `library` and `include/mbedtls` directories still exist in Mbed TLS, but not contain only TLS and X.509 components. +(†) The `library` and `include/mbedtls` directories still exist in Mbed TLS, but now contain only TLS and X.509 components. ### Configuration file split Cryptography and platform configuration options have been moved from `include/mbedtls/mbedtls_config.h` to `tf-psa-crypto/include/psa/crypto_config.h`, which is now mandatory. @@ -152,7 +151,7 @@ Both `mbedcrypto.pc` and `tfpsacrypto.pc` are functionally equivalent, providing The Mbed TLS CMake build system still installs the cryptography libraries under their legacy name, `libmbedcrypto.`, so you can continue linking against them. The cryptography library is also now provided as `libtfpsacrypto.`. -Regarding the headers, the main change is the relocation of some headers to private directories. +Regarding the headers, the main change is the relocation of some headers to subdirectories called `private`. These headers are installed primarily to satisfy compiler dependencies. Others remain for historical reasons and may be cleaned up in later versions of the library. From dca3b381fa222e53dbe0be3c5ddfce371f018f3b Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 9 Oct 2025 17:21:23 +0200 Subject: [PATCH 33/47] Various improvements Signed-off-by: Ronald Cron --- docs/4.0-migration-guide/repo-split.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md index 7f966ac0d4..e18fbf1ae3 100644 --- a/docs/4.0-migration-guide/repo-split.md +++ b/docs/4.0-migration-guide/repo-split.md @@ -45,6 +45,9 @@ There is currently no equivalent for `make uninstall` in the Mbed TLS CMake buil #### Common build options +The following table illustrates the approximate CMake equivalents of common make commands. +Most CMake examples show only the configuration step, others (like installation) correspond to different stages of the build process. + | Make usage | CMake usage | Description | |----------------------------|-------------------------------------------------------|----------------------| | `make DEBUG=1` | `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug` | Build in debug mode. | @@ -83,7 +86,7 @@ The header `include/mbedtls/mbedtls_config.h` still exists and now contains only If you use the Python script `scripts/config.py` to adjust your configuration, you do not need to modify your scripts to specify which configuration file to edit, the script automatically updates the correct file. -There has been significant changes in the configuration options, primarily affecting cryptography. +There have been significant changes in the configuration options, primarily affecting cryptography. #### Cryptography configuration - See [psa-transition.md](https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/psa-transition.md#compile-time-configuration). @@ -165,7 +168,8 @@ Finally, note the new `include/tf-psa-crypto` directory, which contains the TF-P #### Application Developers using a distribution package - See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on: - Linking against the cryptography library or CMake targets. - - Use the updated `pkg-config` files (`mbedcrypto.pc` / `tfpsacrypto.pc`). + - Using the Mbed TLS Crypto pkg-config file. + - Using Mbed TLS as an installed library ### Developer or package maintainers If you build or distribute Mbed TLS: @@ -175,7 +179,8 @@ If you build or distribute Mbed TLS: - Review [File and directory relocations](#file-and-directory-relocations) for updated paths. - See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on: - Linking against the cryptography library or CMake targets. - - Use the updated `pkg-config` files (`mbedcrypto.pc` / `tfpsacrypto.pc`). + - Using the Mbed TLS Crypto pkg-config file (`mbedcrypto.pc` or `tfpsacrypto.pc`). + - Using Mbed TLS as an installed library - Configuration note: cryptography and platform options are now in `crypto_config.h` (see [Configuration file split](#configuration-file-split)). ### Platform Integrators From 7c39b6055e6e87fea4e7f02f39f1fc2d50ed0913 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 9 Oct 2025 18:07:59 +0200 Subject: [PATCH 34/47] Improve sections "Using Mbed TLS as a CMake subproject/package" Signed-off-by: Ronald Cron --- docs/4.0-migration-guide/repo-split.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md index e18fbf1ae3..5ad741855b 100644 --- a/docs/4.0-migration-guide/repo-split.md +++ b/docs/4.0-migration-guide/repo-split.md @@ -116,26 +116,35 @@ You may need to update include paths to the public header files, see [File and D #### Using Mbed TLS as a CMake subproject -The base name of the CMake cryptography library target has been changed from `mbedcrypto` to `tfpsacrypto`. -If no target prefix is specified through the `MBEDTLS_TARGET_PREFIX` option, the associated CMake target is now `tfpsacrypto`, and you will need to update it in your CMake scripts. +The base name of the libraries are now `tfpsacrypto` (formely `mbedcrypto`), `mbedx509` and `mbedtls`. +As before, these base names are also the names of CMake targets to build each library. +If your CMake scripts reference a cryptography library target, you need to update its name accordingly. + +For example, the following CMake code: +``` +target_link_libraries(mytarget PRIVATE mbedcrypto) +``` +should be updated to: +``` +target_link_libraries(mytarget PRIVATE tfpsacrypto) +``` You can refer to the following example demonstrating how to consume Mbed TLS as a CMake subproject: - `programs/test/cmake_subproject` #### Using Mbed TLS as a CMake package -The same renaming applies to the cryptography library targets declared as part of the Mbed TLS CMake package. -When no global target prefix is defined, use `MbedTLS::tfpsacrypto` instead of `MbedTLS::mbedcrypto`. +The same renaming applies to the cryptography library targets declared as part of the Mbed TLS CMake package, use `MbedTLS::tfpsacrypto` instead of `MbedTLS::mbedcrypto`. For example, the following CMake code: ``` find_package(MbedTLS REQUIRED) -target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::mbedcrypto) +target_link_libraries(myapp PRIVATE MbedTLS::mbedcrypto) ``` should be updated to: ``` find_package(MbedTLS REQUIRED) -target_link_libraries(myapp PRIVATE MbedTLS::mbedtls MbedTLS::mbedx509 MbedTLS::tfpsacrypto) +target_link_libraries(myapp PRIVATE MbedTLS::tfpsacrypto) ``` You can also refer to the following example programs demonstrating how to consume Mbed TLS as a CMake package: - `programs/test/cmake_package` From 9fc5910bdc8d027f33ae80d2fddbd93f7a688c1b Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 10 Oct 2025 15:48:06 +0200 Subject: [PATCH 35/47] Remove 3.0 migration guide Migrating from 2.x to 3.0 is no longer relevant: some of the advice wouldn't work with 4.0. We don't really need a migration guide from 3.x any longer since 2.x is no longer officially supported. Signed-off-by: Gilles Peskine --- docs/3.0-migration-guide.md | 1039 ----------------------------------- 1 file changed, 1039 deletions(-) delete mode 100644 docs/3.0-migration-guide.md diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md deleted file mode 100644 index e927667b7e..0000000000 --- a/docs/3.0-migration-guide.md +++ /dev/null @@ -1,1039 +0,0 @@ -# Migrating from Mbed TLS 2.x to Mbed TLS 3.0 - -This guide details the steps required to migrate from Mbed TLS version 2.x to -Mbed TLS version 3.0 or greater. Unlike normal releases, Mbed TLS 3.0 breaks -compatibility with previous versions, so users (and alt implementers) might -need to change their own code in order to make it work with Mbed TLS 3.0. - -Here's the list of breaking changes; each entry should help you answer these -two questions: (1) am I affected? (2) if yes, what's my migration path? - -The changes are detailed below, and include: - -- Removal of many insecure or obsolete features -- Tidying up of configuration options (including removing some less useful options). -- Changing function signatures, e.g. adding return codes, adding extra parameters, or making some arguments const. -- Removal of functions, macros, and types previously marked as deprecated. - -Much of the information needed to determine a migration path can be found in the Mbed TLS 2.x documentation. - - -## Accessing the Mbed TLS 2.x documentation - -For features previously marked as deprecated, Mbed TLS 2.x documentation may -explain how to upgrade, and should be referred to when migrating code. Where a -migration path is not provided in prior documentation, changes made and the -upgrade steps required will be explained later in this guide. - -It's best to use the latest version of Mbed TLS 2.x for this purpose, which is the 2.28 LTS release. -So to generate the documentation, checkout the `mbedtls-2.28` branch and follow -the instructions in the [Documentation section of the README](https://github.com/Mbed-TLS/mbedtls/blob/mbedtls-2.28/README.md#documentation). -Then browse `apidoc/deprecated.html` for guidance on upgrading deprecated code. - -For some deprecated functions, 2.x documentation will suggest using a variant -suffixed with `_ret`. In Mbed TLS 3.x, this change may not be required, as most -of these variants have been renamed without the suffix. The section -[Rename mbedtls_*_ret...](#rename-mbedtls__ret-cryptography-functions-whose-deprecated-variants-have-been-removed) -has further detail on which functions this applies to. - - -## General changes - -### Introduce a level of indirection and versioning in the config files - -`config.h` was split into `build_info.h` and `mbedtls_config.h`. - -* In code, use `#include `. Don't include `mbedtls/config.h` and don't refer to `MBEDTLS_CONFIG_FILE`. -* In build tools, edit `mbedtls_config.h`, or edit `MBEDTLS_CONFIG_FILE` as before. -* If you had a tool that parsed the library version from `include/mbedtls/version.h`, this has moved to `include/mbedtls/build_info.h`. From C code, both headers now define the `MBEDTLS_VERSION_xxx` macros. - -Also, if you have a custom configuration file: - -* Don't include `check_config.h` or `config_psa.h` anymore. -* Don't define `MBEDTLS_CONFIG_H` anymore. - -A config file version symbol, `MBEDTLS_CONFIG_VERSION` was introduced. -Defining it to a particular value will ensure that Mbed TLS interprets -the config file in a way that's compatible with the config file format -used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same -value. -The only value supported by Mbed TLS 3.0.0 is `0x03000000`. - -### Most structure fields are now private - -Direct access to fields of structures (`struct` types) declared in public headers is no longer supported. In Mbed TLS 3, the layout of structures is not considered part of the stable API, and minor versions (3.1, 3.2, etc.) may add, remove, rename, reorder or change the type of structure fields. - -There is a small number of exceptions where some fields are guaranteed to remain stable throughout the lifetime of Mbed TLS 3.x. These fields are explicitly documented as public. Please note that even if all the fields of a structure are public, future versions may add new fields. Also, as before, some public fields should be considered read-only, since modifying them may make the structure inconsistent; check the documentation in each case. - -Attempting to access a private field directly will result in a compilation error. - -If you were accessing structure fields directly, and these fields are not documented as public, you need to change your code. If an accessor (getter/setter) function exists, use that. Direct accessor functions are usually called `mbedtls__{get,set}_` or `mbedtls___{get,set}_`. Accessor functions that change the format may use different verbs, for example `read`/`write` for functions that import/export data from/to a text or byte string. - -If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/Mbed-TLS/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them to the first minor release(s) (3.1, etc.). - -As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS. In the Mbed TLS 3.6 LTS this will tend to be safer than in a normal minor release because LTS versions try to maintain ABI stability. - -### Move part of timing module out of the library - -The change affects users who use any of the following functions: -`mbedtls_timing_self_test()`, `mbedtls_hardclock_poll()`, -`mbedtls_timing_hardclock()` and `mbedtls_set_alarm()`. - -If you were relying on these functions, you'll now need to change to using your -platform's corresponding functions directly. - -### Deprecated net.h file was removed - -The file `include/mbedtls/net.h` was removed because its only function was to -include `mbedtls/net_sockets.h` which now should be included directly. - -### Remove `MBEDTLS_CHECK_PARAMS` option - -This change does not affect users who use the default configuration; it only -affects users who enabled that option. - -The option `MBEDTLS_CHECK_PARAMS` (disabled by default) enabled certain kinds -of “parameter validation”. It covered two kinds of validations: - -- In some functions that require a valid pointer, “parameter validation” checks -that the pointer is non-null. With the feature disabled, a null pointer is not -treated differently from any other invalid pointer, and typically leads to a -runtime crash. 90% of the uses of the feature are of this kind. -- In some functions that take an enum-like argument, “parameter validation” -checks that the value is a valid one. With the feature disabled, an invalid -value causes a silent default to one of the valid values. - -The default reaction to a failed check was to call a function -`mbedtls_param_failed()` which the application had to provide. If this function -returned, its caller returned an error `MBEDTLS_ERR_xxx_BAD_INPUT_DATA`. - -This feature was only used in some classic (non-PSA) cryptography modules. It was -not used in X.509, TLS or in PSA crypto, and it was not implemented in all -classic crypto modules. - -This feature has been removed. The library no longer checks for NULL pointers; -checks for enum-like arguments will be kept or re-introduced on a case-by-case -basis, but their presence will no longer be dependent on a compile-time option. - -Validation of enum-like values is somewhat useful, but not extremely important, -because the parameters concerned are usually constants in applications. - -For more information see issue #4313. - -### Remove the `MBEDTLS_TEST_NULL_ENTROPY` configuration option - -This does not affect users who use the default `mbedtls_config.h`, as this option was -already off by default. - -If you were using the `MBEDTLS_TEST_NULL_ENTROPY` option and your platform -doesn't have any entropy source, you should use `MBEDTLS_ENTROPY_NV_SEED` -and make sure your device is provisioned with a strong random seed. -Alternatively, for testing purposes only, you can create and register a fake -entropy function. - -### Remove the HAVEGE module - -This doesn't affect people using the default configuration as it was already -disabled by default. - -This only affects users who called the HAVEGE modules directly (not -recommended), or users who used it through the entropy module but had it as the -only source of entropy. If you're in that case, please declare OS or hardware -RNG interfaces with `mbedtls_entropy_add_source()` and/or use an entropy seed -file created securely during device provisioning. See - for more -information. - -### Remove helpers for the transition from Mbed TLS 1.3 to Mbed TLS 2.0 - -This only affects people who've been using Mbed TLS since before version 2.0 -and still relied on `compat-1.3.h` in their code. - -Please use the new names directly in your code; `scripts/rename.pl` (from any -of the 2.x releases — no longer included in 3.0) might help you do that. - - -## Low-level crypto - -Please also refer to the section [High-level crypto](#high-level-crypto) for -changes that could sit in either category. - -### Deprecated functions were removed from bignum - -The function `mbedtls_mpi_is_prime()` was removed. Please use -`mbedtls_mpi_is_prime_ext()` instead which additionally allows specifying the -number of Miller-Rabin rounds. - -### Deprecated functions were removed from DRBGs - -The functions `mbedtls_ctr_drbg_update_ret()` and `mbedtls_hmac_drbg_update_ret()` -were renamed to replace the corresponding functions without `_ret` appended. Please call -the name without `_ret` appended and check the return value. - -### Deprecated hex-encoded primes were removed from DHM - -The macros `MBEDTLS_DHM_RFC5114_MODP_2048_P`, `MBEDTLS_DHM_RFC5114_MODP_2048_G`, -`MBEDTLS_DHM_RFC3526_MODP_2048_P`, `MBEDTLS_DHM_RFC3526_MODP_2048_G`, -`MBEDTLS_DHM_RFC3526_MODP_3072_P`, `MBEDTLS_DHM_RFC3526_MODP_3072_G`, -`MBEDTLS_DHM_RFC3526_MODP_4096_P `and `MBEDTLS_DHM_RFC3526_MODP_4096_G` were -removed. The primes from RFC 5114 are deprecated because their derivation is not -documented and therefore their usage constitutes a security risk; they are fully -removed from the library. Please use parameters from RFC 3526 (still in the -library, only in binary form) or RFC 7919 (also available in the library) or -other trusted sources instead. - -### Deprecated functions were removed from hashing modules - -Modules: MD5, SHA1, SHA256, SHA512, MD. - -- The functions `mbedtls_xxx_starts_ret()`, `mbedtls_xxx_update_ret()`, - `mbedtls_xxx_finish_ret()` and `mbedtls_xxx_ret()` were renamed to replace - the corresponding functions without `_ret` appended. Please call the name without `_ret` appended and check the return value. -- The function `mbedtls_md_init_ctx()` was removed; please use - `mbedtls_md_setup()` instead. -- The functions `mbedtls_xxx_process()` were removed. You normally don't need - to call that from application code. However if you do (or if you want to - provide your own version of that function), please use - `mbedtls_internal_xxx_process()` instead, and check the return value. - -### Change `MBEDTLS_ECP_FIXED_POINT_OPTIM` behavior - -The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increases code size and it does -not increase peak RAM usage anymore. - -If you are limited by code size, you can define `MBEDTLS_ECP_FIXED_POINT_OPTIM` -to `0` in your config file. The impact depends on the number and size of -enabled curves. For example, for P-256 the difference is 1KB; see the documentation -of this option for details. - -### Separated `MBEDTLS_SHA224_C` and `MBEDTLS_SHA256_C` - -This does not affect users who use the default `mbedtls_config.h`. `MBEDTLS_SHA256_C` -was enabled by default. Now both `MBEDTLS_SHA256_C` and `MBEDTLS_SHA224_C` are -enabled. - -If you were using custom config file with `MBEDTLS_SHA256_C` enabled, then -you will need to add `#define MBEDTLS_SHA224_C` option to your config. -Current version of the library does not support enabling `MBEDTLS_SHA256_C` -without `MBEDTLS_SHA224_C`. - -### Replaced `MBEDTLS_SHA512_NO_SHA384` with `MBEDTLS_SHA384_C` - -This does not affect users who use the default `mbedtls_config.h`. -`MBEDTLS_SHA512_NO_SHA384` was disabled by default, now `MBEDTLS_SHA384_C` is -enabled by default. - -If you were using a config file with both `MBEDTLS_SHA512_C` and -MBEDTLS_SHA512_NO_SHA384, then just remove the `MBEDTLS_SHA512_NO_SHA384`. -If you were using a config file with `MBEDTLS_SHA512_C` and without -`MBEDTLS_SHA512_NO_SHA384` and you need the SHA-384 algorithm, then add -`#define MBEDTLS_SHA384_C` to your config file. - -### GCM multipart interface: application changes - -The GCM module now supports arbitrary chunked input in the multipart interface. -This changes the interface for applications using the GCM module directly for multipart operations. -Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any changes. - -* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). Call the new function `mbedtls_gcm_update_ad()` to pass the associated data. -* `mbedtls_gcm_update()` now takes an extra parameter to indicate the actual output length. In Mbed TLS 2.x, applications had to pass inputs consisting of whole 16-byte blocks except for the last block (this limitation has been lifted). In this case: - * As long as the input remains block-aligned, the output length is exactly the input length, as before. - * If the length of the last input is not a multiple of 16, alternative implementations may return the last partial block in the call to `mbedtls_gcm_finish()` instead of returning it in the last call to `mbedtls_gcm_update()`. -* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block. This is needed for alternative implementations that can only process a whole block at a time. - -### GCM interface changes: impact for alternative implementations - -The GCM multipart interface has changed as described in [“GCM multipart interface: application changes”](#gcm-multipart-interface-application-changes). The consequences for an alternative implementation of GCM (`MBEDTLS_GCM_ALT`) are as follows: - -* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). The new function `mbedtls_gcm_update_ad()` receives the associated data. It may be called multiple times. -* `mbedtls_gcm_update()` now allows arbitrary-length inputs, takes an extra parameter to indicate the actual output length. Alternative implementations may choose between two modes: - * Always return the partial output immediately, even if it does not consist of a whole number of blocks. - * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`. -* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed. - -### The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed - -This doesn't affect users of the default configuration; it only affects people -who were explicitly setting this option. - -This was a trade-off between code size and countermeasures; it is no longer -relevant as the countermeasure is now always on at no cost in code size. - -### SHA-512 and SHA-256 output type change - -The output parameter of `mbedtls_sha256_finish()`, `mbedtls_sha256()`, `mbedtls_sha512_finish()`, `mbedtls_sha512()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer or a SHA-224 hash into a 28-byte buffer. - -This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer. - -Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly. - -### Deprecated error codes for hardware failures were removed - -- The macros `MBEDTLS_ERR_xxx_FEATURE_UNAVAILABLE` from various crypto modules - were removed; `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used - instead. -- The macro `MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION` was removed; - `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used instead. -- The macros `MBEDTLS_ERR_xxx_HW_ACCEL_FAILED` from various crypto modules - were removed; `MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED` is now used instead. - -### Deprecated error codes for invalid input data were removed - -- The macros `MBEDTLS_ERR_xxx_INVALID_KEY_LENGTH` from ARIA and Camellia - modules were removed; `MBEDTLS_ERR_xxx_BAD_INPUT_DATA` is now used instead. - -### Remove the mode parameter from RSA functions - -This affects all users who use the RSA encrypt, decrypt, sign and -verify APIs. - -The RSA module no longer supports private-key operations with the public key or -vice versa. As a consequence, RSA operation functions no longer have a mode -parameter. If you were calling RSA operations with the normal mode (public key -for verification or encryption, private key for signature or decryption), remove -the `MBEDTLS_RSA_PUBLIC` or `MBEDTLS_RSA_PRIVATE` argument. If you were calling -RSA operations with the wrong mode, which rarely makes sense from a security -perspective, this is no longer supported. - -### Deprecated functions were removed from AES - -The functions `mbedtls_aes_encrypt()` and `mbedtls_aes_decrypt()` were -removed. - -If you're simply using the AES module, you should be calling the higher-level -functions `mbedtls_aes_crypt_xxx()`. - -If you're providing an alternative implementation using -`MBEDTLS_AES_ENCRYPT_ALT` or `MBEDTLS_AES_DECRYPT_ALT`, you should be -replacing the removed functions with `mbedtls_internal_aes_encrypt()` and -`mbedtls_internal_aes_decrypt()` respectively. - -### Deprecated functions were removed from ECDSA - -The functions `mbedtls_ecdsa_write_signature_det()` and -`mbedtls_ecdsa_sign_det()` were removed. They were superseded by -`mbedtls_ecdsa_write_signature()` and `mbedtls_ecdsa_sign_det_ext()` -respectively. - -### Rename `mbedtls_*_ret()` cryptography functions whose deprecated variants have been removed - -This change affects users who were using the `mbedtls_*_ret()` cryptography -functions. - -Those functions were created based on now-deprecated functions according to a -requirement that a function needs to return a value. This change brings back the -original names of those functions. The renamed functions are: - -| name before this change | after the change | -|--------------------------------|----------------------------| -| `mbedtls_ctr_drbg_update_ret` | `mbedtls_ctr_drbg_update` | -| `mbedtls_hmac_drbg_update_ret` | `mbedtls_hmac_drbg_update` | -| `mbedtls_md5_starts_ret` | `mbedtls_md5_starts` | -| `mbedtls_md5_update_ret` | `mbedtls_md5_update` | -| `mbedtls_md5_finish_ret` | `mbedtls_md5_finish` | -| `mbedtls_md5_ret` | `mbedtls_md5` | -| `mbedtls_ripemd160_starts_ret` | `mbedtls_ripemd160_starts` | -| `mbedtls_ripemd160_update_ret` | `mbedtls_ripemd160_update` | -| `mbedtls_ripemd160_finish_ret` | `mbedtls_ripemd160_finish` | -| `mbedtls_ripemd160_ret` | `mbedtls_ripemd160` | -| `mbedtls_sha1_starts_ret` | `mbedtls_sha1_starts` | -| `mbedtls_sha1_update_ret` | `mbedtls_sha1_update` | -| `mbedtls_sha1_finish_ret` | `mbedtls_sha1_finish` | -| `mbedtls_sha1_ret` | `mbedtls_sha1` | -| `mbedtls_sha256_starts_ret` | `mbedtls_sha256_starts` | -| `mbedtls_sha256_update_ret` | `mbedtls_sha256_update` | -| `mbedtls_sha256_finish_ret` | `mbedtls_sha256_finish` | -| `mbedtls_sha256_ret` | `mbedtls_sha256` | -| `mbedtls_sha512_starts_ret` | `mbedtls_sha512_starts` | -| `mbedtls_sha512_update_ret` | `mbedtls_sha512_update` | -| `mbedtls_sha512_finish_ret` | `mbedtls_sha512_finish` | -| `mbedtls_sha512_ret` | `mbedtls_sha512` | - -To migrate to this change the user can keep the `*_ret` names in their code -and include the `compat_2.x.h` header file which holds macros with proper -renaming or to rename those functions in their code according to the list from -mentioned header file. - -### Remove the RNG parameter from RSA verify functions - -RSA verification functions also no longer take random generator arguments (this -was only needed when using a private key). This affects all applications using -the RSA verify functions. - -### Remove the padding parameters from `mbedtls_rsa_init()` - -This affects all users who use the RSA encrypt, decrypt, sign and -verify APIs. - -The function `mbedtls_rsa_init()` no longer supports selecting the PKCS#1 v2.1 -encoding and its hash. It just selects the PKCS#1 v1.5 encoding by default. If -you were using the PKCS#1 v2.1 encoding you now need, subsequently to the call -to `mbedtls_rsa_init()`, to call `mbedtls_rsa_set_padding()` to set it. - -To choose the padding type when initializing a context, instead of - -```C - mbedtls_rsa_init(ctx, padding, hash_id); -``` - -use - -```C - mbedtls_rsa_init(ctx); - mbedtls_rsa_set_padding(ctx, padding, hash_id); -``` - -To use PKCS#1 v1.5 padding, instead of - -```C - mbedtls_rsa_init(ctx, MBEDTLS_RSA_PKCS_V15, ); -``` - -just use - -```C - mbedtls_rsa_init(ctx); -``` - - -## High-level crypto - -Please also refer to the section [Low-level crypto](#low-level-crypto) for -changes that could sit in either category. - -### Calling `mbedtls_cipher_finish()` is mandatory for all multi-part operations - -This only affects people who use the cipher module to perform AEAD operations -using the multi-part API. - -Previously, the documentation didn't state explicitly if it was OK to call -`mbedtls_cipher_check_tag()` or `mbedtls_cipher_write_tag()` directly after -the last call to `mbedtls_cipher_update()` — that is, without calling -`mbedtls_cipher_finish()` in-between. If your code was missing that call, -please add it and be prepared to get as much as 15 bytes of output. - -Currently the output is always 0 bytes, but it may be more when alternative -implementations of the underlying primitives are in use, or with future -versions of the library. - -### Remove MD2, MD4, RC4, Blowfish and XTEA algorithms - -This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms. - -They are already niche or obsolete and most of them are weak or broken. For -those reasons possible users should consider switching to modern and safe -alternatives to be found in the literature. - -### Deprecated functions were removed from cipher - -The functions `mbedtls_cipher_auth_encrypt()` and -`mbedtls_cipher_auth_decrypt()` were removed. They were superseded by -`mbedtls_cipher_auth_encrypt_ext()` and `mbedtls_cipher_auth_decrypt_ext()` -respectively which additionally support key wrapping algorithms such as -NIST_KW. - -### Extra parameter for the output buffer size - -The following functions now take an extra parameter indicating the size of the output buffer: - -* `mbedtls_ecdsa_write_signature()`, `mbedtls_ecdsa_write_signature_restartable()` -* `mbedtls_pk_sign()`, `mbedtls_pk_sign_restartable()` - -The requirements for the output buffer have not changed, but passing a buffer that is too small now reliably causes the functions to return an error, rather than overflowing the buffer. - -### Signature functions now require the hash length to match the expected value - -This affects users of the PK API as well as users of the low-level API in the RSA module. Users of the PSA API or of the ECDSA module are unaffected. - -All the functions in the RSA module that accept a `hashlen` parameter used to -ignore it unless the `md_alg` parameter was `MBEDTLS_MD_NONE`, indicating raw -data was signed. The `hashlen` parameter is now always the size that is read -from the `hash` input buffer. This length must be equal to the output size of -the hash algorithm used when signing a hash. (The requirements when signing -raw data are unchanged.) This affects the following functions: - -* `mbedtls_rsa_pkcs1_sign`, `mbedtls_rsa_pkcs1_verify` -* `mbedtls_rsa_rsassa_pkcs1_v15_sign`, `mbedtls_rsa_rsassa_pkcs1_v15_verify` -* `mbedtls_rsa_rsassa_pss_sign`, `mbedtls_rsa_rsassa_pss_verify` -* `mbedtls_rsa_rsassa_pss_sign_ext`, `mbedtls_rsa_rsassa_pss_verify_ext` - -The signature functions in the PK module no longer accept 0 as the `hash_len` parameter. The `hash_len` parameter is now always the size that is read from the `hash` input buffer. This affects the following functions: - -* `mbedtls_pk_sign`, `mbedtls_pk_verify` -* `mbedtls_pk_sign_restartable`, `mbedtls_pk_verify_restartable` -* `mbedtls_pk_verify_ext` - -The migration path is to pass the correct value to those functions. - -### Some function parameters were made const - -Various functions in the PK and ASN.1 modules had a `const` qualifier added to -some of their parameters. - -This normally doesn't affect your code, unless you use pointers to reference -those functions. In this case, you'll need to update the type of your pointers -in order to match the new signature. - -### The RNG parameter is now mandatory for all functions that accept one - -This change affects all users who called a function accepting a `f_rng` -parameter with `NULL` as the value of this argument; this is no longer -supported. - -The changed functions are: the X.509 CRT and CSR writing functions; the PK and -RSA sign and decrypt functions; `mbedtls_rsa_private()`; the functions in DHM -and ECDH that compute the shared secret; the scalar multiplication functions in -ECP. - -You now need to pass a properly seeded, cryptographically secure RNG to all -functions that accept a `f_rng` parameter. It is of course still possible to -pass `NULL` as the context pointer `p_rng` if your RNG function doesn't need a -context. - -Alternative implementations of a module (enabled with the `MBEDTLS_module_ALT` -configuration options) may have their own internal and are free to ignore the -`f_rng` argument but must allow users to pass one anyway. - -### Some functions gained an RNG parameter - -This affects users of the following functions: `mbedtls_ecp_check_pub_priv()`, -`mbedtls_pk_check_pair()`, `mbedtls_pk_parse_key()`, and -`mbedtls_pk_parse_keyfile()`. - -You now need to pass a properly seeded, cryptographically secure RNG when -calling these functions. It is used for blinding, a countermeasure against -side-channel attacks. - - -## PSA - -### Deprecated names for PSA constants and types were removed - -Some constants and types that were present in beta versions of the PSA Crypto -API were removed from version 1.0 of specification. Please switch to the new -names provided by the 1.0 specification instead. - - -## Changes that only affect alternative implementations - -### Internal / alt-focused headers were moved to a private location - -This shouldn't affect users who took care not to include headers that -were documented as internal, despite being in the public include directory. - -If you're providing alt implementations of ECP or RSA, you'll need to add our -`library` directory to your include path when building your alt -implementations, and note that `ecp_internal.h` and `rsa_internal.h` have been -renamed to `ecp_internal_alt.h` and `rsa_alt_helpers.h` respectively. - -If you're a library user and used to rely on having access to a structure or -function that's now in a private header, please reach out on the mailing list -and explain your need; we'll consider adding a new API in a future version. - -### CCM interface changes: impact for alternative implementations - -The CCM interface has changed with the addition of support for -multi-part operations. Five new API functions have been defined: - `mbedtls_ccm_starts()`, `mbedtls_ccm_set_lengths()`, - `mbedtls_ccm_update_ad()`, `mbedtls_ccm_update()` and `mbedtls_ccm_finish()`. -Alternative implementations of CCM (`MBEDTLS_CCM_ALT`) have now to -implement those additional five API functions. - - -## X.509 - -### Remove the certs module from the library - -This should not affect production use of the library, as the certificates and -keys included there were never suitable for production use. - -However it might affect you if you relied on them for testing purposes. In -that case, please embed your own test certificates in your test code; now that -`certs.c` is out of the library there is no longer any stability guaranteed -and it may change in incompatible ways at any time. - -### Change the API to allow adding critical extensions to CSRs - -This affects applications that call the `mbedtls_x509write_csr_set_extension` -function. - -The API is changed to include the parameter `critical` which enables marking an -extension included in a CSR as critical. To get the previous behavior pass 0. - -### Remove the config option `MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION` - -This change does not affect users of the default configuration; it only affects -users who enable this option. - -The X.509 standard says that implementations must reject critical extensions that -they don't recognize, and this is what Mbed TLS does by default. This option -allowed to continue parsing those certificates but didn't provide a convenient -way to handle those extensions. - -The migration path from that option is to use the -`mbedtls_x509_crt_parse_der_with_ext_cb()` function which is functionally -equivalent to `mbedtls_x509_crt_parse_der()`, and/or -`mbedtls_x509_crt_parse_der_nocopy()` but it calls the callback with every -unsupported certificate extension and additionally the "certificate policies" -extension if it contains any unsupported certificate policies. - -### Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h` - -This change affects users who have chosen the configuration options to disable the -library's verification of the `keyUsage` and `extendedKeyUsage` fields of X.509 -certificates. - -The `MBEDTLS_X509_CHECK_KEY_USAGE` and `MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE` -configuration options are removed and the X.509 code now behaves as if they were -always enabled. It is consequently not possible anymore to disable at compile -time the verification of the `keyUsage` and `extendedKeyUsage` fields of X.509 -certificates. - -The verification of the `keyUsage` and `extendedKeyUsage` fields is important, -disabling it can cause security issues and it is thus not recommended. If the -verification is for some reason undesirable, it can still be disabled by means -of the verification callback function passed to `mbedtls_x509_crt_verify()` (see -the documentation of this function for more information). - -### Remove the `MBEDTLS_X509_ALLOW_EXTENSIONS_NON_V3` option - -This change does not affect users who were using the default configuration, as -this option was already disabled by default. Also, it does not affect users who -are working with current V3 X.509 certificates. - -Extensions were added in V3 of the X.509 specification, so pre-V3 certificates -containing extensions were never compliant. Mbed TLS now rejects them with a -parsing error in all configurations, as it did previously in the default -configuration. - -If you are working with the pre-V3 certificates you need to switch to the -current ones. - -### Strengthen default algorithm selection for X.509 - -This is described in the section [Strengthen default algorithm selection for X.509 and TLS](#strengthen-default-algorithm-selection-for-x.509-and-tls). - -### Remove wrapper for libpkcs11-helper - -This doesn't affect people using the default configuration as it was already -disabled by default. - -If you used to rely on this module in order to store your private keys -securely, please have a look at the key management facilities provided by the -PSA crypto API. If you have a use case that's not covered yet by this API, -please reach out on the mailing list. - - -## SSL - -### Remove support for TLS 1.0, 1.1 and DTLS 1.0 - -This change affects users of the TLS 1.0, 1.1 and DTLS 1.0 protocols. - -These versions have been deprecated by RFC 8996. -Keeping them in the library creates opportunities for misconfiguration -and possibly downgrade attacks. More generally, more code means a larger attack -surface, even if the code is supposedly not used. - -The migration path is to adopt the latest versions of the protocol. - -As a consequence of removing TLS 1.0, support for CBC record splitting was -also removed, as it was a work-around for a weakness in this particular -version. There is no migration path since the feature is no longer relevant. - -As a consequence of currently supporting only one version of (D)TLS (and in the -future 1.3 which will have a different version negotiation mechanism), support -for fallback SCSV (RFC 7507) was also removed. There is no migration path as -it's no longer useful with TLS 1.2 and later. - -As a consequence of currently supporting only one version of (D)TLS (and in the -future 1.3 which will have a different concept of ciphersuites), support for -configuring ciphersuites separately for each version via -`mbedtls_ssl_conf_ciphersuites_for_version()` was removed. Use -`mbedtls_ssl_conf_ciphersuites()` to configure ciphersuites to use with (D)TLS -1.2; in the future a different API will be added for (D)TLS 1.3. - -### Remove support for SSL 3.0 - -This doesn't affect people using the default configuration as it was already -disabled by default. - -This only affects TLS users who explicitly enabled `MBEDTLS_SSL_PROTO_SSL3` -and relied on that version in order to communicate with peers that are not up -to date. If one of your peers is in that case, please try contacting them and -encouraging them to upgrade their software. - -### Remove support for parsing SSLv2 ClientHello - -This doesn't affect people using the default configuration as it was already -disabled by default. - -This only affects TLS servers that have clients who send an SSLv2 ClientHello. -These days clients are very unlikely to do that. If you have a client that -does, please try contacting them and encouraging them to upgrade their -software. - -### Remove support for truncated HMAC - -This affects users of truncated HMAC, that is, users who called -`mbedtls_ssl_conf_truncated_hmac( ..., MBEDTLS_SSL_TRUNC_HMAC_ENABLED)`, -regardless of whether the standard version was used or compatibility version -(`MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT`). - -The recommended migration path for people who want minimal overhead is to use a -CCM-8 ciphersuite. - -### Remove support for TLS record-level compression - -This doesn't affect people using the default configuration as it was already -disabled by default. - -This only affects TLS users who enabled `MBEDTLS_ZLIB_SUPPORT`. This will not -cause any failures however if you used to enable TLS record-level compression -you may find that your bandwidth usage increases without compression. There's -no general solution to this problem; application protocols might have their -own compression mechanisms and are in a better position than the TLS stack to -avoid variants of the CRIME and BREACH attacks. - -### Remove support for TLS RC4-based ciphersuites - -This does not affect people who used the default `mbedtls_config.h` and the default -list of ciphersuites, as RC4-based ciphersuites were already not negotiated in -that case. - -Please switch to any of the modern, recommended ciphersuites (based on -AES-GCM, AES-CCM or ChachaPoly for example) and if your peer doesn't support -any, encourage them to upgrade their software. - -### Remove support for TLS single-DES ciphersuites - -This doesn't affect people using the default configuration as it was already -disabled by default. - -Please switch to any of the modern, recommended ciphersuites (based on -AES-GCM, AES-CCM or ChachaPoly for example) and if your peer doesn't support -any, encourage them to upgrade their software. - -### Remove support for TLS record-level hardware acceleration - -This doesn't affect people using the default configuration as it was already -disabled by default. - -This feature had been broken for a while so we doubt anyone still used it. -However if you did, please reach out on the mailing list and let us know about -your use case. - -### Remove config option `MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME` - -This doesn't affect people using the default configuration. - -This option has not had any effect for a long time. Please use the `lifetime` -parameter of `mbedtls_ssl_ticket_setup()` instead. - -### Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options - -This change affects users who modified the default `mbedtls_config.h` padding granularity -settings, i.e. enabled at least one of the options. - -The `mbedtls_config.h` options `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and -`MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` were combined into one option because -they used exactly the same padding mechanism and hence their respective padding -granularities can be used in exactly the same way. This change simplifies the -code maintenance. - -The new single option `MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY` can be used -for both DTLS-CID and TLS 1.3. - -### TLS now favors faster curves over larger curves - -The default preference order for curves in TLS now favors resource usage (performance and memory consumption) over size. The exact order is unspecified and may change, but generally you can expect 256-bit curves to be preferred over larger curves. - -If you prefer a different order, call `mbedtls_ssl_conf_groups()` when configuring a TLS connection. - -### SSL key export interface change - -This affects users of the SSL key export APIs: -``` - mbedtls_ssl_conf_export_keys_cb() - mbedtls_ssl_conf_export_keys_ext_cb() -``` - -Those APIs have been removed and replaced by the new API -`mbedtls_ssl_set_export_keys_cb()`. This API differs from -the previous key export API in the following ways: - -- It is no longer bound to an SSL configuration, but to an - SSL context. This allows users to more easily identify the - connection an exported key belongs to. -- It no longer exports raw keys and IV. -- A secret type parameter has been added to identify which key - is being exported. For TLS 1.2, only the master secret is - exported, but upcoming TLS 1.3 support will add other kinds of keys. -- The callback now specifies a void return type, rather than - returning an error code. It is the responsibility of the application - to handle failures in the key export callback, for example by - shutting down the TLS connection. - -For users which do not rely on raw keys and IV, adjusting to the new -callback type should be straightforward — see the example programs -`programs/ssl/ssl_client2` and `programs/ssl/ssl_server2` for callbacks -for NSSKeylog, EAP-TLS and DTLS-SRTP. - -Users which require access to the raw keys used to secure application -traffic may derive those by hand based on the master secret and the -handshake transcript hashes which can be obtained from the raw data -on the wire. Such users are also encouraged to reach out to the -Mbed TLS team on the mailing list, to let the team know about their -use case. - -### Remove MaximumFragmentLength (MFL) query API - -This affects users which use the MFL query APIs -`mbedtls_ssl_get_{input,output}_max_frag_len()` to -infer upper bounds on the plaintext size of incoming and -outgoing record. - -Users should switch to `mbedtls_ssl_get_max_{in,out}_record_payload()` -instead, which also provides such upper bounds but takes more factors -than just the MFL configuration into account. - -### Relaxed semantics for PSK configuration - -This affects users which call the PSK configuration APIs -`mbedtls_ssl_conf_psk()` and `mbedtls_ssl_conf_psk_opaque()` -multiple times on the same SSL configuration. - -In Mbed TLS 2.x, users would observe later calls overwriting -the effect of earlier calls, with the prevailing PSK being -the one that has been configured last. In Mbed TLS 3.0, -calling `mbedtls_ssl_conf_psk[_opaque]()` multiple times -will return an error, leaving the first PSK intact. - -To achieve equivalent functionality when migrating to Mbed TLS 3.0, -users calling `mbedtls_ssl_conf_psk[_opaque]()` multiple times should -remove all but the last call, so that only one call to _either_ -`mbedtls_ssl_conf_psk()` _or_ `mbedtls_ssl_conf_psk_opaque()` -remains. - -### Remove the configuration to enable weak ciphersuites in SSL / TLS - -This does not affect users who use the default `mbedtls_config.h`, as this option was -already off by default. - -If you were using a weak cipher, please switch to any of the modern, -recommended ciphersuites (based on AES-GCM, AES-CCM or ChachaPoly for example) -and if your peer doesn't support any, encourage them to upgrade their software. - -If you were using a ciphersuite without encryption, you just have to -enable `MBEDTLS_CIPHER_NULL_CIPHER` now. - -### Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option - -This affects users who use the `MBEDTLS_SSL_MAX_CONTENT_LEN` option to -set the maximum length of incoming and outgoing plaintext fragments, -which can save memory by reducing the size of the TLS I/O buffers. - -This option is replaced by the more fine-grained options -`MBEDTLS_SSL_IN_CONTENT_LEN` and `MBEDTLS_SSL_OUT_CONTENT_LEN` that set -the maximum incoming and outgoing plaintext fragment lengths, respectively. - -### Remove the SSL API `mbedtls_ssl_get_session_pointer()` - -This affects two classes of users: - -1. Users who manually inspect parts of the current session through - direct structure field access. - -2. Users of session resumption who query the current session - via `mbedtls_ssl_get_session_pointer()` prior to saving or exporting - it via `mbedtls_ssl_session_copy()` or `mbedtls_ssl_session_save()`, - respectively. - -Migration paths: - -1. Mbed TLS 3.0 does not offer a migration path for the use case 1: Like many - other Mbed TLS structures, the structure of `mbedtls_ssl_session` is no - longer part of the public API in Mbed TLS 3.0, and direct structure field - access is no longer supported. Please see the [section on private structure fields](#most-structure-fields-are-now-private) for more details. - -2. Users should replace calls to `mbedtls_ssl_get_session_pointer()` by - calls to `mbedtls_ssl_get_session()` as demonstrated in the example - program `programs/ssl/ssl_client2.c`. - -### Remove `MBEDTLS_SSL_DTLS_BADMAC_LIMIT` option - -This change does not affect users who used the default `mbedtls_config.h`, as the option -`MBEDTLS_SSL_DTLS_BADMAC_LIMIT` was already on by default. - -This option was a trade-off between functionality and code size: it allowed -users who didn't need that feature to avoid paying the cost in code size, by -disabling it. - -This option is no longer present, but its functionality is now always enabled. - -### Deprecated functions were removed from SSL - -The function `mbedtls_ssl_conf_dh_param()` was removed. Please use -`mbedtls_ssl_conf_dh_param_bin()` or `mbedtls_ssl_conf_dh_param_ctx()` instead. - -The function `mbedtls_ssl_get_max_frag_len()` was removed. Please use -`mbedtls_ssl_get_max_out_record_payload()` and -`mbedtls_ssl_get_max_in_record_payload()` -instead. - -### Remove `MBEDTLS_SSL_RECORD_CHECKING` option and enable its action by default - -This change does not affect users who use the default `mbedtls_config.h`, as the -option `MBEDTLS_SSL_RECORD_CHECKING` was already on by default. - -This option was added only to control compilation of one function, - `mbedtls_ssl_check_record()`, which is only useful in some specific cases, so it -was made optional to allow users who don't need it to save some code space. -However, the same effect can be achieved by using link-time garbage collection. - -Users who changed the default setting of the option need to change the config/ -build system to remove that change. - -### Session Cache API Change - -This affects users who use `mbedtls_ssl_conf_session_cache()` -to configure a custom session cache implementation different -from the one Mbed TLS implements in `library/ssl_cache.c`. - -Those users will need to modify the API of their session cache -implementation to that of a key-value store with keys being -session IDs and values being instances of `mbedtls_ssl_session`: - -```C -typedef int mbedtls_ssl_cache_get_t( void *data, - unsigned char const *session_id, - size_t session_id_len, - mbedtls_ssl_session *session ); -typedef int mbedtls_ssl_cache_set_t( void *data, - unsigned char const *session_id, - size_t session_id_len, - const mbedtls_ssl_session *session ); -``` - -Since the structure of `mbedtls_ssl_session` is no longer public from 3.0 -onwards, portable session cache implementations must not access fields of -`mbedtls_ssl_session`. See the corresponding migration guide. Users that -find themselves unable to migrate their session cache functionality without -accessing fields of `mbedtls_ssl_session` should describe their use case -on the Mbed TLS mailing list. - -### Changes in the SSL error code space - -This affects users manually checking for the following error codes: - -- `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` -- `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` -- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` -- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` -- `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` -- `MBEDTLS_ERR_SSL_BAD_HS_XXX` - -Migration paths: -- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and - `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` is returned instead if the user's own certificate - is too large to fit into the output buffers. - - Users should check for `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially - compare the size of their own certificate against the configured size of the output buffer to - understand if the error is due to an overly large certificate. - -- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` and `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` have been - replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`. - -- All codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives, which give more information about the type of error raised. - - Users should check for the newly introduced generic error codes - - * `MBEDTLS_ERR_SSL_DECODE_ERROR` - * `MBEDTLS_ERR_SSL_ILLEGAL_PARAMETER`, - * `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE` - * `MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION` - * `MBEDTLS_ERR_SSL_BAD_CERTIFICATE` - * `MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME` - * `MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION` - * `MBEDTLS_ERR_SSL_NO_APPLICATION_PROTOCOL` - - and the pre-existing generic error codes - - * `MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE` - * `MBEDTLS_ERR_SSL_INTERNAL_ERROR` - - instead. - -### Modified semantics of `mbedtls_ssl_{get,set}_session()` - -This affects users who call `mbedtls_ssl_get_session()` or -`mbedtls_ssl_set_session()` multiple times on the same SSL context -representing an established TLS 1.2 connection. -Those users will now observe the second call to fail with -`MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`. - -Migration path: -- Exporting the same TLS 1.2 connection multiple times via - `mbedtls_ssl_get_session()` leads to multiple copies of - the same session. This use of `mbedtls_ssl_get_session()` - is discouraged, and the following should be considered: - * If the various session copies are later loaded into - fresh SSL contexts via `mbedtls_ssl_set_session()`, - export via `mbedtls_ssl_get_session()` only once and - load the same session into different contexts via - `mbedtls_ssl_set_session()`. Since `mbedtls_ssl_set_session()` - makes a copy of the session that's being loaded, this - is functionally equivalent. - * If the various session copies are later serialized - via `mbedtls_ssl_session_save()`, export and serialize - the session only once via `mbedtls_ssl_get_session()` and - `mbedtls_ssl_session_save()` and make copies of the raw - data instead. -- Calling `mbedtls_ssl_set_session()` multiple times in Mbed TLS 2.x - is not useful since subsequent calls overwrite the effect of previous - calls. Applications achieve equivalent functional behavior by - issuing only the very last call to `mbedtls_ssl_set_session()`. - -### Turn `MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE` configuration option into a runtime option - -This change affects users who were enabling `MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE` -option in the `mbedtls_config.h` - -This option has been removed and a new function with similar functionality has -been introduced into the SSL API. - -This new function `mbedtls_ssl_conf_preference_order()` can be used to -change the preferred order of ciphersuites on the server to those used on the client, -e.g.: `mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT)` -has the same effect as enabling the removed option. The default state is to use -the server order of suites. - -### Strengthen default algorithm selection for X.509 and TLS - -The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection in TLS have changed. They are now aligned, except that the X.509 profile only lists curves that support signature verification. - -Hashes and curves weaker than 255 bits (security strength less than 128 bits) are no longer accepted by default. The following hashes have been removed: SHA-1 (formerly only accepted for key exchanges but not for certificate signatures), SHA-224 (weaker hashes were already not accepted). The following curves have been removed: secp192r1, secp224r1, secp192k1, secp224k1. - -The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available. - -The curve secp256k1 has also been removed from the default X.509 and TLS profiles. [RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422#section-5.1.1) deprecates it in TLS, and it is very rarely used, although it is not known to be weak at the time of writing. - -If you still need to accept certificates signed with algorithms that have been removed from the default profile, call `mbedtls_x509_crt_verify_with_profile` instead of `mbedtls_x509_crt_verify` and pass a profile that allows the curves and hashes you want. For example, to allow SHA-224: -```C -mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; -my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); -``` - -If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_groups()` with the desired lists. - -### Remove 3DES ciphersuites - -This change does not affect users using default settings for 3DES in `mbedtls_config.h` -because the 3DES ciphersuites were disabled by that. - -3DES has weaknesses/limitations and there are better alternatives, and more and -more standard bodies are recommending against its use in TLS. - -The migration path here is to chose from the alternatives recommended in the -literature, such as AES. From e79923c65de283ddf4a871b2d1f8f346ebdf3a39 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 10 Oct 2025 15:50:20 +0200 Subject: [PATCH 36/47] Consolidate migration guide chapters into a single file Signed-off-by: Gilles Peskine --- docs/4.0-migration-guide.md | 599 ++++++++++++++++++ docs/4.0-migration-guide/configuration.md | 44 -- .../deprecated-removals.md | 14 - docs/4.0-migration-guide/error-codes.md | 37 -- docs/4.0-migration-guide/feature-removals.md | 152 ----- .../function-prototype-changes.md | 89 --- docs/4.0-migration-guide/oid.md | 7 - docs/4.0-migration-guide/private-decls.md | 33 - docs/4.0-migration-guide/psa-only.md | 23 - docs/4.0-migration-guide/repo-split.md | 200 ------ 10 files changed, 599 insertions(+), 599 deletions(-) create mode 100644 docs/4.0-migration-guide.md delete mode 100644 docs/4.0-migration-guide/configuration.md delete mode 100644 docs/4.0-migration-guide/deprecated-removals.md delete mode 100644 docs/4.0-migration-guide/error-codes.md delete mode 100644 docs/4.0-migration-guide/feature-removals.md delete mode 100644 docs/4.0-migration-guide/function-prototype-changes.md delete mode 100644 docs/4.0-migration-guide/oid.md delete mode 100644 docs/4.0-migration-guide/private-decls.md delete mode 100644 docs/4.0-migration-guide/psa-only.md delete mode 100644 docs/4.0-migration-guide/repo-split.md diff --git a/docs/4.0-migration-guide.md b/docs/4.0-migration-guide.md new file mode 100644 index 0000000000..83ec90ca92 --- /dev/null +++ b/docs/4.0-migration-guide.md @@ -0,0 +1,599 @@ +## CMake as the only build system +Mbed TLS now uses CMake exclusively to configure and drive its build process. +Support for the GNU Make and Microsoft Visual Studio project-based build systems has been removed. + +The previous `.sln` and `.vcxproj` files are no longer distributed or generated. + +See the `Compiling` section in README.md for instructions on building the Mbed TLS libraries and tests with CMake. +If you develop in Microsoft Visual Studio, you could either generate a Visual Studio solution using a CMake generator, or open the CMake project directly in Visual Studio. + +### Translating Make commands to CMake + +With the removal of GNU Make support, all build, test, and installation operations must now be performed using CMake. +This section provides a quick reference for translating common `make` commands into their CMake equivalents. + +#### Basic build workflow + +Run `cmake -S . -B build` once before building to configure the build and generate native build files (e.g., Makefiles) in the `build` directory. +This sets up an out-of-tree build, which is recommended. + +| Make command | CMake equivalent | Description | +|----------------|------------------------------------------------|--------------------------------------------------------------------| +| `make` | `cmake --build build` | Build the libraries, programs, and tests in the `build` directory. | +| `make test` | `ctest --test-dir build` | Run the tests produced by the previous build. | +| `make clean` | `cmake --build build --target clean` | Remove build artifacts produced by the previous build. | +| `make install` | `cmake --install build --prefix build/install` | Install the built libraries, headers, and tests to `build/install`. | + +#### Building specific targets + +Unless otherwise specified, the CMake command in the table below should be preceded by a `cmake -S . -B build` call to configure the build and generate build files in the `build` directory. + +| Make command | CMake equivalent | Description | +|-----------------|---------------------------------------------------------------------|---------------------------| +| `make lib` | `cmake --build build --target lib` | Build only the libraries. | +| `make tests` | `cmake -S . -B build -DENABLE_PROGRAMS=Off && cmake --build build` | Build test suites. | +| `make programs` | `cmake --build build --target programs` | Build example programs. | +| `make apidoc` | `cmake --build build --target mbedtls-apidoc` | Build documentation. | + +Target names may differ slightly; use `cmake --build build --target help` to list all available CMake targets. + +There is no CMake equivalent for `make generated_files` or `make neat`. +Generated files are automatically created in the build tree with `cmake --build build` and removed with `cmake --build build --target clean`. +If you need to build the generated files in the source tree without involving CMake, you can call `framework/scripts/make_generated_files.py`. + +There is currently no equivalent for `make uninstall` in the Mbed TLS CMake build system. + +#### Common build options + +The following table illustrates the approximate CMake equivalents of common make commands. +Most CMake examples show only the configuration step, others (like installation) correspond to different stages of the build process. + +| Make usage | CMake usage | Description | +|----------------------------|-------------------------------------------------------|----------------------| +| `make DEBUG=1` | `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug` | Build in debug mode. | +| `make SHARED=1` | `cmake -S . -B build -DUSE_SHARED_MBEDTLS_LIBRARY=On` | Also build shared libraries. | +| `make GEN_FILES=""` | `cmake -S . -B build -DGEN_FILES=OFF` | Skip generating files (not a strict equivalent). | +| `make DESTDIR=install_dir` | `cmake --install build --prefix install_dir` | Specify installation path. | +| `make CC=clang` | `cmake -S . -B build -DCMAKE_C_COMPILER=clang` | Set the compiler. | +| `make CFLAGS='-O2 -Wall'` | `cmake -S . -B build -DCMAKE_C_FLAGS="-O2 -Wall"` | Set compiler flags. | + +## Repository split +In Mbed TLS 4.0, the project was split into two repositories: +- [Mbed TLS](https://github.com/Mbed-TLS/mbedtls): provides TLS and X.509 functionality. +- [TF-PSA-Crypto](https://github.com/Mbed-TLS/TF-PSA-Crypto): provides the standalone cryptography library, implementing the PSA Cryptography API. +Mbed TLS consumes TF-PSA-Crypto as a submodule. +You should stay with Mbed TLS if you use TLS or X.509 functionality. You still have direct access to the cryptography library. + +### File and directory relocations + +The following table summarizes the file and directory relocations resulting from the repository split between Mbed TLS and TF-PSA-Crypto. +These changes reflect the move of cryptographic, cryptographic-adjacent, and platform components from Mbed TLS into the new TF-PSA-Crypto repository. + +| Original location | New location(s) | Notes | +|-----------------------------------------|--------------------------------------------------------------------------------------|-------| +| `library/*` (†) | `tf-psa-crypto/core/`
`tf-psa-crypto/drivers/builtin/src/` | Contains cryptographic, cryptographic-adjacent (e.g., ASN.1, Base64), and platform C modules and headers. | +| `include/mbedtls/*` (†) | `tf-psa-crypto/include/mbedtls/`
`tf-psa-crypto/drivers/builtin/include/private/` | Public headers moved to `include/mbedtls`; now internal headers moved to `include/private`. | +| `include/psa` | `tf-psa-crypto/include/psa` | All PSA headers consolidated here. | +| `3rdparty/everest`
`3rdparty/p256-m` | `tf-psa-crypto/drivers/everest`
`tf-psa-crypto/drivers/p256-m` | Third-party crypto driver implementations. | + +(†) The `library` and `include/mbedtls` directories still exist in Mbed TLS, but now contain only TLS and X.509 components. + +### Configuration file split +Cryptography and platform configuration options have been moved from `include/mbedtls/mbedtls_config.h` to `tf-psa-crypto/include/psa/crypto_config.h`, which is now mandatory. +See [Compile-time configuration](#compile-time-configuration). + +The header `include/mbedtls/mbedtls_config.h` still exists and now contains only the TLS and X.509 configuration options. + +If you use the Python script `scripts/config.py` to adjust your configuration, you do not need to modify your scripts to specify which configuration file to edit, the script automatically updates the correct file. + +There have been significant changes in the configuration options, primarily affecting cryptography. + +#### Cryptography configuration +- See [psa-transition.md](https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/psa-transition.md#compile-time-configuration). +- See also the following sections in the TF-PSA-Crypto 1.0 migration guide: + - *PSA as the Only Cryptography API* and its sub-section *Impact on the Library Configuration* + - *Random Number Generation Configuration* + +#### TLS configuration +For details about TLS-related changes, see [Changes to TLS options](#changes-to-tls-options). + +### Impact on some usages of the library + +#### Checking out a branch or a tag +After checking out a branch or tag of the Mbed TLS repository, you must now recursively update the submodules, as TF-PSA-Crypto contains itself a nested submodule: +``` +git submodule update --init --recursive +``` + +#### Linking directly to a built library + +The Mbed TLS CMake build system still provides the cryptography libraries under their legacy name, `libmbedcrypto.`, so you can continue linking against them. +These libraries are still located in the `library` directory within the build tree. + +The cryptography libraries are also now provided as `libtfpsacrypto.`, consistent with the naming used in the TF-PSA-Crypto repository. + +You may need to update include paths to the public header files, see [File and Directory Relocations](#file-and-directory-relocations) for details. + +#### Using Mbed TLS as a CMake subproject + +The base name of the libraries are now `tfpsacrypto` (formely `mbedcrypto`), `mbedx509` and `mbedtls`. +As before, these base names are also the names of CMake targets to build each library. +If your CMake scripts reference a cryptography library target, you need to update its name accordingly. + +For example, the following CMake code: +``` +target_link_libraries(mytarget PRIVATE mbedcrypto) +``` +should be updated to: +``` +target_link_libraries(mytarget PRIVATE tfpsacrypto) +``` + +You can refer to the following example demonstrating how to consume Mbed TLS as a CMake subproject: +- `programs/test/cmake_subproject` + +#### Using Mbed TLS as a CMake package + +The same renaming applies to the cryptography library targets declared as part of the Mbed TLS CMake package, use `MbedTLS::tfpsacrypto` instead of `MbedTLS::mbedcrypto`. + +For example, the following CMake code: +``` +find_package(MbedTLS REQUIRED) +target_link_libraries(myapp PRIVATE MbedTLS::mbedcrypto) +``` +should be updated to: +``` +find_package(MbedTLS REQUIRED) +target_link_libraries(myapp PRIVATE MbedTLS::tfpsacrypto) +``` +You can also refer to the following example programs demonstrating how to consume Mbed TLS as a CMake package: +- `programs/test/cmake_package` +- `programs/test/cmake_package_install` + +#### Using the Mbed TLS Crypto pkg-config file + +The Mbed TLS CMake build system still provides the pkg-config file mbedcrypto.pc, so you can continue using it. +Internally, it now references the tfpsacrypto library. + +A new pkg-config file, `tfpsacrypto.pc`, is also provided. +Both `mbedcrypto.pc` and `tfpsacrypto.pc` are functionally equivalent, providing the same compiler and linker flags. + +#### Using Mbed TLS as an installed library + +The Mbed TLS CMake build system still installs the cryptography libraries under their legacy name, `libmbedcrypto.`, so you can continue linking against them. +The cryptography library is also now provided as `libtfpsacrypto.`. + +Regarding the headers, the main change is the relocation of some headers to subdirectories called `private`. +These headers are installed primarily to satisfy compiler dependencies. +Others remain for historical reasons and may be cleaned up in later versions of the library. + +We strongly recommend not relying on the declarations in these headers, as they may be removed or modified without notice. +See the section Private Declarations in the TF-PSA-Crypto 1.0 migration guide for more information. + +Finally, note the new `include/tf-psa-crypto` directory, which contains the TF-PSA-Crypto version and build-time configuration headers. + +### Audience-Specific Notes + +#### Application Developers using a distribution package +- See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on: + - Linking against the cryptography library or CMake targets. + - Using the Mbed TLS Crypto pkg-config file. + - Using Mbed TLS as an installed library + +### Developer or package maintainers +If you build or distribute Mbed TLS: +- The build system is now CMake only, Makefiles and Visual Studio projects are removed. +- You may need to adapt packaging scripts to handle the TF-PSA-Crypto submodule. +- You should update submodules recursively after checkout. +- Review [File and directory relocations](#file-and-directory-relocations) for updated paths. +- See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on: + - Linking against the cryptography library or CMake targets. + - Using the Mbed TLS Crypto pkg-config file (`mbedcrypto.pc` or `tfpsacrypto.pc`). + - Using Mbed TLS as an installed library +- Configuration note: cryptography and platform options are now in `crypto_config.h` (see [Configuration file split](#configuration-file-split)). + +### Platform Integrators +If you integrate Mbed TLS with a platform or hardware drivers: +- TF-PSA-Crypto is now a submodule, update integration scripts to initialize submodules recursively. +- The PSA driver wrapper is now generated in TF-PSA-Crypto. +- Platform-specific configuration are now handled in `crypto_config.h`. +- See [Repository split](#repository-split) for how platform components moved to TF-PSA-Crypto. +## Compile-time configuration + +### Configuration file split + +All configuration options that are relevant to TF-PSA-Crypto must now be configured in one of its configuration files, namely: + +* `TF_PSA_CRYPTO_CONFIG_FILE`, if set on the preprocessor command line; +* otherwise ``; +* additionally `TF_PSA_CRYPTO_USER_CONFIG_FILE`, if set. + +Configuration options that are relevant to X.509 or TLS should still be set in the Mbed TLS configuration file (`MBEDTLS_CONFIG_FILE` or ``, plus `MBEDTLS_USER_CONFIG_FILE` if it is set). However, you can define all options in the crypto configuration, and Mbed TLS will pick them up. + +Generally speaking, the options that must be configured in TF-PSA-Crypto are: + +* options related to platform settings; +* options related to the choice of cryptographic mechanisms included in the build; +* options related to the inner workings of cryptographic mechanisms, such as size/memory/performance compromises; +* options related to crypto-adjacent features, such as ASN.1 and Base64. + +See `include/psa/crypto_config.h` in TF-PSA-Crypto and `include/mbedtls/mbedtls_config.h` in Mbed TLS for details. + +Notably, `` is no longer limited to `PSA_WANT_xxx` options. + +Note that many options related to cryptography have changed; see the TF-PSA-Crypto migration guide for details. + +### Split of `build_info.h` and `version.h` + +The header file ``, which includes the configuration file and provides the adjusted configuration macros, now has an similar file `` in TF-PSA-Crypto. The Mbed TLS header includes the TF-PSA-Crypto header, so including `` remains sufficient to obtain information about the crypto configuration. + +TF-PSA-Crypto exposes its version through ``, similar to `` in Mbed TLS. + +### Removal of `check_config.h` + +The header `mbedtls/check_config.h` is no longer present. Including it from user configuration files was already obsolete in Mbed TLS 3.x, since it enforces properties the configuration as adjusted by `mbedtls/build_info.h`, not properties that the user configuration is expected to meet. + +### Changes to TLS options + +#### Enabling null cipher suites + +The option to enable null cipher suites in TLS 1.2 has been renamed from `MBEDTLS_CIPHER_NULL_CIPHER` to `MBEDTLS_SSL_NULL_CIPHERSUITES`. It remains disabled in the default configuration. + +#### Removal of backward compatibility options + +The option `MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT` has been removed. Only the version standardized in RFC 9146 is supported now. +## PSA as the only cryptography API + +The PSA API is now the only API for cryptographic primitives. + +### Impact on application code + +The X.509, PKCS7 and SSL modules always use PSA for cryptography, with a few exceptions documented in the [PSA limitations](../architecture/psa-migration/psa-limitations.md) document. (These limitations are mostly transparent unless you want to leverage PSA accelerator drivers.) This corresponds to the behavior of Mbed TLS 3.x when `MBEDTLS_USE_PSA_CRYPTO` is enabled. In effect, `MBEDTLS_USE_PSA_CRYPTO` is now always enabled. + +`psa_crypto_init()` must be called before performing any cryptographic operation, including indirect requests such as parsing a key or certificate or starting a TLS handshake. + +A few functions take different parameters to migrate them to the PSA API. See “[Function prototype changes](#function-prototype-changes)”. + +### No random generator instantiation + +Formerly, applications using TLS, asymmetric cryptography operations involving a private key, or other features needing random numbers, needed to provide a random generator, generally by instantiating an entropy context (`mbedtls_entropy_context`) and a DRBG context (`mbedtls_ctr_drbg_context` or `mbedtls_hmac_drbg_context`). This is no longer necessary, or possible. All features that require a random generator (RNG) now use the one provided by the PSA subsystem. + +Instead, applications that use random generators or keys (even public keys) need to call `psa_crypto_init()` before any cryptographic operation or key management operation. + +See also [function prototype changes](#function-prototype-changes), many of which are related to the move from RNG callbacks to a global RNG. + +### Impact on the library configuration + +Mbed TLS follows the configuration of TF-PSA-Crypto with respect to cryptographic mechanisms. They are now based on `PSA_WANT_xxx` macros instead of legacy configuration macros such as `MBEDTLS_RSA_C`, `MBEDTLS_PKCS1_V15`, etc. The configuration of X.509 and TLS is not directly affected by the configuration. However, applications and middleware that rely on these configuration symbols to know which cryptographic mechanisms to support will need to migrate to `PSA_WANT_xxx` macros. For more information, consult the PSA transition guide in TF-PSA-Crypto. +## Private declarations + +Since Mbed TLS 3.0, some things that are declared in a public header are not part of the stable application programming interface (API), but instead are considered private. Private elements may be removed or may have their semantics changed in a future minor release without notice. + +### Understanding private declarations in public headers + +In Mbed TLS 4.x, private elements in header files include: + +* Anything appearing in a header file whose path contains `/private` (unless re-exported and documented in another non-private header). +* Structure and union fields declared with `MBEDTLS_PRIVATE(field_name)` in the source code, and appearing as `private_field_name` in the rendered documentation. (This was already the case since Mbed TLS 3.0.) +* Any preprocessor macro that is not documented with a Doxygen comment. + In the source code, Doxygen comments start with `/**` or `/*!`. If a macro only has a comment above that starts with `/*`, the macro is considered private. + In the rendered documentation, private macros appear with only an automatically rendered parameter list, value and location, but no custom text. +* Any declaration that is guarded by the preprocessor macro `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS`. + +### Usage of private declarations + +Some private declarations are present in public headers for technical reasons, because they need to be visible to the compiler. Others are present for historical reasons and may be cleaned up in later versions of the library. We strongly recommend against relying on these declarations, since they may be removed or may have their semantics changed without notice. + +Note that Mbed TLS 4.0 still relies on some private interfaces of TF-PSA-Crypto 1.0. We expect to remove this reliance gradually in future minor releases. + +Sample programs have not been fully updated yet and some of them might still +use APIs that are no longer public. You can recognize them by the fact that they +define the macro `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS` (or +`MBEDTLS_ALLOW_PRIVATE_ACCESS`) at the very top (before including headers). When +you see one of these two macros in a sample program, be aware it has not been +updated and parts of it do not demonstrate current practice. + +We strongly recommend against defining `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS` or +`MBEDTLS_ALLOW_PRIVATE_ACCESS` in your own application. If you do so, your code +may not compile or work with future minor releases. If there's something you +want to do that you feel can only be achieved by using one of these two macros, +please reach out on github or the mailing list. +## Error codes + +### Unified error code space + +The convention still applies that functions return 0 for success and a negative value between -32767 and -1 on error. PSA functions (`psa_xxx()` or `mbedtls_psa_xxx()`) still return a `PSA_ERROR_xxx` error codes. Non-PSA functions (`mbedtls_xxx()` excluding `mbedtls_psa_xxx()`) can return either `PSA_ERROR_xxx` or `MBEDTLS_ERR_xxx` error codes. + +There may be cases where an `MBEDTLS_ERR_xxx` constant has the same numerical value as a `PSA_ERROR_xxx`. In such cases, they have the same meaning: they are different names for the same error condition. + +### Simplified legacy error codes + +All values returned by a function to indicate an error now have a defined constant named `MBEDTLS_ERR_xxx` or `PSA_ERROR_xxx`. Functions no longer return the sum of a “low-level” and a “high-level” error code. + +Generally, functions that used to return the sum of two error codes now return the low-level code. However, as before, the exact error code returned in a given scenario can change without notice unless the condition is specifically described in the function's documentation and no other condition is applicable. + +As a consequence, the functions `mbedtls_low_level_strerr()` and `mbedtls_high_level_strerr()` no longer exist. + +### Removed error code names + +Many legacy error codes have been removed in favor of PSA error codes. Generally, functions that returned a legacy error code in the table below in Mbed TLS 3.6 now return the PSA error code listed on the same row. Similarly, callbacks should apply the same changes to error code, unless there has been a relevant change to the callback's interface. + +| Legacy constant (Mbed TLS 3.6) | PSA constant (Mbed TLS 4.0) | +|-----------------------------------------|---------------------------------| +| `MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED` | `PSA_ERROR_CORRUPTION_DETECTED` | +| `MBEDTLS_ERR_ERROR_GENERIC_ERROR` | `PSA_ERROR_GENERIC_ERROR` | +| `MBEDTLS_ERR_NET_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` | +| `MBEDTLS_ERR_OID_BUF_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` | +| `MBEDTLS_ERR_OID_NOT_FOUND` | `PSA_ERROR_NOT_SUPPORTED` | +| `MBEDTLS_ERR_PKCS7_ALLOC_FAILED` | `PSA_ERROR_INSUFFICIENT_MEMORY` | +| `MBEDTLS_ERR_PKCS7_BAD_INPUT_DATA` | `PSA_ERROR_INVALID_ARGUMENT` | +| `MBEDTLS_ERR_PKCS7_VERIFY_FAIL` | `PSA_ERROR_INVALID_SIGNATURE` | +| `MBEDTLS_ERR_SSL_ALLOC_FAILED` | `PSA_ERROR_INSUFFICIENT_MEMORY` | +| `MBEDTLS_ERR_SSL_BAD_INPUT_DATA` | `PSA_ERROR_INVALID_ARGUMENT` | +| `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` | +| `MBEDTLS_ERR_X509_ALLOC_FAILED` | `PSA_ERROR_INSUFFICIENT_MEMORY` | +| `MBEDTLS_ERR_X509_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` | + +See also the corresponding section in the TF-PSA-Crypto migration guide, which lists error codes from cryptography modules. +## Removal of deprecated functions + +### Removal of deprecated X.509 functions + +The deprecated function `mbedtls_x509write_crt_set_serial()` has been removed. The function was superseded by `mbedtls_x509write_crt_set_serial_raw()`. + +### Removal of deprecated SSL functions + +The deprecated function `mbedtls_ssl_conf_curves()` has been removed. +The function was superseded by `mbedtls_ssl_conf_groups()`. + +### Removal of `compat-2.x.h` + +The header `compat-2.x.h`, containing some definitions for backward compatibility with Mbed TLS 2.x, has been removed. +## Removed features + +### Removal of obsolete key exchanges methods in (D)TLS 1.2 + +Mbed TLS 4.0 no longer supports key exchange methods that rely on finite-field Diffie-Hellman (DHE) in TLS 1.2 and DTLS 1.2. (Only ephemeral Diffie-Hellman was ever supported, Mbed TLS 3.x already did not support static Diffie-Hellman.) Finite-field Diffie-Hellman remains supported in TLS 1.3. + +Mbed TLS 4.0 no longer supports key exchange methods that rely on RSA decryption (without forward secrecy). RSA signatures remain supported. This affects TLS 1.2 and DTLS 1.2 (TLS 1.3 does not have key exchanges using RSA decryption). + +That is, the following key exchange types are no longer supported: + +* RSA-PSK; +* RSA (i.e. cipher suites using only RSA decryption: cipher suites using RSA signatures remain supported); +* DHE-PSK (except in TLS 1.3); +* DHE-RSA (except in TLS 1.3). +* static ECDH (ECDH-RSA and ECDH-ECDSA, as opposed to ephemeral ECDH (ECDHE) which remains supported). + +The full list of removed cipher suites is: + +``` +TLS-DHE-PSK-WITH-AES-128-CBC-SHA +TLS-DHE-PSK-WITH-AES-128-CBC-SHA256 +TLS-DHE-PSK-WITH-AES-128-CCM +TLS-DHE-PSK-WITH-AES-128-CCM-8 +TLS-DHE-PSK-WITH-AES-128-GCM-SHA256 +TLS-DHE-PSK-WITH-AES-256-CBC-SHA +TLS-DHE-PSK-WITH-AES-256-CBC-SHA384 +TLS-DHE-PSK-WITH-AES-256-CCM +TLS-DHE-PSK-WITH-AES-256-CCM-8 +TLS-DHE-PSK-WITH-AES-256-GCM-SHA384 +TLS-DHE-PSK-WITH-ARIA-128-CBC-SHA256 +TLS-DHE-PSK-WITH-ARIA-128-GCM-SHA256 +TLS-DHE-PSK-WITH-ARIA-256-CBC-SHA384 +TLS-DHE-PSK-WITH-ARIA-256-GCM-SHA384 +TLS-DHE-PSK-WITH-CAMELLIA-128-CBC-SHA256 +TLS-DHE-PSK-WITH-CAMELLIA-128-GCM-SHA256 +TLS-DHE-PSK-WITH-CAMELLIA-256-CBC-SHA384 +TLS-DHE-PSK-WITH-CAMELLIA-256-GCM-SHA384 +TLS-DHE-PSK-WITH-CHACHA20-POLY1305-SHA256 +TLS-DHE-PSK-WITH-NULL-SHA +TLS-DHE-PSK-WITH-NULL-SHA256 +TLS-DHE-PSK-WITH-NULL-SHA384 +TLS-DHE-RSA-WITH-AES-128-CBC-SHA +TLS-DHE-RSA-WITH-AES-128-CBC-SHA256 +TLS-DHE-RSA-WITH-AES-128-CCM +TLS-DHE-RSA-WITH-AES-128-CCM-8 +TLS-DHE-RSA-WITH-AES-128-GCM-SHA256 +TLS-DHE-RSA-WITH-AES-256-CBC-SHA +TLS-DHE-RSA-WITH-AES-256-CBC-SHA256 +TLS-DHE-RSA-WITH-AES-256-CCM +TLS-DHE-RSA-WITH-AES-256-CCM-8 +TLS-DHE-RSA-WITH-AES-256-GCM-SHA384 +TLS-DHE-RSA-WITH-ARIA-128-CBC-SHA256 +TLS-DHE-RSA-WITH-ARIA-128-GCM-SHA256 +TLS-DHE-RSA-WITH-ARIA-256-CBC-SHA384 +TLS-DHE-RSA-WITH-ARIA-256-GCM-SHA384 +TLS-DHE-RSA-WITH-CAMELLIA-128-CBC-SHA +TLS-DHE-RSA-WITH-CAMELLIA-128-CBC-SHA256 +TLS-DHE-RSA-WITH-CAMELLIA-128-GCM-SHA256 +TLS-DHE-RSA-WITH-CAMELLIA-256-CBC-SHA +TLS-DHE-RSA-WITH-CAMELLIA-256-CBC-SHA256 +TLS-DHE-RSA-WITH-CAMELLIA-256-GCM-SHA384 +TLS-DHE-RSA-WITH-CHACHA20-POLY1305-SHA256 +TLS-ECDH-ECDSA-WITH-AES-128-CBC-SHA +TLS-ECDH-ECDSA-WITH-AES-128-CBC-SHA256 +TLS-ECDH-ECDSA-WITH-AES-128-GCM-SHA256 +TLS-ECDH-ECDSA-WITH-AES-256-CBC-SHA +TLS-ECDH-ECDSA-WITH-AES-256-CBC-SHA384 +TLS-ECDH-ECDSA-WITH-AES-256-GCM-SHA384 +TLS-ECDH-ECDSA-WITH-ARIA-128-CBC-SHA256 +TLS-ECDH-ECDSA-WITH-ARIA-128-GCM-SHA256 +TLS-ECDH-ECDSA-WITH-ARIA-256-CBC-SHA384 +TLS-ECDH-ECDSA-WITH-ARIA-256-GCM-SHA384 +TLS-ECDH-ECDSA-WITH-CAMELLIA-128-CBC-SHA256 +TLS-ECDH-ECDSA-WITH-CAMELLIA-128-GCM-SHA256 +TLS-ECDH-ECDSA-WITH-CAMELLIA-256-CBC-SHA384 +TLS-ECDH-ECDSA-WITH-CAMELLIA-256-GCM-SHA384 +TLS-ECDH-ECDSA-WITH-NULL-SHA +TLS-ECDH-RSA-WITH-AES-128-CBC-SHA +TLS-ECDH-RSA-WITH-AES-128-CBC-SHA256 +TLS-ECDH-RSA-WITH-AES-128-GCM-SHA256 +TLS-ECDH-RSA-WITH-AES-256-CBC-SHA +TLS-ECDH-RSA-WITH-AES-256-CBC-SHA384 +TLS-ECDH-RSA-WITH-AES-256-GCM-SHA384 +TLS-ECDH-RSA-WITH-ARIA-128-CBC-SHA256 +TLS-ECDH-RSA-WITH-ARIA-128-GCM-SHA256 +TLS-ECDH-RSA-WITH-ARIA-256-CBC-SHA384 +TLS-ECDH-RSA-WITH-ARIA-256-GCM-SHA384 +TLS-ECDH-RSA-WITH-CAMELLIA-128-CBC-SHA256 +TLS-ECDH-RSA-WITH-CAMELLIA-128-GCM-SHA256 +TLS-ECDH-RSA-WITH-CAMELLIA-256-CBC-SHA384 +TLS-ECDH-RSA-WITH-CAMELLIA-256-GCM-SHA384 +TLS-ECDH-RSA-WITH-NULL-SHA +TLS-RSA-PSK-WITH-AES-128-CBC-SHA +TLS-RSA-PSK-WITH-AES-128-CBC-SHA256 +TLS-RSA-PSK-WITH-AES-128-GCM-SHA256 +TLS-RSA-PSK-WITH-AES-256-CBC-SHA +TLS-RSA-PSK-WITH-AES-256-CBC-SHA384 +TLS-RSA-PSK-WITH-AES-256-GCM-SHA384 +TLS-RSA-PSK-WITH-ARIA-128-CBC-SHA256 +TLS-RSA-PSK-WITH-ARIA-128-GCM-SHA256 +TLS-RSA-PSK-WITH-ARIA-256-CBC-SHA384 +TLS-RSA-PSK-WITH-ARIA-256-GCM-SHA384 +TLS-RSA-PSK-WITH-CAMELLIA-128-CBC-SHA256 +TLS-RSA-PSK-WITH-CAMELLIA-128-GCM-SHA256 +TLS-RSA-PSK-WITH-CAMELLIA-256-CBC-SHA384 +TLS-RSA-PSK-WITH-CAMELLIA-256-GCM-SHA384 +TLS-RSA-PSK-WITH-CHACHA20-POLY1305-SHA256 +TLS-RSA-PSK-WITH-NULL-SHA +TLS-RSA-PSK-WITH-NULL-SHA256 +TLS-RSA-PSK-WITH-NULL-SHA384 +TLS-RSA-WITH-AES-128-CBC-SHA +TLS-RSA-WITH-AES-128-CBC-SHA256 +TLS-RSA-WITH-AES-128-CCM +TLS-RSA-WITH-AES-128-CCM-8 +TLS-RSA-WITH-AES-128-GCM-SHA256 +TLS-RSA-WITH-AES-256-CBC-SHA +TLS-RSA-WITH-AES-256-CBC-SHA256 +TLS-RSA-WITH-AES-256-CCM +TLS-RSA-WITH-AES-256-CCM-8 +TLS-RSA-WITH-AES-256-GCM-SHA384 +TLS-RSA-WITH-ARIA-128-CBC-SHA256 +TLS-RSA-WITH-ARIA-128-GCM-SHA256 +TLS-RSA-WITH-ARIA-256-CBC-SHA384 +TLS-RSA-WITH-ARIA-256-GCM-SHA384 +TLS-RSA-WITH-CAMELLIA-128-CBC-SHA +TLS-RSA-WITH-CAMELLIA-128-CBC-SHA256 +TLS-RSA-WITH-CAMELLIA-128-GCM-SHA256 +TLS-RSA-WITH-CAMELLIA-256-CBC-SHA +TLS-RSA-WITH-CAMELLIA-256-CBC-SHA256 +TLS-RSA-WITH-CAMELLIA-256-GCM-SHA384 +TLS-RSA-WITH-NULL-MD5 +TLS-RSA-WITH-NULL-SHA +TLS-RSA-WITH-NULL-SHA256 +``` + +As a consequence of the removal of support for DHE in (D)TLS 1.2, the following functions are no longer useful and have been removed: + +``` +mbedtls_ssl_conf_dh_param_bin() +mbedtls_ssl_conf_dh_param_ctx() +mbedtls_ssl_conf_dhm_min_bitlen() +``` + +### Removal of elliptic curves + +Following their removal from the crypto library, elliptic curves of less than 250 bits (secp192r1, secp192k1, secp224r1, secp224k1) are no longer supported in certificates and in TLS. + +### Removal of deprecated functions + +The deprecated functions `mbedtls_ssl_conf_min_version()` and `mbedtls_ssl_conf_max_version()`, and the associated constants `MBEDTLS_SSL_MAJOR_VERSION_3`, `MBEDTLS_SSL_MINOR_VERSION_3` and `MBEDTLS_SSL_MINOR_VERSION_4` have been removed. Use `mbedtls_ssl_conf_min_tls_version()` and `mbedtls_ssl_conf_max_tls_version()` with `MBEDTLS_SSL_VERSION_TLS1_2` or `MBEDTLS_SSL_VERSION_TLS1_3` instead. + +The deprecated function `mbedtls_ssl_conf_sig_hashes()` has been removed. Use `mbedtls_ssl_conf_sig_algs()` instead. +## Function prototype changes + +A number of existing functions now take a different list of arguments, mostly to migrate them to the PSA API. + +### Public functions no longer take a RNG callback + +Functions that need randomness no longer take an RNG callback in the form of `f_rng, p_rng` arguments. Instead, they use the PSA Crypto random generator (accessible as `psa_generate_random()`). All software using the X.509 or SSL modules must call `psa_crypto_init()` before calling any of the functions listed here. + +### RNG removal in X.509 + +The following function prototypes have been changed in `mbedtls/x509_crt.h`: + +```c +int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size, + int (*f_rng)(void *, unsigned char *, size_t), + void *p_rng); + +int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size, + int (*f_rng)(void *, unsigned char *, size_t), + void *p_rng); +``` + +to + +```c +int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size); + +int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size); +``` + +The following function prototypes have been changed in `mbedtls/x509_csr.h`: +```c +int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size, + int (*f_rng)(void *, unsigned char *, size_t), + void *p_rng); + +int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size, + int (*f_rng)(void *, unsigned char *, size_t), + void *p_rng); +``` + +to + +```c +int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size); + +int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size); +``` + +### RNG removal in SSL + +The following function prototype has been changed in `mbedtls/ssl_cookie.h`: + +```c +int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx, + int (*f_rng)(void *, unsigned char *, size_t), + void *p_rng); +``` + +to + +```c +int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx); +``` + +### Removal of `mbedtls_ssl_conf_rng` + +`mbedtls_ssl_conf_rng()` has been removed from the library. Its sole purpose was to configure the RNG used for TLS, but now the PSA Crypto random generator is used throughout the library. + +### Changes to mbedtls_ssl_ticket_setup + +In the arguments of the function `mbedtls_ssl_ticket_setup()`, the `mbedtls_cipher_type_t` argument specifying the AEAD mechanism for ticket protection has been replaced by an equivalent PSA description consisting of a key type, a size and an algorithm. Also, the function no longer takes RNG arguments. + +The prototype in `mbedtls/ssl_ticket.h` has changed from + +```c +int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx, + mbedtls_f_rng_t *f_rng, void *p_rng, + mbedtls_cipher_type_t cipher, + uint32_t lifetime); +``` + +to + +```c +int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx, + psa_algorithm_t alg, psa_key_type_t key_type, psa_key_bits_t key_bits, + uint32_t lifetime); +``` +## OID module + +The compilation option `MBEDTLS_OID_C` no longer exists. OID tables are included in the build automatically as needed for parsing and writing X.509 data. + +Mbed TLS no longer offers interfaces to look up values by OID or OID by enum values (`mbedtls_oid_get_()` and `mbedtls_oid_get_oid_by_()`). + +The header `` now only provides functions to convert between binary and dotted string OID representations. These functions are now part of `libmbedx509` rather than the crypto library. The function `mbedtls_oid_get_numeric_string()` is guarded by `MBEDTLS_X509_USE_C`, and `mbedtls_oid_from_numeric_string()` by `MBEDTLS_X509_CREATE_C`. The header also still defines macros for OID strings that are relevant to X.509. diff --git a/docs/4.0-migration-guide/configuration.md b/docs/4.0-migration-guide/configuration.md deleted file mode 100644 index 25bddf44f9..0000000000 --- a/docs/4.0-migration-guide/configuration.md +++ /dev/null @@ -1,44 +0,0 @@ -## Compile-time configuration - -### Configuration file split - -All configuration options that are relevant to TF-PSA-Crypto must now be configured in one of its configuration files, namely: - -* `TF_PSA_CRYPTO_CONFIG_FILE`, if set on the preprocessor command line; -* otherwise ``; -* additionally `TF_PSA_CRYPTO_USER_CONFIG_FILE`, if set. - -Configuration options that are relevant to X.509 or TLS should still be set in the Mbed TLS configuration file (`MBEDTLS_CONFIG_FILE` or ``, plus `MBEDTLS_USER_CONFIG_FILE` if it is set). However, you can define all options in the crypto configuration, and Mbed TLS will pick them up. - -Generally speaking, the options that must be configured in TF-PSA-Crypto are: - -* options related to platform settings; -* options related to the choice of cryptographic mechanisms included in the build; -* options related to the inner workings of cryptographic mechanisms, such as size/memory/performance compromises; -* options related to crypto-adjacent features, such as ASN.1 and Base64. - -See `include/psa/crypto_config.h` in TF-PSA-Crypto and `include/mbedtls/mbedtls_config.h` in Mbed TLS for details. - -Notably, `` is no longer limited to `PSA_WANT_xxx` options. - -Note that many options related to cryptography have changed; see the TF-PSA-Crypto migration guide for details. - -### Split of `build_info.h` and `version.h` - -The header file ``, which includes the configuration file and provides the adjusted configuration macros, now has an similar file `` in TF-PSA-Crypto. The Mbed TLS header includes the TF-PSA-Crypto header, so including `` remains sufficient to obtain information about the crypto configuration. - -TF-PSA-Crypto exposes its version through ``, similar to `` in Mbed TLS. - -### Removal of `check_config.h` - -The header `mbedtls/check_config.h` is no longer present. Including it from user configuration files was already obsolete in Mbed TLS 3.x, since it enforces properties the configuration as adjusted by `mbedtls/build_info.h`, not properties that the user configuration is expected to meet. - -### Changes to TLS options - -#### Enabling null cipher suites - -The option to enable null cipher suites in TLS 1.2 has been renamed from `MBEDTLS_CIPHER_NULL_CIPHER` to `MBEDTLS_SSL_NULL_CIPHERSUITES`. It remains disabled in the default configuration. - -#### Removal of backward compatibility options - -The option `MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT` has been removed. Only the version standardized in RFC 9146 is supported now. diff --git a/docs/4.0-migration-guide/deprecated-removals.md b/docs/4.0-migration-guide/deprecated-removals.md deleted file mode 100644 index e74b1adc10..0000000000 --- a/docs/4.0-migration-guide/deprecated-removals.md +++ /dev/null @@ -1,14 +0,0 @@ -## Removal of deprecated functions - -### Removal of deprecated X.509 functions - -The deprecated function `mbedtls_x509write_crt_set_serial()` has been removed. The function was superseded by `mbedtls_x509write_crt_set_serial_raw()`. - -### Removal of deprecated SSL functions - -The deprecated function `mbedtls_ssl_conf_curves()` has been removed. -The function was superseded by `mbedtls_ssl_conf_groups()`. - -### Removal of `compat-2.x.h` - -The header `compat-2.x.h`, containing some definitions for backward compatibility with Mbed TLS 2.x, has been removed. diff --git a/docs/4.0-migration-guide/error-codes.md b/docs/4.0-migration-guide/error-codes.md deleted file mode 100644 index a2744679e0..0000000000 --- a/docs/4.0-migration-guide/error-codes.md +++ /dev/null @@ -1,37 +0,0 @@ -## Error codes - -### Unified error code space - -The convention still applies that functions return 0 for success and a negative value between -32767 and -1 on error. PSA functions (`psa_xxx()` or `mbedtls_psa_xxx()`) still return a `PSA_ERROR_xxx` error codes. Non-PSA functions (`mbedtls_xxx()` excluding `mbedtls_psa_xxx()`) can return either `PSA_ERROR_xxx` or `MBEDTLS_ERR_xxx` error codes. - -There may be cases where an `MBEDTLS_ERR_xxx` constant has the same numerical value as a `PSA_ERROR_xxx`. In such cases, they have the same meaning: they are different names for the same error condition. - -### Simplified legacy error codes - -All values returned by a function to indicate an error now have a defined constant named `MBEDTLS_ERR_xxx` or `PSA_ERROR_xxx`. Functions no longer return the sum of a “low-level” and a “high-level” error code. - -Generally, functions that used to return the sum of two error codes now return the low-level code. However, as before, the exact error code returned in a given scenario can change without notice unless the condition is specifically described in the function's documentation and no other condition is applicable. - -As a consequence, the functions `mbedtls_low_level_strerr()` and `mbedtls_high_level_strerr()` no longer exist. - -### Removed error code names - -Many legacy error codes have been removed in favor of PSA error codes. Generally, functions that returned a legacy error code in the table below in Mbed TLS 3.6 now return the PSA error code listed on the same row. Similarly, callbacks should apply the same changes to error code, unless there has been a relevant change to the callback's interface. - -| Legacy constant (Mbed TLS 3.6) | PSA constant (Mbed TLS 4.0) | -|-----------------------------------------|---------------------------------| -| `MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED` | `PSA_ERROR_CORRUPTION_DETECTED` | -| `MBEDTLS_ERR_ERROR_GENERIC_ERROR` | `PSA_ERROR_GENERIC_ERROR` | -| `MBEDTLS_ERR_NET_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` | -| `MBEDTLS_ERR_OID_BUF_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` | -| `MBEDTLS_ERR_OID_NOT_FOUND` | `PSA_ERROR_NOT_SUPPORTED` | -| `MBEDTLS_ERR_PKCS7_ALLOC_FAILED` | `PSA_ERROR_INSUFFICIENT_MEMORY` | -| `MBEDTLS_ERR_PKCS7_BAD_INPUT_DATA` | `PSA_ERROR_INVALID_ARGUMENT` | -| `MBEDTLS_ERR_PKCS7_VERIFY_FAIL` | `PSA_ERROR_INVALID_SIGNATURE` | -| `MBEDTLS_ERR_SSL_ALLOC_FAILED` | `PSA_ERROR_INSUFFICIENT_MEMORY` | -| `MBEDTLS_ERR_SSL_BAD_INPUT_DATA` | `PSA_ERROR_INVALID_ARGUMENT` | -| `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` | -| `MBEDTLS_ERR_X509_ALLOC_FAILED` | `PSA_ERROR_INSUFFICIENT_MEMORY` | -| `MBEDTLS_ERR_X509_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` | - -See also the corresponding section in the TF-PSA-Crypto migration guide, which lists error codes from cryptography modules. diff --git a/docs/4.0-migration-guide/feature-removals.md b/docs/4.0-migration-guide/feature-removals.md deleted file mode 100644 index b958f864fc..0000000000 --- a/docs/4.0-migration-guide/feature-removals.md +++ /dev/null @@ -1,152 +0,0 @@ -## Removed features - -### Removal of obsolete key exchanges methods in (D)TLS 1.2 - -Mbed TLS 4.0 no longer supports key exchange methods that rely on finite-field Diffie-Hellman (DHE) in TLS 1.2 and DTLS 1.2. (Only ephemeral Diffie-Hellman was ever supported, Mbed TLS 3.x already did not support static Diffie-Hellman.) Finite-field Diffie-Hellman remains supported in TLS 1.3. - -Mbed TLS 4.0 no longer supports key exchange methods that rely on RSA decryption (without forward secrecy). RSA signatures remain supported. This affects TLS 1.2 and DTLS 1.2 (TLS 1.3 does not have key exchanges using RSA decryption). - -That is, the following key exchange types are no longer supported: - -* RSA-PSK; -* RSA (i.e. cipher suites using only RSA decryption: cipher suites using RSA signatures remain supported); -* DHE-PSK (except in TLS 1.3); -* DHE-RSA (except in TLS 1.3). -* static ECDH (ECDH-RSA and ECDH-ECDSA, as opposed to ephemeral ECDH (ECDHE) which remains supported). - -The full list of removed cipher suites is: - -``` -TLS-DHE-PSK-WITH-AES-128-CBC-SHA -TLS-DHE-PSK-WITH-AES-128-CBC-SHA256 -TLS-DHE-PSK-WITH-AES-128-CCM -TLS-DHE-PSK-WITH-AES-128-CCM-8 -TLS-DHE-PSK-WITH-AES-128-GCM-SHA256 -TLS-DHE-PSK-WITH-AES-256-CBC-SHA -TLS-DHE-PSK-WITH-AES-256-CBC-SHA384 -TLS-DHE-PSK-WITH-AES-256-CCM -TLS-DHE-PSK-WITH-AES-256-CCM-8 -TLS-DHE-PSK-WITH-AES-256-GCM-SHA384 -TLS-DHE-PSK-WITH-ARIA-128-CBC-SHA256 -TLS-DHE-PSK-WITH-ARIA-128-GCM-SHA256 -TLS-DHE-PSK-WITH-ARIA-256-CBC-SHA384 -TLS-DHE-PSK-WITH-ARIA-256-GCM-SHA384 -TLS-DHE-PSK-WITH-CAMELLIA-128-CBC-SHA256 -TLS-DHE-PSK-WITH-CAMELLIA-128-GCM-SHA256 -TLS-DHE-PSK-WITH-CAMELLIA-256-CBC-SHA384 -TLS-DHE-PSK-WITH-CAMELLIA-256-GCM-SHA384 -TLS-DHE-PSK-WITH-CHACHA20-POLY1305-SHA256 -TLS-DHE-PSK-WITH-NULL-SHA -TLS-DHE-PSK-WITH-NULL-SHA256 -TLS-DHE-PSK-WITH-NULL-SHA384 -TLS-DHE-RSA-WITH-AES-128-CBC-SHA -TLS-DHE-RSA-WITH-AES-128-CBC-SHA256 -TLS-DHE-RSA-WITH-AES-128-CCM -TLS-DHE-RSA-WITH-AES-128-CCM-8 -TLS-DHE-RSA-WITH-AES-128-GCM-SHA256 -TLS-DHE-RSA-WITH-AES-256-CBC-SHA -TLS-DHE-RSA-WITH-AES-256-CBC-SHA256 -TLS-DHE-RSA-WITH-AES-256-CCM -TLS-DHE-RSA-WITH-AES-256-CCM-8 -TLS-DHE-RSA-WITH-AES-256-GCM-SHA384 -TLS-DHE-RSA-WITH-ARIA-128-CBC-SHA256 -TLS-DHE-RSA-WITH-ARIA-128-GCM-SHA256 -TLS-DHE-RSA-WITH-ARIA-256-CBC-SHA384 -TLS-DHE-RSA-WITH-ARIA-256-GCM-SHA384 -TLS-DHE-RSA-WITH-CAMELLIA-128-CBC-SHA -TLS-DHE-RSA-WITH-CAMELLIA-128-CBC-SHA256 -TLS-DHE-RSA-WITH-CAMELLIA-128-GCM-SHA256 -TLS-DHE-RSA-WITH-CAMELLIA-256-CBC-SHA -TLS-DHE-RSA-WITH-CAMELLIA-256-CBC-SHA256 -TLS-DHE-RSA-WITH-CAMELLIA-256-GCM-SHA384 -TLS-DHE-RSA-WITH-CHACHA20-POLY1305-SHA256 -TLS-ECDH-ECDSA-WITH-AES-128-CBC-SHA -TLS-ECDH-ECDSA-WITH-AES-128-CBC-SHA256 -TLS-ECDH-ECDSA-WITH-AES-128-GCM-SHA256 -TLS-ECDH-ECDSA-WITH-AES-256-CBC-SHA -TLS-ECDH-ECDSA-WITH-AES-256-CBC-SHA384 -TLS-ECDH-ECDSA-WITH-AES-256-GCM-SHA384 -TLS-ECDH-ECDSA-WITH-ARIA-128-CBC-SHA256 -TLS-ECDH-ECDSA-WITH-ARIA-128-GCM-SHA256 -TLS-ECDH-ECDSA-WITH-ARIA-256-CBC-SHA384 -TLS-ECDH-ECDSA-WITH-ARIA-256-GCM-SHA384 -TLS-ECDH-ECDSA-WITH-CAMELLIA-128-CBC-SHA256 -TLS-ECDH-ECDSA-WITH-CAMELLIA-128-GCM-SHA256 -TLS-ECDH-ECDSA-WITH-CAMELLIA-256-CBC-SHA384 -TLS-ECDH-ECDSA-WITH-CAMELLIA-256-GCM-SHA384 -TLS-ECDH-ECDSA-WITH-NULL-SHA -TLS-ECDH-RSA-WITH-AES-128-CBC-SHA -TLS-ECDH-RSA-WITH-AES-128-CBC-SHA256 -TLS-ECDH-RSA-WITH-AES-128-GCM-SHA256 -TLS-ECDH-RSA-WITH-AES-256-CBC-SHA -TLS-ECDH-RSA-WITH-AES-256-CBC-SHA384 -TLS-ECDH-RSA-WITH-AES-256-GCM-SHA384 -TLS-ECDH-RSA-WITH-ARIA-128-CBC-SHA256 -TLS-ECDH-RSA-WITH-ARIA-128-GCM-SHA256 -TLS-ECDH-RSA-WITH-ARIA-256-CBC-SHA384 -TLS-ECDH-RSA-WITH-ARIA-256-GCM-SHA384 -TLS-ECDH-RSA-WITH-CAMELLIA-128-CBC-SHA256 -TLS-ECDH-RSA-WITH-CAMELLIA-128-GCM-SHA256 -TLS-ECDH-RSA-WITH-CAMELLIA-256-CBC-SHA384 -TLS-ECDH-RSA-WITH-CAMELLIA-256-GCM-SHA384 -TLS-ECDH-RSA-WITH-NULL-SHA -TLS-RSA-PSK-WITH-AES-128-CBC-SHA -TLS-RSA-PSK-WITH-AES-128-CBC-SHA256 -TLS-RSA-PSK-WITH-AES-128-GCM-SHA256 -TLS-RSA-PSK-WITH-AES-256-CBC-SHA -TLS-RSA-PSK-WITH-AES-256-CBC-SHA384 -TLS-RSA-PSK-WITH-AES-256-GCM-SHA384 -TLS-RSA-PSK-WITH-ARIA-128-CBC-SHA256 -TLS-RSA-PSK-WITH-ARIA-128-GCM-SHA256 -TLS-RSA-PSK-WITH-ARIA-256-CBC-SHA384 -TLS-RSA-PSK-WITH-ARIA-256-GCM-SHA384 -TLS-RSA-PSK-WITH-CAMELLIA-128-CBC-SHA256 -TLS-RSA-PSK-WITH-CAMELLIA-128-GCM-SHA256 -TLS-RSA-PSK-WITH-CAMELLIA-256-CBC-SHA384 -TLS-RSA-PSK-WITH-CAMELLIA-256-GCM-SHA384 -TLS-RSA-PSK-WITH-CHACHA20-POLY1305-SHA256 -TLS-RSA-PSK-WITH-NULL-SHA -TLS-RSA-PSK-WITH-NULL-SHA256 -TLS-RSA-PSK-WITH-NULL-SHA384 -TLS-RSA-WITH-AES-128-CBC-SHA -TLS-RSA-WITH-AES-128-CBC-SHA256 -TLS-RSA-WITH-AES-128-CCM -TLS-RSA-WITH-AES-128-CCM-8 -TLS-RSA-WITH-AES-128-GCM-SHA256 -TLS-RSA-WITH-AES-256-CBC-SHA -TLS-RSA-WITH-AES-256-CBC-SHA256 -TLS-RSA-WITH-AES-256-CCM -TLS-RSA-WITH-AES-256-CCM-8 -TLS-RSA-WITH-AES-256-GCM-SHA384 -TLS-RSA-WITH-ARIA-128-CBC-SHA256 -TLS-RSA-WITH-ARIA-128-GCM-SHA256 -TLS-RSA-WITH-ARIA-256-CBC-SHA384 -TLS-RSA-WITH-ARIA-256-GCM-SHA384 -TLS-RSA-WITH-CAMELLIA-128-CBC-SHA -TLS-RSA-WITH-CAMELLIA-128-CBC-SHA256 -TLS-RSA-WITH-CAMELLIA-128-GCM-SHA256 -TLS-RSA-WITH-CAMELLIA-256-CBC-SHA -TLS-RSA-WITH-CAMELLIA-256-CBC-SHA256 -TLS-RSA-WITH-CAMELLIA-256-GCM-SHA384 -TLS-RSA-WITH-NULL-MD5 -TLS-RSA-WITH-NULL-SHA -TLS-RSA-WITH-NULL-SHA256 -``` - -As a consequence of the removal of support for DHE in (D)TLS 1.2, the following functions are no longer useful and have been removed: - -``` -mbedtls_ssl_conf_dh_param_bin() -mbedtls_ssl_conf_dh_param_ctx() -mbedtls_ssl_conf_dhm_min_bitlen() -``` - -### Removal of elliptic curves - -Following their removal from the crypto library, elliptic curves of less than 250 bits (secp192r1, secp192k1, secp224r1, secp224k1) are no longer supported in certificates and in TLS. - -### Removal of deprecated functions - -The deprecated functions `mbedtls_ssl_conf_min_version()` and `mbedtls_ssl_conf_max_version()`, and the associated constants `MBEDTLS_SSL_MAJOR_VERSION_3`, `MBEDTLS_SSL_MINOR_VERSION_3` and `MBEDTLS_SSL_MINOR_VERSION_4` have been removed. Use `mbedtls_ssl_conf_min_tls_version()` and `mbedtls_ssl_conf_max_tls_version()` with `MBEDTLS_SSL_VERSION_TLS1_2` or `MBEDTLS_SSL_VERSION_TLS1_3` instead. - -The deprecated function `mbedtls_ssl_conf_sig_hashes()` has been removed. Use `mbedtls_ssl_conf_sig_algs()` instead. diff --git a/docs/4.0-migration-guide/function-prototype-changes.md b/docs/4.0-migration-guide/function-prototype-changes.md deleted file mode 100644 index 52e37c7286..0000000000 --- a/docs/4.0-migration-guide/function-prototype-changes.md +++ /dev/null @@ -1,89 +0,0 @@ -## Function prototype changes - -A number of existing functions now take a different list of arguments, mostly to migrate them to the PSA API. - -### Public functions no longer take a RNG callback - -Functions that need randomness no longer take an RNG callback in the form of `f_rng, p_rng` arguments. Instead, they use the PSA Crypto random generator (accessible as `psa_generate_random()`). All software using the X.509 or SSL modules must call `psa_crypto_init()` before calling any of the functions listed here. - -### RNG removal in X.509 - -The following function prototypes have been changed in `mbedtls/x509_crt.h`: - -```c -int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size, - int (*f_rng)(void *, unsigned char *, size_t), - void *p_rng); - -int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size, - int (*f_rng)(void *, unsigned char *, size_t), - void *p_rng); -``` - -to - -```c -int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size); - -int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size); -``` - -The following function prototypes have been changed in `mbedtls/x509_csr.h`: -```c -int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size, - int (*f_rng)(void *, unsigned char *, size_t), - void *p_rng); - -int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size, - int (*f_rng)(void *, unsigned char *, size_t), - void *p_rng); -``` - -to - -```c -int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size); - -int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size); -``` - -### RNG removal in SSL - -The following function prototype has been changed in `mbedtls/ssl_cookie.h`: - -```c -int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx, - int (*f_rng)(void *, unsigned char *, size_t), - void *p_rng); -``` - -to - -```c -int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx); -``` - -### Removal of `mbedtls_ssl_conf_rng` - -`mbedtls_ssl_conf_rng()` has been removed from the library. Its sole purpose was to configure the RNG used for TLS, but now the PSA Crypto random generator is used throughout the library. - -### Changes to mbedtls_ssl_ticket_setup - -In the arguments of the function `mbedtls_ssl_ticket_setup()`, the `mbedtls_cipher_type_t` argument specifying the AEAD mechanism for ticket protection has been replaced by an equivalent PSA description consisting of a key type, a size and an algorithm. Also, the function no longer takes RNG arguments. - -The prototype in `mbedtls/ssl_ticket.h` has changed from - -```c -int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx, - mbedtls_f_rng_t *f_rng, void *p_rng, - mbedtls_cipher_type_t cipher, - uint32_t lifetime); -``` - -to - -```c -int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx, - psa_algorithm_t alg, psa_key_type_t key_type, psa_key_bits_t key_bits, - uint32_t lifetime); -``` diff --git a/docs/4.0-migration-guide/oid.md b/docs/4.0-migration-guide/oid.md deleted file mode 100644 index 875f062155..0000000000 --- a/docs/4.0-migration-guide/oid.md +++ /dev/null @@ -1,7 +0,0 @@ -## OID module - -The compilation option `MBEDTLS_OID_C` no longer exists. OID tables are included in the build automatically as needed for parsing and writing X.509 data. - -Mbed TLS no longer offers interfaces to look up values by OID or OID by enum values (`mbedtls_oid_get_()` and `mbedtls_oid_get_oid_by_()`). - -The header `` now only provides functions to convert between binary and dotted string OID representations. These functions are now part of `libmbedx509` rather than the crypto library. The function `mbedtls_oid_get_numeric_string()` is guarded by `MBEDTLS_X509_USE_C`, and `mbedtls_oid_from_numeric_string()` by `MBEDTLS_X509_CREATE_C`. The header also still defines macros for OID strings that are relevant to X.509. diff --git a/docs/4.0-migration-guide/private-decls.md b/docs/4.0-migration-guide/private-decls.md deleted file mode 100644 index ff974746c5..0000000000 --- a/docs/4.0-migration-guide/private-decls.md +++ /dev/null @@ -1,33 +0,0 @@ -## Private declarations - -Since Mbed TLS 3.0, some things that are declared in a public header are not part of the stable application programming interface (API), but instead are considered private. Private elements may be removed or may have their semantics changed in a future minor release without notice. - -### Understanding private declarations in public headers - -In Mbed TLS 4.x, private elements in header files include: - -* Anything appearing in a header file whose path contains `/private` (unless re-exported and documented in another non-private header). -* Structure and union fields declared with `MBEDTLS_PRIVATE(field_name)` in the source code, and appearing as `private_field_name` in the rendered documentation. (This was already the case since Mbed TLS 3.0.) -* Any preprocessor macro that is not documented with a Doxygen comment. - In the source code, Doxygen comments start with `/**` or `/*!`. If a macro only has a comment above that starts with `/*`, the macro is considered private. - In the rendered documentation, private macros appear with only an automatically rendered parameter list, value and location, but no custom text. -* Any declaration that is guarded by the preprocessor macro `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS`. - -### Usage of private declarations - -Some private declarations are present in public headers for technical reasons, because they need to be visible to the compiler. Others are present for historical reasons and may be cleaned up in later versions of the library. We strongly recommend against relying on these declarations, since they may be removed or may have their semantics changed without notice. - -Note that Mbed TLS 4.0 still relies on some private interfaces of TF-PSA-Crypto 1.0. We expect to remove this reliance gradually in future minor releases. - -Sample programs have not been fully updated yet and some of them might still -use APIs that are no longer public. You can recognize them by the fact that they -define the macro `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS` (or -`MBEDTLS_ALLOW_PRIVATE_ACCESS`) at the very top (before including headers). When -you see one of these two macros in a sample program, be aware it has not been -updated and parts of it do not demonstrate current practice. - -We strongly recommend against defining `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS` or -`MBEDTLS_ALLOW_PRIVATE_ACCESS` in your own application. If you do so, your code -may not compile or work with future minor releases. If there's something you -want to do that you feel can only be achieved by using one of these two macros, -please reach out on github or the mailing list. diff --git a/docs/4.0-migration-guide/psa-only.md b/docs/4.0-migration-guide/psa-only.md deleted file mode 100644 index 7d7bfee193..0000000000 --- a/docs/4.0-migration-guide/psa-only.md +++ /dev/null @@ -1,23 +0,0 @@ -## PSA as the only cryptography API - -The PSA API is now the only API for cryptographic primitives. - -### Impact on application code - -The X.509, PKCS7 and SSL modules always use PSA for cryptography, with a few exceptions documented in the [PSA limitations](../architecture/psa-migration/psa-limitations.md) document. (These limitations are mostly transparent unless you want to leverage PSA accelerator drivers.) This corresponds to the behavior of Mbed TLS 3.x when `MBEDTLS_USE_PSA_CRYPTO` is enabled. In effect, `MBEDTLS_USE_PSA_CRYPTO` is now always enabled. - -`psa_crypto_init()` must be called before performing any cryptographic operation, including indirect requests such as parsing a key or certificate or starting a TLS handshake. - -A few functions take different parameters to migrate them to the PSA API. See “[Function prototype changes](#function-prototype-changes)”. - -### No random generator instantiation - -Formerly, applications using TLS, asymmetric cryptography operations involving a private key, or other features needing random numbers, needed to provide a random generator, generally by instantiating an entropy context (`mbedtls_entropy_context`) and a DRBG context (`mbedtls_ctr_drbg_context` or `mbedtls_hmac_drbg_context`). This is no longer necessary, or possible. All features that require a random generator (RNG) now use the one provided by the PSA subsystem. - -Instead, applications that use random generators or keys (even public keys) need to call `psa_crypto_init()` before any cryptographic operation or key management operation. - -See also [function prototype changes](#function-prototype-changes), many of which are related to the move from RNG callbacks to a global RNG. - -### Impact on the library configuration - -Mbed TLS follows the configuration of TF-PSA-Crypto with respect to cryptographic mechanisms. They are now based on `PSA_WANT_xxx` macros instead of legacy configuration macros such as `MBEDTLS_RSA_C`, `MBEDTLS_PKCS1_V15`, etc. The configuration of X.509 and TLS is not directly affected by the configuration. However, applications and middleware that rely on these configuration symbols to know which cryptographic mechanisms to support will need to migrate to `PSA_WANT_xxx` macros. For more information, consult the PSA transition guide in TF-PSA-Crypto. diff --git a/docs/4.0-migration-guide/repo-split.md b/docs/4.0-migration-guide/repo-split.md deleted file mode 100644 index 5ad741855b..0000000000 --- a/docs/4.0-migration-guide/repo-split.md +++ /dev/null @@ -1,200 +0,0 @@ -## CMake as the only build system -Mbed TLS now uses CMake exclusively to configure and drive its build process. -Support for the GNU Make and Microsoft Visual Studio project-based build systems has been removed. - -The previous `.sln` and `.vcxproj` files are no longer distributed or generated. - -See the `Compiling` section in README.md for instructions on building the Mbed TLS libraries and tests with CMake. -If you develop in Microsoft Visual Studio, you could either generate a Visual Studio solution using a CMake generator, or open the CMake project directly in Visual Studio. - -### Translating Make commands to CMake - -With the removal of GNU Make support, all build, test, and installation operations must now be performed using CMake. -This section provides a quick reference for translating common `make` commands into their CMake equivalents. - -#### Basic build workflow - -Run `cmake -S . -B build` once before building to configure the build and generate native build files (e.g., Makefiles) in the `build` directory. -This sets up an out-of-tree build, which is recommended. - -| Make command | CMake equivalent | Description | -|----------------|------------------------------------------------|--------------------------------------------------------------------| -| `make` | `cmake --build build` | Build the libraries, programs, and tests in the `build` directory. | -| `make test` | `ctest --test-dir build` | Run the tests produced by the previous build. | -| `make clean` | `cmake --build build --target clean` | Remove build artifacts produced by the previous build. | -| `make install` | `cmake --install build --prefix build/install` | Install the built libraries, headers, and tests to `build/install`. | - -#### Building specific targets - -Unless otherwise specified, the CMake command in the table below should be preceded by a `cmake -S . -B build` call to configure the build and generate build files in the `build` directory. - -| Make command | CMake equivalent | Description | -|-----------------|---------------------------------------------------------------------|---------------------------| -| `make lib` | `cmake --build build --target lib` | Build only the libraries. | -| `make tests` | `cmake -S . -B build -DENABLE_PROGRAMS=Off && cmake --build build` | Build test suites. | -| `make programs` | `cmake --build build --target programs` | Build example programs. | -| `make apidoc` | `cmake --build build --target mbedtls-apidoc` | Build documentation. | - -Target names may differ slightly; use `cmake --build build --target help` to list all available CMake targets. - -There is no CMake equivalent for `make generated_files` or `make neat`. -Generated files are automatically created in the build tree with `cmake --build build` and removed with `cmake --build build --target clean`. -If you need to build the generated files in the source tree without involving CMake, you can call `framework/scripts/make_generated_files.py`. - -There is currently no equivalent for `make uninstall` in the Mbed TLS CMake build system. - -#### Common build options - -The following table illustrates the approximate CMake equivalents of common make commands. -Most CMake examples show only the configuration step, others (like installation) correspond to different stages of the build process. - -| Make usage | CMake usage | Description | -|----------------------------|-------------------------------------------------------|----------------------| -| `make DEBUG=1` | `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug` | Build in debug mode. | -| `make SHARED=1` | `cmake -S . -B build -DUSE_SHARED_MBEDTLS_LIBRARY=On` | Also build shared libraries. | -| `make GEN_FILES=""` | `cmake -S . -B build -DGEN_FILES=OFF` | Skip generating files (not a strict equivalent). | -| `make DESTDIR=install_dir` | `cmake --install build --prefix install_dir` | Specify installation path. | -| `make CC=clang` | `cmake -S . -B build -DCMAKE_C_COMPILER=clang` | Set the compiler. | -| `make CFLAGS='-O2 -Wall'` | `cmake -S . -B build -DCMAKE_C_FLAGS="-O2 -Wall"` | Set compiler flags. | - -## Repository split -In Mbed TLS 4.0, the project was split into two repositories: -- [Mbed TLS](https://github.com/Mbed-TLS/mbedtls): provides TLS and X.509 functionality. -- [TF-PSA-Crypto](https://github.com/Mbed-TLS/TF-PSA-Crypto): provides the standalone cryptography library, implementing the PSA Cryptography API. -Mbed TLS consumes TF-PSA-Crypto as a submodule. -You should stay with Mbed TLS if you use TLS or X.509 functionality. You still have direct access to the cryptography library. - -### File and directory relocations - -The following table summarizes the file and directory relocations resulting from the repository split between Mbed TLS and TF-PSA-Crypto. -These changes reflect the move of cryptographic, cryptographic-adjacent, and platform components from Mbed TLS into the new TF-PSA-Crypto repository. - -| Original location | New location(s) | Notes | -|-----------------------------------------|--------------------------------------------------------------------------------------|-------| -| `library/*` (†) | `tf-psa-crypto/core/`
`tf-psa-crypto/drivers/builtin/src/` | Contains cryptographic, cryptographic-adjacent (e.g., ASN.1, Base64), and platform C modules and headers. | -| `include/mbedtls/*` (†) | `tf-psa-crypto/include/mbedtls/`
`tf-psa-crypto/drivers/builtin/include/private/` | Public headers moved to `include/mbedtls`; now internal headers moved to `include/private`. | -| `include/psa` | `tf-psa-crypto/include/psa` | All PSA headers consolidated here. | -| `3rdparty/everest`
`3rdparty/p256-m` | `tf-psa-crypto/drivers/everest`
`tf-psa-crypto/drivers/p256-m` | Third-party crypto driver implementations. | - -(†) The `library` and `include/mbedtls` directories still exist in Mbed TLS, but now contain only TLS and X.509 components. - -### Configuration file split -Cryptography and platform configuration options have been moved from `include/mbedtls/mbedtls_config.h` to `tf-psa-crypto/include/psa/crypto_config.h`, which is now mandatory. -See [Compile-time configuration](#compile-time-configuration). - -The header `include/mbedtls/mbedtls_config.h` still exists and now contains only the TLS and X.509 configuration options. - -If you use the Python script `scripts/config.py` to adjust your configuration, you do not need to modify your scripts to specify which configuration file to edit, the script automatically updates the correct file. - -There have been significant changes in the configuration options, primarily affecting cryptography. - -#### Cryptography configuration -- See [psa-transition.md](https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/psa-transition.md#compile-time-configuration). -- See also the following sections in the TF-PSA-Crypto 1.0 migration guide: - - *PSA as the Only Cryptography API* and its sub-section *Impact on the Library Configuration* - - *Random Number Generation Configuration* - -#### TLS configuration -For details about TLS-related changes, see [Changes to TLS options](#changes-to-tls-options). - -### Impact on some usages of the library - -#### Checking out a branch or a tag -After checking out a branch or tag of the Mbed TLS repository, you must now recursively update the submodules, as TF-PSA-Crypto contains itself a nested submodule: -``` -git submodule update --init --recursive -``` - -#### Linking directly to a built library - -The Mbed TLS CMake build system still provides the cryptography libraries under their legacy name, `libmbedcrypto.`, so you can continue linking against them. -These libraries are still located in the `library` directory within the build tree. - -The cryptography libraries are also now provided as `libtfpsacrypto.`, consistent with the naming used in the TF-PSA-Crypto repository. - -You may need to update include paths to the public header files, see [File and Directory Relocations](#file-and-directory-relocations) for details. - -#### Using Mbed TLS as a CMake subproject - -The base name of the libraries are now `tfpsacrypto` (formely `mbedcrypto`), `mbedx509` and `mbedtls`. -As before, these base names are also the names of CMake targets to build each library. -If your CMake scripts reference a cryptography library target, you need to update its name accordingly. - -For example, the following CMake code: -``` -target_link_libraries(mytarget PRIVATE mbedcrypto) -``` -should be updated to: -``` -target_link_libraries(mytarget PRIVATE tfpsacrypto) -``` - -You can refer to the following example demonstrating how to consume Mbed TLS as a CMake subproject: -- `programs/test/cmake_subproject` - -#### Using Mbed TLS as a CMake package - -The same renaming applies to the cryptography library targets declared as part of the Mbed TLS CMake package, use `MbedTLS::tfpsacrypto` instead of `MbedTLS::mbedcrypto`. - -For example, the following CMake code: -``` -find_package(MbedTLS REQUIRED) -target_link_libraries(myapp PRIVATE MbedTLS::mbedcrypto) -``` -should be updated to: -``` -find_package(MbedTLS REQUIRED) -target_link_libraries(myapp PRIVATE MbedTLS::tfpsacrypto) -``` -You can also refer to the following example programs demonstrating how to consume Mbed TLS as a CMake package: -- `programs/test/cmake_package` -- `programs/test/cmake_package_install` - -#### Using the Mbed TLS Crypto pkg-config file - -The Mbed TLS CMake build system still provides the pkg-config file mbedcrypto.pc, so you can continue using it. -Internally, it now references the tfpsacrypto library. - -A new pkg-config file, `tfpsacrypto.pc`, is also provided. -Both `mbedcrypto.pc` and `tfpsacrypto.pc` are functionally equivalent, providing the same compiler and linker flags. - -#### Using Mbed TLS as an installed library - -The Mbed TLS CMake build system still installs the cryptography libraries under their legacy name, `libmbedcrypto.`, so you can continue linking against them. -The cryptography library is also now provided as `libtfpsacrypto.`. - -Regarding the headers, the main change is the relocation of some headers to subdirectories called `private`. -These headers are installed primarily to satisfy compiler dependencies. -Others remain for historical reasons and may be cleaned up in later versions of the library. - -We strongly recommend not relying on the declarations in these headers, as they may be removed or modified without notice. -See the section Private Declarations in the TF-PSA-Crypto 1.0 migration guide for more information. - -Finally, note the new `include/tf-psa-crypto` directory, which contains the TF-PSA-Crypto version and build-time configuration headers. - -### Audience-Specific Notes - -#### Application Developers using a distribution package -- See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on: - - Linking against the cryptography library or CMake targets. - - Using the Mbed TLS Crypto pkg-config file. - - Using Mbed TLS as an installed library - -### Developer or package maintainers -If you build or distribute Mbed TLS: -- The build system is now CMake only, Makefiles and Visual Studio projects are removed. -- You may need to adapt packaging scripts to handle the TF-PSA-Crypto submodule. -- You should update submodules recursively after checkout. -- Review [File and directory relocations](#file-and-directory-relocations) for updated paths. -- See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on: - - Linking against the cryptography library or CMake targets. - - Using the Mbed TLS Crypto pkg-config file (`mbedcrypto.pc` or `tfpsacrypto.pc`). - - Using Mbed TLS as an installed library -- Configuration note: cryptography and platform options are now in `crypto_config.h` (see [Configuration file split](#configuration-file-split)). - -### Platform Integrators -If you integrate Mbed TLS with a platform or hardware drivers: -- TF-PSA-Crypto is now a submodule, update integration scripts to initialize submodules recursively. -- The PSA driver wrapper is now generated in TF-PSA-Crypto. -- Platform-specific configuration are now handled in `crypto_config.h`. -- See [Repository split](#repository-split) for how platform components moved to TF-PSA-Crypto. From 2c0cb9926a979cfc6e97f33d4eca9a8259e10305 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 10 Oct 2025 15:56:21 +0200 Subject: [PATCH 37/47] Add short introduction Signed-off-by: Gilles Peskine --- docs/4.0-migration-guide.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/4.0-migration-guide.md b/docs/4.0-migration-guide.md index 83ec90ca92..040194b478 100644 --- a/docs/4.0-migration-guide.md +++ b/docs/4.0-migration-guide.md @@ -1,3 +1,16 @@ +# Migrating from Mbed TLS 3.x to TF-PSA-Crypto 1.0 + +This guide details the steps required to migrate from Mbed TLS version 2.x to Mbed TLS version 3.0 or greater. Unlike normal releases, Mbed TLS 3.0 breaks compatibility with previous versions, so users, integrators and package maintainers might need to change their own code in order to make it work with Mbed TLS 3.0. + +Here's the list of breaking changes; each entry should help you answer these two questions: (1) am I affected? (2) if yes, what's my migration path? + +- Mbed TLS has been split between two products: TF-PSA-Crypto for cryptography, and Mbed TLS for X.509 and (D)TLS. +- CMake is now the only supported build system. +- The cryptography API is now mostly the PSA API: most legacy cryptography APIs have been removed. This has led to adaptations in some X.509 and TLS APIs, notably because the library always uses the PSA random generator. +- Various deprecated or minor functionality has been removed. + +Please consult the [TF-PSA-Crypto migration guide](../tf-psa-crypto/docs/1.0-migration-guide.md) for all information related to the crytography part of the library. + ## CMake as the only build system Mbed TLS now uses CMake exclusively to configure and drive its build process. Support for the GNU Make and Microsoft Visual Studio project-based build systems has been removed. @@ -248,7 +261,7 @@ The PSA API is now the only API for cryptographic primitives. ### Impact on application code -The X.509, PKCS7 and SSL modules always use PSA for cryptography, with a few exceptions documented in the [PSA limitations](../architecture/psa-migration/psa-limitations.md) document. (These limitations are mostly transparent unless you want to leverage PSA accelerator drivers.) This corresponds to the behavior of Mbed TLS 3.x when `MBEDTLS_USE_PSA_CRYPTO` is enabled. In effect, `MBEDTLS_USE_PSA_CRYPTO` is now always enabled. +The X.509, PKCS7 and SSL modules always use PSA for cryptography, with a few exceptions documented in the [PSA limitations](architecture/psa-migration/psa-limitations.md) document. (These limitations are mostly transparent unless you want to leverage PSA accelerator drivers.) This corresponds to the behavior of Mbed TLS 3.x when `MBEDTLS_USE_PSA_CRYPTO` is enabled. In effect, `MBEDTLS_USE_PSA_CRYPTO` is now always enabled. `psa_crypto_init()` must be called before performing any cryptographic operation, including indirect requests such as parsing a key or certificate or starting a TLS handshake. From 66719098b872da4cb25728cd29ea11410155bbb0 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 10 Oct 2025 15:51:17 +0200 Subject: [PATCH 38/47] Ensure there is a blank line before headers (markdown portability) Signed-off-by: Gilles Peskine --- docs/4.0-migration-guide.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/4.0-migration-guide.md b/docs/4.0-migration-guide.md index 040194b478..16328ad028 100644 --- a/docs/4.0-migration-guide.md +++ b/docs/4.0-migration-guide.md @@ -211,6 +211,7 @@ If you integrate Mbed TLS with a platform or hardware drivers: - The PSA driver wrapper is now generated in TF-PSA-Crypto. - Platform-specific configuration are now handled in `crypto_config.h`. - See [Repository split](#repository-split) for how platform components moved to TF-PSA-Crypto. + ## Compile-time configuration ### Configuration file split @@ -255,6 +256,7 @@ The option to enable null cipher suites in TLS 1.2 has been renamed from `MBEDTL #### Removal of backward compatibility options The option `MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT` has been removed. Only the version standardized in RFC 9146 is supported now. + ## PSA as the only cryptography API The PSA API is now the only API for cryptographic primitives. @@ -278,6 +280,7 @@ See also [function prototype changes](#function-prototype-changes), many of whic ### Impact on the library configuration Mbed TLS follows the configuration of TF-PSA-Crypto with respect to cryptographic mechanisms. They are now based on `PSA_WANT_xxx` macros instead of legacy configuration macros such as `MBEDTLS_RSA_C`, `MBEDTLS_PKCS1_V15`, etc. The configuration of X.509 and TLS is not directly affected by the configuration. However, applications and middleware that rely on these configuration symbols to know which cryptographic mechanisms to support will need to migrate to `PSA_WANT_xxx` macros. For more information, consult the PSA transition guide in TF-PSA-Crypto. + ## Private declarations Since Mbed TLS 3.0, some things that are declared in a public header are not part of the stable application programming interface (API), but instead are considered private. Private elements may be removed or may have their semantics changed in a future minor release without notice. @@ -311,6 +314,7 @@ We strongly recommend against defining `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS` or may not compile or work with future minor releases. If there's something you want to do that you feel can only be achieved by using one of these two macros, please reach out on github or the mailing list. + ## Error codes ### Unified error code space @@ -348,6 +352,7 @@ Many legacy error codes have been removed in favor of PSA error codes. Generally | `MBEDTLS_ERR_X509_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` | See also the corresponding section in the TF-PSA-Crypto migration guide, which lists error codes from cryptography modules. + ## Removal of deprecated functions ### Removal of deprecated X.509 functions @@ -362,6 +367,7 @@ The function was superseded by `mbedtls_ssl_conf_groups()`. ### Removal of `compat-2.x.h` The header `compat-2.x.h`, containing some definitions for backward compatibility with Mbed TLS 2.x, has been removed. + ## Removed features ### Removal of obsolete key exchanges methods in (D)TLS 1.2 @@ -514,6 +520,7 @@ Following their removal from the crypto library, elliptic curves of less than 25 The deprecated functions `mbedtls_ssl_conf_min_version()` and `mbedtls_ssl_conf_max_version()`, and the associated constants `MBEDTLS_SSL_MAJOR_VERSION_3`, `MBEDTLS_SSL_MINOR_VERSION_3` and `MBEDTLS_SSL_MINOR_VERSION_4` have been removed. Use `mbedtls_ssl_conf_min_tls_version()` and `mbedtls_ssl_conf_max_tls_version()` with `MBEDTLS_SSL_VERSION_TLS1_2` or `MBEDTLS_SSL_VERSION_TLS1_3` instead. The deprecated function `mbedtls_ssl_conf_sig_hashes()` has been removed. Use `mbedtls_ssl_conf_sig_algs()` instead. + ## Function prototype changes A number of existing functions now take a different list of arguments, mostly to migrate them to the PSA API. @@ -603,6 +610,7 @@ int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx, psa_algorithm_t alg, psa_key_type_t key_type, psa_key_bits_t key_bits, uint32_t lifetime); ``` + ## OID module The compilation option `MBEDTLS_OID_C` no longer exists. OID tables are included in the build automatically as needed for parsing and writing X.509 data. From d83c476f3b9d38890b86b2d3daee1fcf54e851a8 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 10 Oct 2025 16:36:42 +0200 Subject: [PATCH 39/47] Fix copypasta Signed-off-by: Gilles Peskine --- docs/4.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/4.0-migration-guide.md b/docs/4.0-migration-guide.md index 16328ad028..fa7732b8c6 100644 --- a/docs/4.0-migration-guide.md +++ b/docs/4.0-migration-guide.md @@ -1,6 +1,6 @@ # Migrating from Mbed TLS 3.x to TF-PSA-Crypto 1.0 -This guide details the steps required to migrate from Mbed TLS version 2.x to Mbed TLS version 3.0 or greater. Unlike normal releases, Mbed TLS 3.0 breaks compatibility with previous versions, so users, integrators and package maintainers might need to change their own code in order to make it work with Mbed TLS 3.0. +This guide details the steps required to migrate from Mbed TLS version 3.x to Mbed TLS version 4.0 or greater. Unlike normal releases, Mbed TLS 4.0 breaks compatibility with previous versions, so users, integrators and package maintainers might need to change their own code in order to make it work with Mbed TLS 4.0. Here's the list of breaking changes; each entry should help you answer these two questions: (1) am I affected? (2) if yes, what's my migration path? From 75a36bd9cdffc4778d2ef70c3ee44cd4aca973a3 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 10 Oct 2025 17:45:33 +0200 Subject: [PATCH 40/47] Fix copypasta in title Signed-off-by: Gilles Peskine --- docs/4.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/4.0-migration-guide.md b/docs/4.0-migration-guide.md index fa7732b8c6..ec4b8c9b8c 100644 --- a/docs/4.0-migration-guide.md +++ b/docs/4.0-migration-guide.md @@ -1,4 +1,4 @@ -# Migrating from Mbed TLS 3.x to TF-PSA-Crypto 1.0 +# Migrating from Mbed TLS 3.x to Mbed TLS 4.0 This guide details the steps required to migrate from Mbed TLS version 3.x to Mbed TLS version 4.0 or greater. Unlike normal releases, Mbed TLS 4.0 breaks compatibility with previous versions, so users, integrators and package maintainers might need to change their own code in order to make it work with Mbed TLS 4.0. From fa4e9461bd43866939f627ca6c4451df42575020 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 10 Oct 2025 17:54:00 +0200 Subject: [PATCH 41/47] Add sentence that was in 3.0 and is in TF-PSA-Crypto 1.0 Signed-off-by: Gilles Peskine --- docs/4.0-migration-guide.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/4.0-migration-guide.md b/docs/4.0-migration-guide.md index ec4b8c9b8c..9b4768a3a1 100644 --- a/docs/4.0-migration-guide.md +++ b/docs/4.0-migration-guide.md @@ -4,6 +4,8 @@ This guide details the steps required to migrate from Mbed TLS version 3.x to Mb Here's the list of breaking changes; each entry should help you answer these two questions: (1) am I affected? (2) if yes, what's my migration path? +The changes are detailed below. Here is a summary of the main points: + - Mbed TLS has been split between two products: TF-PSA-Crypto for cryptography, and Mbed TLS for X.509 and (D)TLS. - CMake is now the only supported build system. - The cryptography API is now mostly the PSA API: most legacy cryptography APIs have been removed. This has led to adaptations in some X.509 and TLS APIs, notably because the library always uses the PSA random generator. From 65c29f07c7931cd97ad23ea7a664b6fed5f7b93c Mon Sep 17 00:00:00 2001 From: Minos Galanakis Date: Sat, 11 Oct 2025 21:44:26 +0100 Subject: [PATCH 42/47] Updated framework submodule Signed-off-by: Minos Galanakis --- framework | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework b/framework index d80c4f9ec3..4579964747 160000 --- a/framework +++ b/framework @@ -1 +1 @@ -Subproject commit d80c4f9ec3a01c001778658023f82e40fdb51d40 +Subproject commit 457996474728cb8e968ed21953b72f74d2f536b2 From 21cd2ddb1e7cd89f01abe9dc426ef2584a1df8bf Mon Sep 17 00:00:00 2001 From: Minos Galanakis Date: Sat, 11 Oct 2025 21:44:44 +0100 Subject: [PATCH 43/47] Updated tf psa-crypto submodule Signed-off-by: Minos Galanakis --- tf-psa-crypto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tf-psa-crypto b/tf-psa-crypto index cf4c26de94..76920edddc 160000 --- a/tf-psa-crypto +++ b/tf-psa-crypto @@ -1 +1 @@ -Subproject commit cf4c26de948e8bfe6566dd8b78299df4b627127d +Subproject commit 76920edddcad00ac41b248e12d937b845df7bedb From e5862c04940b07a7c4f871e63715fcce00bf14a3 Mon Sep 17 00:00:00 2001 From: Minos Galanakis Date: Sat, 11 Oct 2025 21:52:07 +0100 Subject: [PATCH 44/47] Removed Beta Changelog Signed-off-by: Minos Galanakis --- ChangeLog | 325 ------------------------------------------------------ 1 file changed, 325 deletions(-) diff --git a/ChangeLog b/ChangeLog index 912a1786b7..1c48958e39 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,330 +1,5 @@ Mbed TLS ChangeLog (Sorted per branch, date) -= Mbed TLS 4.0.0-beta branch released 2025-07-04 - -API changes - * The experimental functions psa_generate_key_ext() and - psa_key_derivation_output_key_ext() have been replaced by - psa_generate_key_custom() and psa_key_derivation_output_key_custom(). - They have almost exactly the same interface, but the variable-length - data is passed in a separate parameter instead of a flexible array - member. This resolves a build failure under C++ compilers that do not - support flexible array members (a C99 feature not adopted by C++). - Fixes #9020. - * Align the mbedtls_ssl_ticket_setup() function with the PSA Crypto API. - Instead of taking a mbedtls_cipher_type_t as an argument, this function - now takes 3 new arguments: a PSA algorithm, key type and key size, to - specify the AEAD for ticket protection. - * The PSA and Mbed TLS error spaces are now unified. mbedtls_xxx() - functions can now return PSA_ERROR_xxx values. - There is no longer a distinction between "low-level" and "high-level" - Mbed TLS error codes. - This will not affect most applications since the error values are - between -32767 and -1 as before. - * All API functions now use the PSA random generator psa_generate_random() - internally. As a consequence, functions no longer take RNG parameters. - Please refer to the migration guide at : - tf-psa-crypto/docs/4.0-migration-guide.md. - -Default behavior changes - * In a PSA-client-only build (i.e. MBEDTLS_PSA_CRYPTO_CLIENT && - !MBEDTLS_PSA_CRYPTO_C), do not automatically enable local crypto when the - corresponding PSA mechanism is enabled, since the server provides the - crypto. Fixes #9126. - * The PK, X.509, PKCS7 and TLS modules now always use the PSA subsystem - to perform cryptographic operations, with a few exceptions documented - in docs/architecture/psa-migration/psa-limitations.md. This - corresponds to the behavior of Mbed TLS 3.x when - MBEDTLS_USE_PSA_CRYPTO is enabled. In effect, MBEDTLS_USE_PSA_CRYPTO - is now always enabled. - * psa_crypto_init() must be called before performing any cryptographic - operation, including indirect requests such as parsing a key or - certificate or starting a TLS handshake. - * The `PSA_WANT_XXX` symbols as defined in - tf-psa-crypto/include/psa/crypto_config.h are now always used in the - configuration of the cryptographic mechanisms exposed by the PSA API. - This corresponds to the configuration behavior of Mbed TLS 3.x when - MBEDTLS_PSA_CRYPTO_CONFIG is enabled. In effect, MBEDTLS_PSA_CRYPTO_CONFIG - is now always enabled and the configuration option has been removed. - * In TLS clients, if mbedtls_ssl_set_hostname() has not been called, - mbedtls_ssl_handshake() now fails with - MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME - if certificate-based authentication of the server is attempted. - This is because authenticating a server without knowing what name - to expect is usually insecure. - -Removals - * Drop support for VIA Padlock. Removes MBEDTLS_PADLOCK_C. - Fixes #5903. - * Drop support for crypto alt interface. Removes MBEDTLS_XXX_ALT options - at the module and function level for crypto mechanisms only. The remaining - alt interfaces for platform, threading and timing are unchanged. - Fixes #8149. - * Remove support for the RSA-PSK key exchange in TLS 1.2. - * Remove deprecated mbedtls_x509write_crt_set_serial(). The function was - already deprecated and superseded by - mbedtls_x509write_crt_set_serial_raw(). - * Remove the function mbedtls_ssl_conf_curves() which had been deprecated - in favour of mbedtls_ssl_conf_groups() since Mbed TLS 3.1. - * Remove support for the DHE-PSK key exchange in TLS 1.2. - * Remove support for the DHE-RSA key exchange in TLS 1.2. - * Following the removal of DHM module (#9972 and TF-PSA-Crypto#175) the - following SSL functions are removed: - - mbedtls_ssl_conf_dh_param_bin - - mbedtls_ssl_conf_dh_param_ctx - - mbedtls_ssl_conf_dhm_min_bitlen - * Remove support for the RSA key exchange in TLS 1.2. - * Remove mbedtls_low_level_strerr() and mbedtls_high_level_strerr(), - since these concepts no longer exists. There is just mbedtls_strerror(). - * Sample programs for the legacy crypto API have been removed. - pkey/rsa_genkey.c - pkey/pk_decrypt.c - pkey/dh_genprime.c - pkey/rsa_verify.c - pkey/mpi_demo.c - pkey/rsa_decrypt.c - pkey/key_app.c - pkey/dh_server.c - pkey/ecdh_curve25519.c - pkey/pk_encrypt.c - pkey/rsa_sign.c - pkey/key_app_writer.c - pkey/dh_client.c - pkey/ecdsa.c - pkey/rsa_encrypt.c - wince_main.c - aes/crypt_and_hash.c - random/gen_random_ctr_drbg.c - random/gen_entropy.c - hash/md_hmac_demo.c - hash/hello.c - hash/generic_sum.c - cipher/cipher_aead_demo.c - * Remove compat-2-x.h header from mbedtls. - * The library no longer offers interfaces to look up values by OID - or OID by enum values. - The header now only defines functions to convert - between binary and dotted string OID representations, and macros - for OID strings that are relevant to X.509. - The compilation option MBEDTLS_OID_C no longer - exists. OID tables are included in the build automatically as needed. - -Features - * When the new compilation option MBEDTLS_PSA_KEY_STORE_DYNAMIC is enabled, - the number of volatile PSA keys is virtually unlimited, at the expense - of increased code size. This option is off by default, but enabled in - the default mbedtls_config.h. Fixes #9216. - * Add a new psa_key_agreement() PSA API to perform key agreement and return - an identifier for the newly created key. - * Added new configuration option MBEDTLS_PSA_STATIC_KEY_SLOTS, which - uses static storage for keys, enabling malloc-less use of key slots. - The size of each buffer is given by the option - MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE. By default it accommodates the - largest PSA key enabled in the build. - * Add an interruptible version of key agreement to the PSA interface. - See psa_key_agreement_iop_setup() and related functions. - * Add an interruptible version of generate key to the PSA interface. - See psa_generate_key_iop_setup() and related functions. - * Add the function mbedtls_ssl_export_keying_material() which allows the - client and server to extract additional shared symmetric keys from an SSL - session, according to the TLS-Exporter specification in RFC 8446 and 5705. - This requires MBEDTLS_SSL_KEYING_MATERIAL_EXPORT to be defined in - mbedtls_config.h. - -Security - * Unlike previously documented, enabling MBEDTLS_PSA_HMAC_DRBG_MD_TYPE does - not cause the PSA subsystem to use HMAC_DRBG: it uses HMAC_DRBG only when - MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG and MBEDTLS_CTR_DRBG_C are disabled. - CVE-2024-45157 - * Fix a stack buffer overflow in mbedtls_ecdsa_der_to_raw() and - mbedtls_ecdsa_raw_to_der() when the bits parameter is larger than the - largest supported curve. In some configurations with PSA disabled, - all values of bits are affected. This never happens in internal library - calls, but can affect applications that call these functions directly. - CVE-2024-45158 - * With TLS 1.3, when a server enables optional authentication of the - client, if the client-provided certificate does not have appropriate values - in keyUsage or extKeyUsage extensions, then the return value of - mbedtls_ssl_get_verify_result() would incorrectly have the - MBEDTLS_X509_BADCERT_KEY_USAGE and MBEDTLS_X509_BADCERT_EXT_KEY_USAGE bits - clear. As a result, an attacker that had a certificate valid for uses other - than TLS client authentication could be able to use it for TLS client - authentication anyway. Only TLS 1.3 servers were affected, and only with - optional authentication (required would abort the handshake with a fatal - alert). - CVE-2024-45159 - * Fix a buffer underrun in mbedtls_pk_write_key_der() when - called on an opaque key, MBEDTLS_USE_PSA_CRYPTO is enabled, - and the output buffer is smaller than the actual output. - Fix a related buffer underrun in mbedtls_pk_write_key_pem() - when called on an opaque RSA key, MBEDTLS_USE_PSA_CRYPTO is enabled - and MBEDTLS_MPI_MAX_SIZE is smaller than needed for a 4096-bit RSA key. - CVE-2024-49195 - * Note that TLS clients should generally call mbedtls_ssl_set_hostname() - if they use certificate authentication (i.e. not pre-shared keys). - Otherwise, in many scenarios, the server could be impersonated. - The library will now prevent the handshake and return - MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME - if mbedtls_ssl_set_hostname() has not been called. - Reported by Daniel Stenberg. - CVE-2025-27809 - * Fix a vulnerability in the TLS 1.2 handshake. If memory allocation failed - or there was a cryptographic hardware failure when calculating the - Finished message, it could be calculated incorrectly. This would break - the security guarantees of the TLS handshake. - CVE-2025-27810 - * Fix possible use-after-free or double-free in code calling - mbedtls_x509_string_to_names(). This was caused by the function calling - mbedtls_asn1_free_named_data_list() on its head argument, while the - documentation did no suggest it did, making it likely for callers relying - on the documented behaviour to still hold pointers to memory blocks after - they were free()d, resulting in high risk of use-after-free or double-free, - with consequences ranging up to arbitrary code execution. - In particular, the two sample programs x509/cert_write and x509/cert_req - were affected (use-after-free if the san string contains more than one DN). - Code that does not call mbedtls_string_to_names() directly is not affected. - Found by Linh Le and Ngan Nguyen from Calif. - CVE-2025-47917 - * Fix a bug in mbedtls_x509_string_to_names() and the - mbedtls_x509write_{crt,csr}_set_{subject,issuer}_name() functions, - where some inputs would cause an inconsistent state to be reached, causing - a NULL dereference either in the function itself, or in subsequent - users of the output structure, such as mbedtls_x509_write_names(). This - only affects applications that create (as opposed to consume) X.509 - certificates, CSRs or CRLs. Found by Linh Le and Ngan Nguyen from Calif. - CVE-2025-48965 - -Bugfix - * Fix TLS 1.3 client build and runtime when support for session tickets is - disabled (MBEDTLS_SSL_SESSION_TICKETS configuration option). Fixes #6395. - * Fix compilation error when memcpy() is a function-like macros. Fixes #8994. - * MBEDTLS_ASN1_PARSE_C and MBEDTLS_ASN1_WRITE_C are now automatically enabled - as soon as MBEDTLS_RSA_C is enabled. Fixes #9041. - * Fix undefined behaviour (incrementing a NULL pointer by zero length) when - passing in zero length additional data to multipart AEAD. - * Fix rare concurrent access bug where attempting to operate on a - non-existent key while concurrently creating a new key could potentially - corrupt the key store. - * Fix error handling when creating a key in a dynamic secure element - (feature enabled by MBEDTLS_PSA_CRYPTO_SE_C). In a low memory condition, - the creation could return PSA_SUCCESS but using or destroying the key - would not work. Fixes #8537. - * Fix issue of redefinition warning messages for _GNU_SOURCE in - entropy_poll.c and sha_256.c. There was a build warning during - building for linux platform. - Resolves #9026 - * Fix a compilation warning in pk.c when PSA is enabled and RSA is disabled. - * Fix the build when MBEDTLS_PSA_CRYPTO_CONFIG is enabled and the built-in - CMAC is enabled, but no built-in unauthenticated cipher is enabled. - Fixes #9209. - * Fix redefinition warnings when SECP192R1 and/or SECP192K1 are disabled. - Fixes #9029. - * Fix psa_cipher_decrypt() with CCM* rejecting messages less than 3 bytes - long. Credit to Cryptofuzz. Fixes #9314. - * Fix interference between PSA volatile keys and built-in keys - when MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS is enabled and - MBEDTLS_PSA_KEY_SLOT_COUNT is more than 4096. - * Document and enforce the limitation of mbedtls_psa_register_se_key() - to persistent keys. Resolves #9253. - * Fix Clang compilation error when MBEDTLS_USE_PSA_CRYPTO is enabled - but MBEDTLS_DHM_C is disabled. Reported by Michael Schuster in #9188. - * Fix server mode only build when MBEDTLS_SSL_SRV_C is enabled but - MBEDTLS_SSL_CLI_C is disabled. Reported by M-Bab on GitHub in #9186. - * When MBEDTLS_PSA_CRYPTO_C was disabled and MBEDTLS_ECDSA_C enabled, - some code was defining 0-size arrays, resulting in compilation errors. - Fixed by disabling the offending code in configurations without PSA - Crypto, where it never worked. Fixes #9311. - * Fixes an issue where some TLS 1.2 clients could not connect to an - Mbed TLS 3.6.0 server, due to incorrect handling of - legacy_compression_methods in the ClientHello. - fixes #8995, #9243. - * Fix a memory leak that could occur when failing to process an RSA - key through some PSA functions due to low memory conditions. - * Fixed a regression introduced in 3.6.0 where the CA callback set with - mbedtls_ssl_conf_ca_cb() would stop working when connections were - upgraded to TLS 1.3. Fixed by adding support for the CA callback with TLS - 1.3. - * Fixed a regression introduced in 3.6.0 where clients that relied on - optional/none authentication mode, by calling mbedtls_ssl_conf_authmode() - with MBEDTLS_SSL_VERIFY_OPTIONAL or MBEDTLS_SSL_VERIFY_NONE, would stop - working when connections were upgraded to TLS 1.3. Fixed by adding - support for optional/none with TLS 1.3 as well. Note that the TLS 1.3 - standard makes server authentication mandatory; users are advised not to - use authmode none, and to carefully check the results when using optional - mode. - * Fixed a regression introduced in 3.6.0 where context-specific certificate - verify callbacks, set with mbedtls_ssl_set_verify() as opposed to - mbedtls_ssl_conf_verify(), would stop working when connections were - upgraded to TLS 1.3. Fixed by adding support for context-specific verify - callback in TLS 1.3. - * Fix unintended performance regression when using short RSA public keys. - Fixes #9232. - * When MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE is disabled, work with - peers that have middlebox compatibility enabled, as long as no - problematic middlebox is in the way. Fixes #9551. - * Fix invalid JSON schemas for driver descriptions used by - generate_driver_wrappers.py. - * Use 'mbedtls_net_close' instead of 'close' in 'mbedtls_net_bind' - and 'mbedtls_net_connect' to prevent possible double close fd - problems. Fixes #9711. - * Fix undefined behavior in some cases when mbedtls_psa_raw_to_der() or - mbedtls_psa_der_to_raw() is called with bits=0. - * Fix compilation on MS-DOS DJGPP. Fixes #9813. - * Fix missing constraints on the AES-NI inline assembly which is used on - GCC-like compilers when building AES for generic x86_64 targets. This - may have resulted in incorrect code with some compilers, depending on - optimizations. Fixes #9819. - * Support re-assembly of fragmented handshake messages in TLS (both - 1.2 and 1.3). The lack of support was causing handshake failures with - some servers, especially with TLS 1.3 in practice. There are a few - limitations, notably a fragmented ClientHello is only supported when - TLS 1.3 support is enabled. See the documentation of - mbedtls_ssl_handshake() for details. - * Fix definition of MBEDTLS_PRINTF_SIZET to prevent runtime crashes that - occurred whenever SSL debugging was enabled on a copy of Mbed TLS built - with Visual Studio 2013 or MinGW. - Fixes #10017. - * Silence spurious -Wunterminated-string-initialization warnings introduced - by GCC 15. Fixes #9944. - -Changes - * Warn if mbedtls/check_config.h is included manually, as this can - lead to spurious errors. Error if a *adjust*.h header is included - manually, as this can lead to silently inconsistent configurations, - potentially resulting in buffer overflows. - When migrating from Mbed TLS 2.x, if you had a custom config.h that - included check_config.h, remove this inclusion from the Mbed TLS 3.x - configuration file (renamed to mbedtls_config.h). This change was made - in Mbed TLS 3.0, but was not announced in a changelog entry at the time. - * Functions regarding numeric string conversions for OIDs have been moved - from the OID module and now reside in X.509 module. This helps to reduce - the code size as these functions are not commonly used outside of X.509. - * Improve performance of PSA key generation with ECC keys: it no longer - computes the public key (which was immediately discarded). Fixes #9732. - * Cryptography and platform configuration options have been migrated - from the Mbed TLS library configuration file mbedtls_config.h to - crypto_config.h that will become the TF-PSA-Crypto configuration file, - see config-split.md for more information. The reference and test custom - configuration files respectively in configs/ and tests/configs/ have - been updated accordingly. - To migrate custom Mbed TLS configurations where - MBEDTLS_PSA_CRYPTO_CONFIG is disabled, you should first adapt them - to the PSA configuration scheme based on PSA_WANT_XXX symbols - (see psa-conditional-inclusion-c.md for more information). - To migrate custom Mbed TLS configurations where - MBEDTLS_PSA_CRYPTO_CONFIG is enabled, you should migrate the - cryptographic and platform configuration options from mbedtls_config.h - to crypto_config.h (see config-split.md for more information and configs/ - for examples). - * Move the crypto part of the library (content of tf-psa-crypto directory) - from the Mbed TLS to the TF-PSA-Crypto repository. The crypto code and - tests development will now occur in TF-PSA-Crypto, which Mbed TLS - references as a Git submodule. - * The function mbedtls_x509_string_to_names() now requires its head argument - to point to NULL on entry. This makes it likely that existing risky uses of - this function (see the entry in the Security section) will be detected and - fixed. - = Mbed TLS 3.6.0 branch released 2024-03-28 API changes From 38181b6d667e579586b775bb7a00f12ee1358699 Mon Sep 17 00:00:00 2001 From: Minos Galanakis Date: Sat, 11 Oct 2025 21:53:21 +0100 Subject: [PATCH 45/47] Assemble ChangeLog Signed-off-by: Minos Galanakis --- ChangeLog | 256 ++++++++++++++++++ ChangeLog.d/10285.txt | 3 - ChangeLog.d/9684.txt | 2 - ChangeLog.d/9685.txt | 2 - ChangeLog.d/9874.txt | 5 - ChangeLog.d/9892.txt | 5 - ChangeLog.d/9956.txt | 6 - ChangeLog.d/9964.txt | 26 -- ChangeLog.d/add-tls-exporter.txt | 6 - ChangeLog.d/check_config.txt | 5 - ChangeLog.d/error-unification.txt | 12 - ChangeLog.d/fix-asn1-store-named-data.txt | 8 - .../fix-clang-psa-build-without-dhm.txt | 5 - ...ion-when-memcpy-is-function-like-macro.txt | 2 - ChangeLog.d/fix-compilation-with-djgpp.txt | 2 - .../fix-dependency-on-generated-files.txt | 3 - ChangeLog.d/fix-legacy-compression-issue.txt | 6 - .../fix-msvc-version-guard-format-zu.txt | 5 - ChangeLog.d/fix-server-mode-only-build.txt | 3 - .../fix-string-to-names-memory-management.txt | 19 -- .../fix-string-to-names-store-named-data.txt | 10 - .../fix_reporting_of_key_usage_issues.txt | 12 - ChangeLog.d/make-visualc.txt | 2 - ChangeLog.d/mbedtls-ssl-null-ciphersuites.txt | 4 - .../mbedtls_ssl_conf_alpn_protocols.txt | 4 - ChangeLog.d/mbedtls_ssl_set_hostname.txt | 18 -- ChangeLog.d/oid.txt | 8 - ChangeLog.d/psa-always-on.txt | 11 - ChangeLog.d/removal-of-rng.txt | 6 - ChangeLog.d/remove-compat-2.x.txt | 2 - ChangeLog.d/remove-deprecated-items.txt | 11 - ChangeLog.d/remove_RSA_key_exchange.txt | 2 - ChangeLog.d/remove_mbedtls_pk_type.txt | 3 - .../replace-close-with-mbedtls_net_close.txt | 4 - ChangeLog.d/replace_time_t.txt | 4 - ChangeLog.d/repo-split.txt | 5 - ChangeLog.d/rm-ssl-conf-curves.txt | 4 - ChangeLog.d/runtime-version-interface.txt | 9 - ChangeLog.d/secp256k1-removal.txt | 3 - ...ring-conversions-out-of-the-oid-module.txt | 4 - ChangeLog.d/static-ecdh-removal.txt | 3 - ChangeLog.d/tls-hs-defrag-in.txt | 7 - ChangeLog.d/tls-key-exchange-rsa.txt | 2 - ChangeLog.d/tls12-check-finished-calc.txt | 6 - ChangeLog.d/tls13-cert-regressions.txt | 18 -- .../tls13-middlebox-compat-disabled.txt | 4 - ChangeLog.d/tls13-without-tickets.txt | 3 - ChangeLog.d/unify-errors.txt | 7 - .../unterminated-string-initialization.txt | 3 - ...x509write_crt_set_serial_raw-alignment.txt | 3 - 50 files changed, 256 insertions(+), 307 deletions(-) delete mode 100644 ChangeLog.d/10285.txt delete mode 100644 ChangeLog.d/9684.txt delete mode 100644 ChangeLog.d/9685.txt delete mode 100644 ChangeLog.d/9874.txt delete mode 100644 ChangeLog.d/9892.txt delete mode 100644 ChangeLog.d/9956.txt delete mode 100644 ChangeLog.d/9964.txt delete mode 100644 ChangeLog.d/add-tls-exporter.txt delete mode 100644 ChangeLog.d/check_config.txt delete mode 100644 ChangeLog.d/error-unification.txt delete mode 100644 ChangeLog.d/fix-asn1-store-named-data.txt delete mode 100644 ChangeLog.d/fix-clang-psa-build-without-dhm.txt delete mode 100644 ChangeLog.d/fix-compilation-when-memcpy-is-function-like-macro.txt delete mode 100644 ChangeLog.d/fix-compilation-with-djgpp.txt delete mode 100644 ChangeLog.d/fix-dependency-on-generated-files.txt delete mode 100644 ChangeLog.d/fix-legacy-compression-issue.txt delete mode 100644 ChangeLog.d/fix-msvc-version-guard-format-zu.txt delete mode 100644 ChangeLog.d/fix-server-mode-only-build.txt delete mode 100644 ChangeLog.d/fix-string-to-names-memory-management.txt delete mode 100644 ChangeLog.d/fix-string-to-names-store-named-data.txt delete mode 100644 ChangeLog.d/fix_reporting_of_key_usage_issues.txt delete mode 100644 ChangeLog.d/make-visualc.txt delete mode 100644 ChangeLog.d/mbedtls-ssl-null-ciphersuites.txt delete mode 100644 ChangeLog.d/mbedtls_ssl_conf_alpn_protocols.txt delete mode 100644 ChangeLog.d/mbedtls_ssl_set_hostname.txt delete mode 100644 ChangeLog.d/oid.txt delete mode 100644 ChangeLog.d/psa-always-on.txt delete mode 100644 ChangeLog.d/removal-of-rng.txt delete mode 100644 ChangeLog.d/remove-compat-2.x.txt delete mode 100644 ChangeLog.d/remove-deprecated-items.txt delete mode 100644 ChangeLog.d/remove_RSA_key_exchange.txt delete mode 100644 ChangeLog.d/remove_mbedtls_pk_type.txt delete mode 100644 ChangeLog.d/replace-close-with-mbedtls_net_close.txt delete mode 100644 ChangeLog.d/replace_time_t.txt delete mode 100644 ChangeLog.d/repo-split.txt delete mode 100644 ChangeLog.d/rm-ssl-conf-curves.txt delete mode 100644 ChangeLog.d/runtime-version-interface.txt delete mode 100644 ChangeLog.d/secp256k1-removal.txt delete mode 100644 ChangeLog.d/split-numeric-string-conversions-out-of-the-oid-module.txt delete mode 100644 ChangeLog.d/static-ecdh-removal.txt delete mode 100644 ChangeLog.d/tls-hs-defrag-in.txt delete mode 100644 ChangeLog.d/tls-key-exchange-rsa.txt delete mode 100644 ChangeLog.d/tls12-check-finished-calc.txt delete mode 100644 ChangeLog.d/tls13-cert-regressions.txt delete mode 100644 ChangeLog.d/tls13-middlebox-compat-disabled.txt delete mode 100644 ChangeLog.d/tls13-without-tickets.txt delete mode 100644 ChangeLog.d/unify-errors.txt delete mode 100644 ChangeLog.d/unterminated-string-initialization.txt delete mode 100644 ChangeLog.d/x509write_crt_set_serial_raw-alignment.txt diff --git a/ChangeLog b/ChangeLog index 1c48958e39..d31ada506f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,261 @@ Mbed TLS ChangeLog (Sorted per branch, date) += Mbed TLS 4.0.0 branch released 2025-10-15 + +API changes + * Align the mbedtls_ssl_ticket_setup() function with the PSA Crypto API. + Instead of taking a mbedtls_cipher_type_t as an argument, this function + now takes 3 new arguments: a PSA algorithm, key type and key size, to + specify the AEAD for ticket protection. + * The PSA and Mbed TLS error spaces are now unified. mbedtls_xxx() + functions can now return PSA_ERROR_xxx values. + There is no longer a distinction between "low-level" and "high-level" + Mbed TLS error codes. + This will not affect most applications since the error values are + between -32767 and -1 as before. + * All API functions now use the PSA random generator psa_generate_random() + internally. As a consequence, functions no longer take RNG parameters. + Please refer to the migration guide at : + docs/4.0-migration-guide.md. + * The list passed to mbedtls_ssl_conf_alpn_protocols() is now declared + as having const elements, reflecting the fact that the library will + not modify it + * Change the serial argument of the mbedtls_x509write_crt_set_serial_raw + function to a const to align with the rest of the API. + * Change the signature of the runtime version information methods that took + a char* as an argument to take zero arguments and return a const char* + instead. This aligns us with the interface used in TF PSA Crypto 1.0. + If you need to support linking against both Mbed TLS 3.x and 4.x, please + use the build-time version macros or mbedtls_version_get_number() to + determine the correct signature for mbedtls_version_get_string() and + mbedtls_version_get_string_full() before calling them. + Fixes issue #10308. + * Make the following error codes aliases of their PSA equivalents, where + xxx is a module, e.g. X509 or SSL. + MBEDTLS_ERR_xxx_BAD_INPUT_DATA -> PSA_ERROR_INVALID_ARGUMENT + MBEDTLS_ERR_xxx_ALLOC_FAILED -> PSA_ERROR_INSUFFICIENT_MEMORY + MBEDTLS_ERR_xxx_BUFFER_TOO_SMALL -> PSA_ERROR_BUFFER_TOO_SMALL + MBEDTLS_ERR_PKCS7_VERIFY_FAIL -> PSA_ERROR_INVALID_SIGNATURE + * Add MBEDTLS_SSL_NULL_CIPHERSUITES configuration option. It enables + TLS 1.2 ciphersuites without encryption and is disabled by default. + This new option replaces MBEDTLS_CIPHER_NULL_CIPHER. + +Default behavior changes + * The X.509 and TLS modules now always use the PSA subsystem + to perform cryptographic operations, with a few exceptions documented + in docs/architecture/psa-migration/psa-limitations.md. This + corresponds to the behavior of Mbed TLS 3.x when + MBEDTLS_USE_PSA_CRYPTO is enabled. In effect, MBEDTLS_USE_PSA_CRYPTO + is now always enabled. + * psa_crypto_init() must be called before performing any cryptographic + operation, including indirect requests such as parsing a key or + certificate or starting a TLS handshake. + * In TLS clients, if mbedtls_ssl_set_hostname() has not been called, + mbedtls_ssl_handshake() now fails with + MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME + if certificate-based authentication of the server is attempted. + This is because authenticating a server without knowing what name + to expect is usually insecure. + +Removals + * Remove support for the RSA-PSK key exchange in TLS 1.2. + * Remove deprecated mbedtls_x509write_crt_set_serial(). The function was + already deprecated and superseded by + mbedtls_x509write_crt_set_serial_raw(). + * Remove the function mbedtls_ssl_conf_curves() which had been deprecated + in favour of mbedtls_ssl_conf_groups() since Mbed TLS 3.1. + * Remove support for the DHE-PSK key exchange in TLS 1.2. + * Remove support for the DHE-RSA key exchange in TLS 1.2. + * Following the removal of DHM module (#9972 and TF-PSA-Crypto#175) the + following SSL functions are removed: + - mbedtls_ssl_conf_dh_param_bin + - mbedtls_ssl_conf_dh_param_ctx + - mbedtls_ssl_conf_dhm_min_bitlen + * Remove support for the RSA key exchange in TLS 1.2. + * Remove mbedtls_low_level_strerr() and mbedtls_high_level_strerr(), + since these concepts no longer exists. There is just mbedtls_strerror(). + * Sample programs for the legacy crypto API have been removed. + pkey/rsa_genkey.c + pkey/pk_decrypt.c + pkey/dh_genprime.c + pkey/rsa_verify.c + pkey/mpi_demo.c + pkey/rsa_decrypt.c + pkey/key_app.c + pkey/dh_server.c + pkey/ecdh_curve25519.c + pkey/pk_encrypt.c + pkey/rsa_sign.c + pkey/key_app_writer.c + pkey/dh_client.c + pkey/ecdsa.c + pkey/rsa_encrypt.c + wince_main.c + aes/crypt_and_hash.c + random/gen_random_ctr_drbg.c + random/gen_entropy.c + hash/md_hmac_demo.c + hash/hello.c + hash/generic_sum.c + cipher/cipher_aead_demo.c + * Remove compat-2-x.h header from mbedtls. + * The library no longer offers interfaces to look up values by OID + or OID by enum values. + The header now only defines functions to convert + between binary and dotted string OID representations, and macros + for OID strings that are relevant to X.509. + The compilation option MBEDTLS_OID_C no longer + exists. OID tables are included in the build automatically as needed. + * The header no longer exists. Including it + from a custom config file was no longer needed since Mbed TLS 3.0, + and could lead to spurious errors. The checks that it performed are + now done automatically when building the library. + * Support for secp192k1, secp192r1, secp224k1 and secp224r1 EC curves is + removed from TLS. + * Remove mbedtls_pk_type_t from the public interface and replace it with + mbedtls_pk_sigalg_t. + * Remove MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT. Now only the + standard version (defined in RFC 9146) of DTLS connection ID is supported. + * Remove mbedtls_ssl_conf_min_version(), mbedtls_ssl_conf_max_version(), and + the associated constants MBEDTLS_SSL_MAJOR_VERSION_x and + MBEDTLS_SSL_MINOR_VERSION_y. Use mbedtls_ssl_conf_min_tls_version() and + mbedtls_ssl_conf_max_tls_version() with MBEDTLS_SSL_VERSION_TLS1_y instead. + Note that the new names of the new constants use the TLS protocol versions, + unlike the old constants whose names are based on internal encodings. + * Remove mbedtls_ssl_conf_sig_hashes(). Use mbedtls_ssl_conf_sig_algs() + instead. + * Removed all public key sample programs from the programs/pkey + directory. + * Removed support for TLS 1.2 static ECDH key + exchanges (ECDH-ECDSA and ECDH-RSA). + * Drop support for the GNU Make and Microsoft Visual Studio build systems. + +Features + * Add the function mbedtls_ssl_export_keying_material() which allows the + client and server to extract additional shared symmetric keys from an SSL + session, according to the TLS-Exporter specification in RFC 8446 and 5705. + This requires MBEDTLS_SSL_KEYING_MATERIAL_EXPORT to be defined in + mbedtls_config.h. + +Security + * With TLS 1.3, when a server enables optional authentication of the + client, if the client-provided certificate does not have appropriate values + in keyUsage or extKeyUsage extensions, then the return value of + mbedtls_ssl_get_verify_result() would incorrectly have the + MBEDTLS_X509_BADCERT_KEY_USAGE and MBEDTLS_X509_BADCERT_EXT_KEY_USAGE bits + clear. As a result, an attacker that had a certificate valid for uses other + than TLS client authentication could be able to use it for TLS client + authentication anyway. Only TLS 1.3 servers were affected, and only with + optional authentication (required would abort the handshake with a fatal + alert). + CVE-2024-45159 + * Note that TLS clients should generally call mbedtls_ssl_set_hostname() + if they use certificate authentication (i.e. not pre-shared keys). + Otherwise, in many scenarios, the server could be impersonated. + The library will now prevent the handshake and return + MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME + if mbedtls_ssl_set_hostname() has not been called. + Reported by Daniel Stenberg. + CVE-2025-27809 + * Fix a vulnerability in the TLS 1.2 handshake. If memory allocation failed + or there was a cryptographic hardware failure when calculating the + Finished message, it could be calculated incorrectly. This would break + the security guarantees of the TLS handshake. + CVE-2025-27810 + * Fix possible use-after-free or double-free in code calling + mbedtls_x509_string_to_names(). This was caused by the function calling + mbedtls_asn1_free_named_data_list() on its head argument, while the + documentation did no suggest it did, making it likely for callers relying + on the documented behaviour to still hold pointers to memory blocks after + they were free()d, resulting in high risk of use-after-free or double-free, + with consequences ranging up to arbitrary code execution. + In particular, the two sample programs x509/cert_write and x509/cert_req + were affected (use-after-free if the san string contains more than one DN). + Code that does not call mbedtls_string_to_names() directly is not affected. + Found by Linh Le and Ngan Nguyen from Calif. + CVE-2025-47917 + * Fix a bug in mbedtls_x509_string_to_names() and the + mbedtls_x509write_{crt,csr}_set_{subject,issuer}_name() functions, + where some inputs would cause an inconsistent state to be reached, causing + a NULL dereference either in the function itself, or in subsequent + users of the output structure, such as mbedtls_x509_write_names(). This + only affects applications that create (as opposed to consume) X.509 + certificates, CSRs or CRLs. Found by Linh Le and Ngan Nguyen from Calif. + CVE-2025-48965 + * Fix a bug in tf-psa-crypto's mbedtls_asn1_store_named_data() where it + would sometimes leave an item in the output list in an inconsistent + state with val.p == NULL but val.len > 0. Affected functions used in X.509 + would then dereference a NULL pointer. Applications that do not + call this function (directly, or indirectly through X.509 writing) are not + affected. Found by Linh Le and Ngan Nguyen from Calif. + +Bugfix + * Fix TLS 1.3 client build and runtime when support for session tickets is + disabled (MBEDTLS_SSL_SESSION_TICKETS configuration option). Fixes #6395. + * Fix compilation error when memcpy() is a function-like macros. Fixes #8994. + * Fix Clang compilation error when finite-field Diffie-Hellman is disabled. + Reported by Michael Schuster in #9188. + * Fix server mode only build when MBEDTLS_SSL_SRV_C is enabled but + MBEDTLS_SSL_CLI_C is disabled. Reported by M-Bab on GitHub in #9186. + * Fixes an issue where some TLS 1.2 clients could not connect to an + Mbed TLS 3.6.0 server, due to incorrect handling of + legacy_compression_methods in the ClientHello. + fixes #8995, #9243. + * Fixed a regression introduced in 3.6.0 where the CA callback set with + mbedtls_ssl_conf_ca_cb() would stop working when connections were + upgraded to TLS 1.3. Fixed by adding support for the CA callback with TLS + 1.3. + * Fixed a regression introduced in 3.6.0 where clients that relied on + optional/none authentication mode, by calling mbedtls_ssl_conf_authmode() + with MBEDTLS_SSL_VERIFY_OPTIONAL or MBEDTLS_SSL_VERIFY_NONE, would stop + working when connections were upgraded to TLS 1.3. Fixed by adding + support for optional/none with TLS 1.3 as well. Note that the TLS 1.3 + standard makes server authentication mandatory; users are advised not to + use authmode none, and to carefully check the results when using optional + mode. + * Fixed a regression introduced in 3.6.0 where context-specific certificate + verify callbacks, set with mbedtls_ssl_set_verify() as opposed to + mbedtls_ssl_conf_verify(), would stop working when connections were + upgraded to TLS 1.3. Fixed by adding support for context-specific verify + callback in TLS 1.3. + * When MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE is disabled, work with + peers that have middlebox compatibility enabled, as long as no + problematic middlebox is in the way. Fixes #9551. + * Use 'mbedtls_net_close' instead of 'close' in 'mbedtls_net_bind' + and 'mbedtls_net_connect' to prevent possible double close fd + problems. Fixes #9711. + * Fix compilation on MS-DOS DJGPP. Fixes #9813. + * Support re-assembly of fragmented handshake messages in TLS (both + 1.2 and 1.3). The lack of support was causing handshake failures with + some servers, especially with TLS 1.3 in practice. There are a few + limitations, notably a fragmented ClientHello is only supported when + TLS 1.3 support is enabled. See the documentation of + mbedtls_ssl_handshake() for details. + * Fix definition of MBEDTLS_PRINTF_SIZET to prevent runtime crashes that + occurred whenever SSL debugging was enabled on a copy of Mbed TLS built + with Visual Studio 2013 or MinGW. + Fixes #10017. + * Silence spurious -Wunterminated-string-initialization warnings introduced + by GCC 15. Fixes #9944. + * Fix potential CMake parallel build failure when building both the static + and shared libraries. + * Fix a build error or incorrect TLS session + lifetime on platforms where mbedtls_time_t + is not time_t. Fixes #10236. + +Changes + * Functions regarding numeric string conversions for OIDs have been moved + from the OID module and now reside in X.509 module. This helps to reduce + the code size as these functions are not commonly used outside of X.509. + * Move the crypto part of the library (content of tf-psa-crypto directory) + from the Mbed TLS to the TF-PSA-Crypto repository. The crypto code and + tests development will now occur in TF-PSA-Crypto, which Mbed TLS + references as a Git submodule. + * The function mbedtls_x509_string_to_names() now requires its head argument + to point to NULL on entry. This makes it likely that existing risky uses of + this function (see the entry in the Security section) will be detected and + fixed. + = Mbed TLS 3.6.0 branch released 2024-03-28 API changes diff --git a/ChangeLog.d/10285.txt b/ChangeLog.d/10285.txt deleted file mode 100644 index 2ac05ab90f..0000000000 --- a/ChangeLog.d/10285.txt +++ /dev/null @@ -1,3 +0,0 @@ -Removals - * Removed all public key sample programs from the programs/pkey - directory. diff --git a/ChangeLog.d/9684.txt b/ChangeLog.d/9684.txt deleted file mode 100644 index 115ded87a0..0000000000 --- a/ChangeLog.d/9684.txt +++ /dev/null @@ -1,2 +0,0 @@ -Removals - * Remove support for the DHE-PSK key exchange in TLS 1.2. diff --git a/ChangeLog.d/9685.txt b/ChangeLog.d/9685.txt deleted file mode 100644 index 9820aff759..0000000000 --- a/ChangeLog.d/9685.txt +++ /dev/null @@ -1,2 +0,0 @@ -Removals - * Remove support for the DHE-RSA key exchange in TLS 1.2. diff --git a/ChangeLog.d/9874.txt b/ChangeLog.d/9874.txt deleted file mode 100644 index a4d2e032ee..0000000000 --- a/ChangeLog.d/9874.txt +++ /dev/null @@ -1,5 +0,0 @@ -API changes - * Align the mbedtls_ssl_ticket_setup() function with the PSA Crypto API. - Instead of taking a mbedtls_cipher_type_t as an argument, this function - now takes 3 new arguments: a PSA algorithm, key type and key size, to - specify the AEAD for ticket protection. diff --git a/ChangeLog.d/9892.txt b/ChangeLog.d/9892.txt deleted file mode 100644 index 962bdad823..0000000000 --- a/ChangeLog.d/9892.txt +++ /dev/null @@ -1,5 +0,0 @@ -Removals - * Remove deprecated mbedtls_x509write_crt_set_serial(). The function was - already deprecated and superseded by - mbedtls_x509write_crt_set_serial_raw(). - diff --git a/ChangeLog.d/9956.txt b/ChangeLog.d/9956.txt deleted file mode 100644 index cea4af1ec6..0000000000 --- a/ChangeLog.d/9956.txt +++ /dev/null @@ -1,6 +0,0 @@ -Removals - * Following the removal of DHM module (#9972 and TF-PSA-Crypto#175) the - following SSL functions are removed: - - mbedtls_ssl_conf_dh_param_bin - - mbedtls_ssl_conf_dh_param_ctx - - mbedtls_ssl_conf_dhm_min_bitlen diff --git a/ChangeLog.d/9964.txt b/ChangeLog.d/9964.txt deleted file mode 100644 index 189b4c1d0e..0000000000 --- a/ChangeLog.d/9964.txt +++ /dev/null @@ -1,26 +0,0 @@ -Removals - * Sample programs for the legacy crypto API have been removed. - pkey/rsa_genkey.c - pkey/pk_decrypt.c - pkey/dh_genprime.c - pkey/rsa_verify.c - pkey/mpi_demo.c - pkey/rsa_decrypt.c - pkey/key_app.c - pkey/dh_server.c - pkey/ecdh_curve25519.c - pkey/pk_encrypt.c - pkey/rsa_sign.c - pkey/key_app_writer.c - pkey/dh_client.c - pkey/ecdsa.c - pkey/rsa_encrypt.c - wince_main.c - aes/crypt_and_hash.c - random/gen_random_ctr_drbg.c - random/gen_entropy.c - hash/md_hmac_demo.c - hash/hello.c - hash/generic_sum.c - cipher/cipher_aead_demo.c - diff --git a/ChangeLog.d/add-tls-exporter.txt b/ChangeLog.d/add-tls-exporter.txt deleted file mode 100644 index 1aea653e09..0000000000 --- a/ChangeLog.d/add-tls-exporter.txt +++ /dev/null @@ -1,6 +0,0 @@ -Features - * Add the function mbedtls_ssl_export_keying_material() which allows the - client and server to extract additional shared symmetric keys from an SSL - session, according to the TLS-Exporter specification in RFC 8446 and 5705. - This requires MBEDTLS_SSL_KEYING_MATERIAL_EXPORT to be defined in - mbedtls_config.h. diff --git a/ChangeLog.d/check_config.txt b/ChangeLog.d/check_config.txt deleted file mode 100644 index f9f44a4b85..0000000000 --- a/ChangeLog.d/check_config.txt +++ /dev/null @@ -1,5 +0,0 @@ -Removals - * The header no longer exists. Including it - from a custom config file was no longer needed since Mbed TLS 3.0, - and could lead to spurious errors. The checks that it performed are - now done automatically when building the library. diff --git a/ChangeLog.d/error-unification.txt b/ChangeLog.d/error-unification.txt deleted file mode 100644 index 1f8e8af1df..0000000000 --- a/ChangeLog.d/error-unification.txt +++ /dev/null @@ -1,12 +0,0 @@ -API changes - * The PSA and Mbed TLS error spaces are now unified. mbedtls_xxx() - functions can now return PSA_ERROR_xxx values. - There is no longer a distinction between "low-level" and "high-level" - Mbed TLS error codes. - This will not affect most applications since the error values are - between -32767 and -1 as before. - -Removals - * Remove mbedtls_low_level_strerr() and mbedtls_high_level_strerr(), - since these concepts no longer exists. There is just mbedtls_strerror(). - diff --git a/ChangeLog.d/fix-asn1-store-named-data.txt b/ChangeLog.d/fix-asn1-store-named-data.txt deleted file mode 100644 index 7a040bd43b..0000000000 --- a/ChangeLog.d/fix-asn1-store-named-data.txt +++ /dev/null @@ -1,8 +0,0 @@ -Security - * Fix a bug in tf-psa-crypto's mbedtls_asn1_store_named_data() where it - would sometimes leave an item in the output list in an inconsistent - state with val.p == NULL but val.len > 0. Affected functions used in X.509 - would then dereference a NULL pointer. Applications that do not - call this function (directly, or indirectly through X.509 writing) are not - affected. Found by Linh Le and Ngan Nguyen from Calif. - diff --git a/ChangeLog.d/fix-clang-psa-build-without-dhm.txt b/ChangeLog.d/fix-clang-psa-build-without-dhm.txt deleted file mode 100644 index 543f4dbf1b..0000000000 --- a/ChangeLog.d/fix-clang-psa-build-without-dhm.txt +++ /dev/null @@ -1,5 +0,0 @@ -Bugfix - * Fix Clang compilation error when finite-field Diffie-Hellman is disabled. - Reported by Michael Schuster in #9188. - - diff --git a/ChangeLog.d/fix-compilation-when-memcpy-is-function-like-macro.txt b/ChangeLog.d/fix-compilation-when-memcpy-is-function-like-macro.txt deleted file mode 100644 index 11e7d25392..0000000000 --- a/ChangeLog.d/fix-compilation-when-memcpy-is-function-like-macro.txt +++ /dev/null @@ -1,2 +0,0 @@ -Bugfix - * Fix compilation error when memcpy() is a function-like macros. Fixes #8994. diff --git a/ChangeLog.d/fix-compilation-with-djgpp.txt b/ChangeLog.d/fix-compilation-with-djgpp.txt deleted file mode 100644 index 5b79fb69de..0000000000 --- a/ChangeLog.d/fix-compilation-with-djgpp.txt +++ /dev/null @@ -1,2 +0,0 @@ -Bugfix - * Fix compilation on MS-DOS DJGPP. Fixes #9813. diff --git a/ChangeLog.d/fix-dependency-on-generated-files.txt b/ChangeLog.d/fix-dependency-on-generated-files.txt deleted file mode 100644 index 540cf0ded2..0000000000 --- a/ChangeLog.d/fix-dependency-on-generated-files.txt +++ /dev/null @@ -1,3 +0,0 @@ -Bugfix - * Fix potential CMake parallel build failure when building both the static - and shared libraries. diff --git a/ChangeLog.d/fix-legacy-compression-issue.txt b/ChangeLog.d/fix-legacy-compression-issue.txt deleted file mode 100644 index 2549af8733..0000000000 --- a/ChangeLog.d/fix-legacy-compression-issue.txt +++ /dev/null @@ -1,6 +0,0 @@ -Bugfix - * Fixes an issue where some TLS 1.2 clients could not connect to an - Mbed TLS 3.6.0 server, due to incorrect handling of - legacy_compression_methods in the ClientHello. - fixes #8995, #9243. - diff --git a/ChangeLog.d/fix-msvc-version-guard-format-zu.txt b/ChangeLog.d/fix-msvc-version-guard-format-zu.txt deleted file mode 100644 index eefda618ca..0000000000 --- a/ChangeLog.d/fix-msvc-version-guard-format-zu.txt +++ /dev/null @@ -1,5 +0,0 @@ -Bugfix - * Fix definition of MBEDTLS_PRINTF_SIZET to prevent runtime crashes that - occurred whenever SSL debugging was enabled on a copy of Mbed TLS built - with Visual Studio 2013 or MinGW. - Fixes #10017. diff --git a/ChangeLog.d/fix-server-mode-only-build.txt b/ChangeLog.d/fix-server-mode-only-build.txt deleted file mode 100644 index d1d8341f79..0000000000 --- a/ChangeLog.d/fix-server-mode-only-build.txt +++ /dev/null @@ -1,3 +0,0 @@ -Bugfix - * Fix server mode only build when MBEDTLS_SSL_SRV_C is enabled but - MBEDTLS_SSL_CLI_C is disabled. Reported by M-Bab on GitHub in #9186. diff --git a/ChangeLog.d/fix-string-to-names-memory-management.txt b/ChangeLog.d/fix-string-to-names-memory-management.txt deleted file mode 100644 index 6b744a74fb..0000000000 --- a/ChangeLog.d/fix-string-to-names-memory-management.txt +++ /dev/null @@ -1,19 +0,0 @@ -Security - * Fix possible use-after-free or double-free in code calling - mbedtls_x509_string_to_names(). This was caused by the function calling - mbedtls_asn1_free_named_data_list() on its head argument, while the - documentation did no suggest it did, making it likely for callers relying - on the documented behaviour to still hold pointers to memory blocks after - they were free()d, resulting in high risk of use-after-free or double-free, - with consequences ranging up to arbitrary code execution. - In particular, the two sample programs x509/cert_write and x509/cert_req - were affected (use-after-free if the san string contains more than one DN). - Code that does not call mbedtls_string_to_names() directly is not affected. - Found by Linh Le and Ngan Nguyen from Calif. - CVE-2025-47917 - -Changes - * The function mbedtls_x509_string_to_names() now requires its head argument - to point to NULL on entry. This makes it likely that existing risky uses of - this function (see the entry in the Security section) will be detected and - fixed. diff --git a/ChangeLog.d/fix-string-to-names-store-named-data.txt b/ChangeLog.d/fix-string-to-names-store-named-data.txt deleted file mode 100644 index b088468612..0000000000 --- a/ChangeLog.d/fix-string-to-names-store-named-data.txt +++ /dev/null @@ -1,10 +0,0 @@ -Security - * Fix a bug in mbedtls_x509_string_to_names() and the - mbedtls_x509write_{crt,csr}_set_{subject,issuer}_name() functions, - where some inputs would cause an inconsistent state to be reached, causing - a NULL dereference either in the function itself, or in subsequent - users of the output structure, such as mbedtls_x509_write_names(). This - only affects applications that create (as opposed to consume) X.509 - certificates, CSRs or CRLs. Found by Linh Le and Ngan Nguyen from Calif. - CVE-2025-48965 - diff --git a/ChangeLog.d/fix_reporting_of_key_usage_issues.txt b/ChangeLog.d/fix_reporting_of_key_usage_issues.txt deleted file mode 100644 index 506f2bdf0e..0000000000 --- a/ChangeLog.d/fix_reporting_of_key_usage_issues.txt +++ /dev/null @@ -1,12 +0,0 @@ -Security - * With TLS 1.3, when a server enables optional authentication of the - client, if the client-provided certificate does not have appropriate values - in keyUsage or extKeyUsage extensions, then the return value of - mbedtls_ssl_get_verify_result() would incorrectly have the - MBEDTLS_X509_BADCERT_KEY_USAGE and MBEDTLS_X509_BADCERT_EXT_KEY_USAGE bits - clear. As a result, an attacker that had a certificate valid for uses other - than TLS client authentication could be able to use it for TLS client - authentication anyway. Only TLS 1.3 servers were affected, and only with - optional authentication (required would abort the handshake with a fatal - alert). - CVE-2024-45159 diff --git a/ChangeLog.d/make-visualc.txt b/ChangeLog.d/make-visualc.txt deleted file mode 100644 index 4b195da54e..0000000000 --- a/ChangeLog.d/make-visualc.txt +++ /dev/null @@ -1,2 +0,0 @@ -Removals - * Drop support for the GNU Make and Microsoft Visual Studio build systems. diff --git a/ChangeLog.d/mbedtls-ssl-null-ciphersuites.txt b/ChangeLog.d/mbedtls-ssl-null-ciphersuites.txt deleted file mode 100644 index a1312d0cb4..0000000000 --- a/ChangeLog.d/mbedtls-ssl-null-ciphersuites.txt +++ /dev/null @@ -1,4 +0,0 @@ -API changes - * Add MBEDTLS_SSL_NULL_CIPHERSUITES configuration option. It enables - TLS 1.2 ciphersuites without encryption and is disabled by default. - This new option replaces MBEDTLS_CIPHER_NULL_CIPHER. diff --git a/ChangeLog.d/mbedtls_ssl_conf_alpn_protocols.txt b/ChangeLog.d/mbedtls_ssl_conf_alpn_protocols.txt deleted file mode 100644 index 0e396bbeff..0000000000 --- a/ChangeLog.d/mbedtls_ssl_conf_alpn_protocols.txt +++ /dev/null @@ -1,4 +0,0 @@ -API changes - * The list passed to mbedtls_ssl_conf_alpn_protocols() is now declared - as having const elements, reflecting the fact that the library will - not modify it diff --git a/ChangeLog.d/mbedtls_ssl_set_hostname.txt b/ChangeLog.d/mbedtls_ssl_set_hostname.txt deleted file mode 100644 index 05f375dcb3..0000000000 --- a/ChangeLog.d/mbedtls_ssl_set_hostname.txt +++ /dev/null @@ -1,18 +0,0 @@ -Default behavior changes - * In TLS clients, if mbedtls_ssl_set_hostname() has not been called, - mbedtls_ssl_handshake() now fails with - MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME - if certificate-based authentication of the server is attempted. - This is because authenticating a server without knowing what name - to expect is usually insecure. - -Security - * Note that TLS clients should generally call mbedtls_ssl_set_hostname() - if they use certificate authentication (i.e. not pre-shared keys). - Otherwise, in many scenarios, the server could be impersonated. - The library will now prevent the handshake and return - MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME - if mbedtls_ssl_set_hostname() has not been called. - Reported by Daniel Stenberg. - CVE-2025-27809 - diff --git a/ChangeLog.d/oid.txt b/ChangeLog.d/oid.txt deleted file mode 100644 index 53828d85b1..0000000000 --- a/ChangeLog.d/oid.txt +++ /dev/null @@ -1,8 +0,0 @@ -Removals - * The library no longer offers interfaces to look up values by OID - or OID by enum values. - The header now only defines functions to convert - between binary and dotted string OID representations, and macros - for OID strings that are relevant to X.509. - The compilation option MBEDTLS_OID_C no longer - exists. OID tables are included in the build automatically as needed. diff --git a/ChangeLog.d/psa-always-on.txt b/ChangeLog.d/psa-always-on.txt deleted file mode 100644 index 6607e9fe40..0000000000 --- a/ChangeLog.d/psa-always-on.txt +++ /dev/null @@ -1,11 +0,0 @@ -Default behavior changes - * The X.509 and TLS modules now always use the PSA subsystem - to perform cryptographic operations, with a few exceptions documented - in docs/architecture/psa-migration/psa-limitations.md. This - corresponds to the behavior of Mbed TLS 3.x when - MBEDTLS_USE_PSA_CRYPTO is enabled. In effect, MBEDTLS_USE_PSA_CRYPTO - is now always enabled. - * psa_crypto_init() must be called before performing any cryptographic - operation, including indirect requests such as parsing a key or - certificate or starting a TLS handshake. - diff --git a/ChangeLog.d/removal-of-rng.txt b/ChangeLog.d/removal-of-rng.txt deleted file mode 100644 index 7ecb29ffb7..0000000000 --- a/ChangeLog.d/removal-of-rng.txt +++ /dev/null @@ -1,6 +0,0 @@ -API changes - * All API functions now use the PSA random generator psa_generate_random() - internally. As a consequence, functions no longer take RNG parameters. - Please refer to the migration guide at : - docs/4.0-migration-guide.md. - diff --git a/ChangeLog.d/remove-compat-2.x.txt b/ChangeLog.d/remove-compat-2.x.txt deleted file mode 100644 index 37f012c217..0000000000 --- a/ChangeLog.d/remove-compat-2.x.txt +++ /dev/null @@ -1,2 +0,0 @@ -Removals - * Remove compat-2-x.h header from mbedtls. diff --git a/ChangeLog.d/remove-deprecated-items.txt b/ChangeLog.d/remove-deprecated-items.txt deleted file mode 100644 index 855265788e..0000000000 --- a/ChangeLog.d/remove-deprecated-items.txt +++ /dev/null @@ -1,11 +0,0 @@ -Removals - * Remove MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT. Now only the - standard version (defined in RFC 9146) of DTLS connection ID is supported. - * Remove mbedtls_ssl_conf_min_version(), mbedtls_ssl_conf_max_version(), and - the associated constants MBEDTLS_SSL_MAJOR_VERSION_x and - MBEDTLS_SSL_MINOR_VERSION_y. Use mbedtls_ssl_conf_min_tls_version() and - mbedtls_ssl_conf_max_tls_version() with MBEDTLS_SSL_VERSION_TLS1_y instead. - Note that the new names of the new constants use the TLS protocol versions, - unlike the old constants whose names are based on internal encodings. - * Remove mbedtls_ssl_conf_sig_hashes(). Use mbedtls_ssl_conf_sig_algs() - instead. diff --git a/ChangeLog.d/remove_RSA_key_exchange.txt b/ChangeLog.d/remove_RSA_key_exchange.txt deleted file mode 100644 index f9baaf1701..0000000000 --- a/ChangeLog.d/remove_RSA_key_exchange.txt +++ /dev/null @@ -1,2 +0,0 @@ -Removals - * Remove support for the RSA key exchange in TLS 1.2. diff --git a/ChangeLog.d/remove_mbedtls_pk_type.txt b/ChangeLog.d/remove_mbedtls_pk_type.txt deleted file mode 100644 index 4b33d1e110..0000000000 --- a/ChangeLog.d/remove_mbedtls_pk_type.txt +++ /dev/null @@ -1,3 +0,0 @@ -Removals - * Remove mbedtls_pk_type_t from the public interface and replace it with - mbedtls_pk_sigalg_t. diff --git a/ChangeLog.d/replace-close-with-mbedtls_net_close.txt b/ChangeLog.d/replace-close-with-mbedtls_net_close.txt deleted file mode 100644 index 213cf55b40..0000000000 --- a/ChangeLog.d/replace-close-with-mbedtls_net_close.txt +++ /dev/null @@ -1,4 +0,0 @@ -Bugfix - * Use 'mbedtls_net_close' instead of 'close' in 'mbedtls_net_bind' - and 'mbedtls_net_connect' to prevent possible double close fd - problems. Fixes #9711. diff --git a/ChangeLog.d/replace_time_t.txt b/ChangeLog.d/replace_time_t.txt deleted file mode 100644 index ec0282a9f2..0000000000 --- a/ChangeLog.d/replace_time_t.txt +++ /dev/null @@ -1,4 +0,0 @@ -Bugfix - * Fix a build error or incorrect TLS session - lifetime on platforms where mbedtls_time_t - is not time_t. Fixes #10236. diff --git a/ChangeLog.d/repo-split.txt b/ChangeLog.d/repo-split.txt deleted file mode 100644 index f03b5ed7fe..0000000000 --- a/ChangeLog.d/repo-split.txt +++ /dev/null @@ -1,5 +0,0 @@ -Changes - * Move the crypto part of the library (content of tf-psa-crypto directory) - from the Mbed TLS to the TF-PSA-Crypto repository. The crypto code and - tests development will now occur in TF-PSA-Crypto, which Mbed TLS - references as a Git submodule. diff --git a/ChangeLog.d/rm-ssl-conf-curves.txt b/ChangeLog.d/rm-ssl-conf-curves.txt deleted file mode 100644 index 4b29adc4c9..0000000000 --- a/ChangeLog.d/rm-ssl-conf-curves.txt +++ /dev/null @@ -1,4 +0,0 @@ -Removals - * Remove the function mbedtls_ssl_conf_curves() which had been deprecated - in favour of mbedtls_ssl_conf_groups() since Mbed TLS 3.1. - diff --git a/ChangeLog.d/runtime-version-interface.txt b/ChangeLog.d/runtime-version-interface.txt deleted file mode 100644 index 1cf42665ca..0000000000 --- a/ChangeLog.d/runtime-version-interface.txt +++ /dev/null @@ -1,9 +0,0 @@ -API changes - * Change the signature of the runtime version information methods that took - a char* as an argument to take zero arguments and return a const char* - instead. This aligns us with the interface used in TF PSA Crypto 1.0. - If you need to support linking against both Mbed TLS 3.x and 4.x, please - use the build-time version macros or mbedtls_version_get_number() to - determine the correct signature for mbedtls_version_get_string() and - mbedtls_version_get_string_full() before calling them. - Fixes issue #10308. diff --git a/ChangeLog.d/secp256k1-removal.txt b/ChangeLog.d/secp256k1-removal.txt deleted file mode 100644 index 9933b8e7a9..0000000000 --- a/ChangeLog.d/secp256k1-removal.txt +++ /dev/null @@ -1,3 +0,0 @@ -Removals - * Support for secp192k1, secp192r1, secp224k1 and secp224r1 EC curves is - removed from TLS. diff --git a/ChangeLog.d/split-numeric-string-conversions-out-of-the-oid-module.txt b/ChangeLog.d/split-numeric-string-conversions-out-of-the-oid-module.txt deleted file mode 100644 index 938e9eccb6..0000000000 --- a/ChangeLog.d/split-numeric-string-conversions-out-of-the-oid-module.txt +++ /dev/null @@ -1,4 +0,0 @@ -Changes - * Functions regarding numeric string conversions for OIDs have been moved - from the OID module and now reside in X.509 module. This helps to reduce - the code size as these functions are not commonly used outside of X.509. diff --git a/ChangeLog.d/static-ecdh-removal.txt b/ChangeLog.d/static-ecdh-removal.txt deleted file mode 100644 index 94512a21f9..0000000000 --- a/ChangeLog.d/static-ecdh-removal.txt +++ /dev/null @@ -1,3 +0,0 @@ -Removals - * Removed support for TLS 1.2 static ECDH key - exchanges (ECDH-ECDSA and ECDH-RSA). diff --git a/ChangeLog.d/tls-hs-defrag-in.txt b/ChangeLog.d/tls-hs-defrag-in.txt deleted file mode 100644 index 6bab02a029..0000000000 --- a/ChangeLog.d/tls-hs-defrag-in.txt +++ /dev/null @@ -1,7 +0,0 @@ -Bugfix - * Support re-assembly of fragmented handshake messages in TLS (both - 1.2 and 1.3). The lack of support was causing handshake failures with - some servers, especially with TLS 1.3 in practice. There are a few - limitations, notably a fragmented ClientHello is only supported when - TLS 1.3 support is enabled. See the documentation of - mbedtls_ssl_handshake() for details. diff --git a/ChangeLog.d/tls-key-exchange-rsa.txt b/ChangeLog.d/tls-key-exchange-rsa.txt deleted file mode 100644 index 4df6b3e303..0000000000 --- a/ChangeLog.d/tls-key-exchange-rsa.txt +++ /dev/null @@ -1,2 +0,0 @@ -Removals - * Remove support for the RSA-PSK key exchange in TLS 1.2. diff --git a/ChangeLog.d/tls12-check-finished-calc.txt b/ChangeLog.d/tls12-check-finished-calc.txt deleted file mode 100644 index cd52d32ffd..0000000000 --- a/ChangeLog.d/tls12-check-finished-calc.txt +++ /dev/null @@ -1,6 +0,0 @@ -Security - * Fix a vulnerability in the TLS 1.2 handshake. If memory allocation failed - or there was a cryptographic hardware failure when calculating the - Finished message, it could be calculated incorrectly. This would break - the security guarantees of the TLS handshake. - CVE-2025-27810 diff --git a/ChangeLog.d/tls13-cert-regressions.txt b/ChangeLog.d/tls13-cert-regressions.txt deleted file mode 100644 index 8dd8a327d6..0000000000 --- a/ChangeLog.d/tls13-cert-regressions.txt +++ /dev/null @@ -1,18 +0,0 @@ -Bugfix - * Fixed a regression introduced in 3.6.0 where the CA callback set with - mbedtls_ssl_conf_ca_cb() would stop working when connections were - upgraded to TLS 1.3. Fixed by adding support for the CA callback with TLS - 1.3. - * Fixed a regression introduced in 3.6.0 where clients that relied on - optional/none authentication mode, by calling mbedtls_ssl_conf_authmode() - with MBEDTLS_SSL_VERIFY_OPTIONAL or MBEDTLS_SSL_VERIFY_NONE, would stop - working when connections were upgraded to TLS 1.3. Fixed by adding - support for optional/none with TLS 1.3 as well. Note that the TLS 1.3 - standard makes server authentication mandatory; users are advised not to - use authmode none, and to carefully check the results when using optional - mode. - * Fixed a regression introduced in 3.6.0 where context-specific certificate - verify callbacks, set with mbedtls_ssl_set_verify() as opposed to - mbedtls_ssl_conf_verify(), would stop working when connections were - upgraded to TLS 1.3. Fixed by adding support for context-specific verify - callback in TLS 1.3. diff --git a/ChangeLog.d/tls13-middlebox-compat-disabled.txt b/ChangeLog.d/tls13-middlebox-compat-disabled.txt deleted file mode 100644 index f5331bc063..0000000000 --- a/ChangeLog.d/tls13-middlebox-compat-disabled.txt +++ /dev/null @@ -1,4 +0,0 @@ -Bugfix - * When MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE is disabled, work with - peers that have middlebox compatibility enabled, as long as no - problematic middlebox is in the way. Fixes #9551. diff --git a/ChangeLog.d/tls13-without-tickets.txt b/ChangeLog.d/tls13-without-tickets.txt deleted file mode 100644 index 8ceef21ee5..0000000000 --- a/ChangeLog.d/tls13-without-tickets.txt +++ /dev/null @@ -1,3 +0,0 @@ -Bugfix - * Fix TLS 1.3 client build and runtime when support for session tickets is - disabled (MBEDTLS_SSL_SESSION_TICKETS configuration option). Fixes #6395. diff --git a/ChangeLog.d/unify-errors.txt b/ChangeLog.d/unify-errors.txt deleted file mode 100644 index f229f1bc4d..0000000000 --- a/ChangeLog.d/unify-errors.txt +++ /dev/null @@ -1,7 +0,0 @@ -API changes - * Make the following error codes aliases of their PSA equivalents, where - xxx is a module, e.g. X509 or SSL. - MBEDTLS_ERR_xxx_BAD_INPUT_DATA -> PSA_ERROR_INVALID_ARGUMENT - MBEDTLS_ERR_xxx_ALLOC_FAILED -> PSA_ERROR_INSUFFICIENT_MEMORY - MBEDTLS_ERR_xxx_BUFFER_TOO_SMALL -> PSA_ERROR_BUFFER_TOO_SMALL - MBEDTLS_ERR_PKCS7_VERIFY_FAIL -> PSA_ERROR_INVALID_SIGNATURE diff --git a/ChangeLog.d/unterminated-string-initialization.txt b/ChangeLog.d/unterminated-string-initialization.txt deleted file mode 100644 index 75a72cae6b..0000000000 --- a/ChangeLog.d/unterminated-string-initialization.txt +++ /dev/null @@ -1,3 +0,0 @@ -Bugfix - * Silence spurious -Wunterminated-string-initialization warnings introduced - by GCC 15. Fixes #9944. diff --git a/ChangeLog.d/x509write_crt_set_serial_raw-alignment.txt b/ChangeLog.d/x509write_crt_set_serial_raw-alignment.txt deleted file mode 100644 index e7ac54684c..0000000000 --- a/ChangeLog.d/x509write_crt_set_serial_raw-alignment.txt +++ /dev/null @@ -1,3 +0,0 @@ -API changes - * Change the serial argument of the mbedtls_x509write_crt_set_serial_raw - function to a const to align with the rest of the API. From 411461a86e8371d6173ee99ae09ee42eaaa53dae Mon Sep 17 00:00:00 2001 From: Minos Galanakis Date: Sat, 11 Oct 2025 21:48:56 +0100 Subject: [PATCH 46/47] Doc: Removed references to beta version Signed-off-by: Minos Galanakis --- README.md | 2 +- doxygen/input/doc_mainpage.h | 2 +- doxygen/mbedtls.doxyfile | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 69f2dcb26e..d3fb638802 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ After cloning or checking out a branch or tag, run: ``` to initialize and update the submodules before building. -However, the official source release tarballs (e.g. [mbedtls-4.0.0-beta.tar.bz2](https://github.com/Mbed-TLS/mbedtls/releases/download/mbedtls-4.0.0-beta/mbedtls-4.0.0-beta.tar.bz2)) include the contents of the submodules. +However, the official source release tarballs (e.g. [mbedtls-4.0.0.tar.bz2](https://github.com/Mbed-TLS/mbedtls/releases/download/mbedtls-4.0.0/mbedtls-4.0.0.tar.bz2)) include the contents of the submodules. ### Generated source files in the development branch diff --git a/doxygen/input/doc_mainpage.h b/doxygen/input/doc_mainpage.h index c1d0f36215..4eda5ba2aa 100644 --- a/doxygen/input/doc_mainpage.h +++ b/doxygen/input/doc_mainpage.h @@ -10,7 +10,7 @@ */ /** - * @mainpage Mbed TLS v4.0.0-beta API Documentation + * @mainpage Mbed TLS v4.0.0 API Documentation * * This documentation describes the application programming interface (API) * of Mbed TLS. diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 00e64d05c9..80e459cc72 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -1,4 +1,4 @@ -PROJECT_NAME = "Mbed TLS v4.0.0-beta" +PROJECT_NAME = "Mbed TLS v4.0.0" OUTPUT_DIRECTORY = ../apidoc/ FULL_PATH_NAMES = NO OPTIMIZE_OUTPUT_FOR_C = YES From ec4044008d2d069da38288bc76b0fee34ec78646 Mon Sep 17 00:00:00 2001 From: Minos Galanakis Date: Mon, 13 Oct 2025 16:50:50 +0100 Subject: [PATCH 47/47] ChangeLog: Added CVEs Signed-off-by: Minos Galanakis --- ChangeLog | 1 + 1 file changed, 1 insertion(+) diff --git a/ChangeLog b/ChangeLog index d31ada506f..4dc0941fee 100644 --- a/ChangeLog +++ b/ChangeLog @@ -188,6 +188,7 @@ Security would then dereference a NULL pointer. Applications that do not call this function (directly, or indirectly through X.509 writing) are not affected. Found by Linh Le and Ngan Nguyen from Calif. + CVE-2025-48965 Bugfix * Fix TLS 1.3 client build and runtime when support for session tickets is