From 28d1d61d72721ae0128184a39b3edf21bf7af8c0 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 30 Sep 2025 10:42:05 +0200 Subject: [PATCH 01/17] 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 02/17] 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 03/17] 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 04/17] 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 05/17] 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 06/17] 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 07/17] 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 08/17] 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 09/17] 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 10/17] 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 11/17] 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 12/17] 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 13/17] 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 14/17] 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 15/17] 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 16/17] 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 17/17] 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).