From 7d3cf9b3dce7d204c791744564e99f388383eb8c Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 25 Sep 2025 18:09:37 +0200 Subject: [PATCH] Add section on the config file split Signed-off-by: Gilles Peskine --- docs/4.0-migration-guide/configuration.md | 34 +++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 docs/4.0-migration-guide/configuration.md diff --git a/docs/4.0-migration-guide/configuration.md b/docs/4.0-migration-guide/configuration.md new file mode 100644 index 0000000000..0065de4542 --- /dev/null +++ b/docs/4.0-migration-guide/configuration.md @@ -0,0 +1,34 @@ +## 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 ``, and `MBEDTLS_USER_CONFIG_FILE` 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` + +TF-PSA-Crypto has a header file `` which includes the configuration file and provides the adjusted configuration macros, similar to `` in Mbed TLS. Generally, you should include a feature-specific header file rather than `build_info.h`. + +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.