| Gilles Peskine | 7d3cf9b | 2025-09-25 18:09:37 +0200 | [diff] [blame] | 1 | ## Compile-time configuration |
| 2 | |
| 3 | ### Configuration file split |
| 4 | |
| 5 | All configuration options that are relevant to TF-PSA-Crypto must now be configured in one of its configuration files, namely: |
| 6 | |
| 7 | * `TF_PSA_CRYPTO_CONFIG_FILE`, if set on the preprocessor command line; |
| 8 | * otherwise `<psa/crypto_config.h>`; |
| 9 | * additionally `TF_PSA_CRYPTO_USER_CONFIG_FILE`, if set. |
| 10 | |
| 11 | Configuration options that are relevant to X.509 or TLS should still be set in the Mbed TLS configuration file (`MBEDTLS_CONFIG_FILE` or `<mbedtls/mbedtls_config.h>`, and `MBEDTLS_USER_CONFIG_FILE` is set). However, you can define all options in the crypto configuration, and Mbed TLS will pick them up. |
| 12 | |
| 13 | Generally speaking, the options that must be configured in TF-PSA-Crypto are: |
| 14 | |
| 15 | * options related to platform settings; |
| 16 | * options related to the choice of cryptographic mechanisms included in the build; |
| 17 | * options related to the inner workings of cryptographic mechanisms, such as size/memory/performance compromises; |
| 18 | * options related to crypto-adjacent features, such as ASN.1 and Base64. |
| 19 | |
| 20 | See `include/psa/crypto_config.h` in TF-PSA-Crypto and `include/mbedtls/mbedtls_config.h` in Mbed TLS for details. |
| 21 | |
| 22 | Notably, `<psa/crypto_config.h>` is no longer limited to `PSA_WANT_xxx` options. |
| 23 | |
| 24 | Note that many options related to cryptography have changed; see the TF-PSA-Crypto migration guide for details. |
| 25 | |
| 26 | ### Split of `build_info.h` and `version.h` |
| 27 | |
| Gilles Peskine | 2c2e243 | 2025-09-29 15:47:23 +0200 | [diff] [blame^] | 28 | The header file `<mbedtls/build_info.h>`, which includes the configuration file and provides the adjusted configuration macros, now has an similar file `<tf-psa-crypto/build_info.h>` in TF-PSA-Crypto. The Mbed TLS header includes the TF-PSA-Crypto header, so including `<mbedtls/build_info.h>` remains sufficient to obtain information about the crypto configuration. |
| Gilles Peskine | 7d3cf9b | 2025-09-25 18:09:37 +0200 | [diff] [blame] | 29 | |
| 30 | TF-PSA-Crypto exposes its version through `<tf-psa-crypto/version.h>`, similar to `<mbedtls/version.h>` in Mbed TLS. |
| 31 | |
| 32 | ### Removal of `check_config.h` |
| 33 | |
| 34 | 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. |
| Gilles Peskine | ce9f08a | 2025-09-26 19:21:15 +0200 | [diff] [blame] | 35 | |
| 36 | ### Changes to TLS options |
| 37 | |
| 38 | #### Enabling null cipher suites |
| 39 | |
| 40 | 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. |
| 41 | |
| 42 | #### Removal of backward compatibility options |
| 43 | |
| 44 | The option `MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT` has been removed. Only the version standardized in RFC 9146 is supported now. |