TeamHepta/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2026-03-20 19:21:09 +01:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Migration guide: header file comparison
This commit is contained in:
Manuel Pégourié-Gonnard
2025-09-29 16:46:32 +00:00
committed by GitHub
parent 6ac36938b8 e27c35c6a6
commit fd9b5d5f09
2 changed files with 85 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/4.0-migration-guide/configuration.md Normal file
View File

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

41
docs/4.0-migration-guide/feature-removals.md
View File

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