From 9228e4a794076dc92e8ce212bd5f40a0db65de99 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Sun, 5 Oct 2025 16:25:43 +0200 Subject: [PATCH 01/12] 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 02/12] 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 03/12] 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 04/12] 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 05/12] 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 06/12] 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 07/12] 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 08/12] 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 09/12] 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 10/12] 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 11/12] 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 12/12] 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`