From cf9b557d1c83a74bc0f94d44db12fc9e9c70df20 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 26 Sep 2025 16:07:38 +0200 Subject: [PATCH 1/5] Removed static ECDH Signed-off-by: Gilles Peskine --- docs/4.0-migration-guide/feature-removals.md | 31 ++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/4.0-migration-guide/feature-removals.md b/docs/4.0-migration-guide/feature-removals.md index ae611a112c..8b2c4d0b8f 100644 --- a/docs/4.0-migration-guide/feature-removals.md +++ b/docs/4.0-migration-guide/feature-removals.md @@ -12,6 +12,7 @@ That is, the following key exchange types are no longer supported: * 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: @@ -59,6 +60,36 @@ 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 From 7d3cf9b3dce7d204c791744564e99f388383eb8c Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 25 Sep 2025 18:09:37 +0200 Subject: [PATCH 2/5] 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. From ce9f08a11bafb4a594b1e72978bfc87771409cb2 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 26 Sep 2025 19:21:15 +0200 Subject: [PATCH 3/5] More removals found in changelog entries Signed-off-by: Gilles Peskine --- docs/4.0-migration-guide/configuration.md | 10 ++++++++++ docs/4.0-migration-guide/feature-removals.md | 10 ++++++++++ 2 files changed, 20 insertions(+) diff --git a/docs/4.0-migration-guide/configuration.md b/docs/4.0-migration-guide/configuration.md index 0065de4542..c8e54f657b 100644 --- a/docs/4.0-migration-guide/configuration.md +++ b/docs/4.0-migration-guide/configuration.md @@ -32,3 +32,13 @@ TF-PSA-Crypto exposes its version through ``, similar t ### 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/feature-removals.md b/docs/4.0-migration-guide/feature-removals.md index 8b2c4d0b8f..b958f864fc 100644 --- a/docs/4.0-migration-guide/feature-removals.md +++ b/docs/4.0-migration-guide/feature-removals.md @@ -140,3 +140,13 @@ 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. From 2c2e24338b4d51de3677719ff0ea03396c1e7f28 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 29 Sep 2025 15:47:23 +0200 Subject: [PATCH 4/5] There's no reason to discourage including */build_info.h directly Signed-off-by: Gilles Peskine --- docs/4.0-migration-guide/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/4.0-migration-guide/configuration.md b/docs/4.0-migration-guide/configuration.md index c8e54f657b..144f7bbe15 100644 --- a/docs/4.0-migration-guide/configuration.md +++ b/docs/4.0-migration-guide/configuration.md @@ -25,7 +25,7 @@ Note that many options related to cryptography have changed; see the TF-PSA-Cryp ### 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`. +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. From e27c35c6a622bdbe1cfff66bc51b074220b12152 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 29 Sep 2025 15:48:58 +0200 Subject: [PATCH 5/5] Copyediting Signed-off-by: Gilles Peskine --- docs/4.0-migration-guide/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/4.0-migration-guide/configuration.md b/docs/4.0-migration-guide/configuration.md index 144f7bbe15..25bddf44f9 100644 --- a/docs/4.0-migration-guide/configuration.md +++ b/docs/4.0-migration-guide/configuration.md @@ -8,7 +8,7 @@ All configuration options that are relevant to TF-PSA-Crypto must now be configu * 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. +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: