Merge pull request #10422 from gilles-peskine-arm/migration-guide-20250926

Migration guide: header file comparison

Author: mpg

docs/4.0-migration-guide/configuration.md

@@ -0,0 +1,44 @@
+## 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 `<psa/crypto_config.h>`;
+* 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 `<mbedtls/mbedtls_config.h>`, 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:
+
+* 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, `<psa/crypto_config.h>` 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`
+
+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.
+
+TF-PSA-Crypto exposes its version through `<tf-psa-crypto/version.h>`, similar to `<mbedtls/version.h>` 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.
+
+### 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.

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
@@ -109,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.