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 #10255 from gilles-peskine-arm/migration-guide-20250624-mbedtls

Browse Source 
Migration guide for API changes in 2025Q2 in mbedtls
This commit is contained in:
Manuel Pégourié-Gonnard
2025-06-30 18:33:36 +00:00
committed by GitHub
parent 921331867d 159a652096
commit 64e80ddf89
15 changed files with 346 additions and 1334 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
ChangeLog.d/9892.txt
View File

@@ -1,4 +1,4 @@
Removals
* Remove deprecated mbedtls_x509write_crt_set_serial(). The function was
already deprecated and superseeded by
already deprecated and superseded by
mbedtls_x509write_crt_set_serial_raw().

2
ChangeLog.d/9964.txt
View File

@@ -1,5 +1,5 @@
Removals
* Removal of the following sample programs:
* Sample programs for the legacy crypto API have been removed.
pkey/rsa_genkey.c
pkey/pk_decrypt.c
pkey/dh_genprime.c

2
ChangeLog.d/error-unification.txt
View File

@@ -7,5 +7,5 @@ API changes
between -32767 and -1 as before.
Removals
* Remove mbedtls_low_level_sterr() and mbedtls_high_level_strerr(),
* Remove mbedtls_low_level_strerr() and mbedtls_high_level_strerr(),
since these concepts no longer exists. There is just mbedtls_strerror().

2
ChangeLog.d/removal-of-rng.txt
View File

@@ -1,5 +1,5 @@
API changes
* All API functions now use the PSA random generator psa_get_random()
* All API functions now use the PSA random generator psa_generate_random()
internally. As a consequence, functions no longer take RNG parameters.
Please refer to the migration guide at :
tf-psa-crypto/docs/4.0-migration-guide.md.

5
ChangeLog.d/remove-crypto-alt-interface.txt
View File

@@ -1,5 +0,0 @@
Removals
* Drop support for crypto alt interface. Removes MBEDTLS_XXX_ALT options
at the module and function level for crypto mechanisms only. The remaining
alt interfaces for platform, threading and timing are unchanged.
Fixes #8149.

3
ChangeLog.d/remove-via-padlock-support.txt
View File

@@ -1,3 +0,0 @@
Removals
* Drop support for VIA Padlock. Removes MBEDTLS_PADLOCK_C.
Fixes #5903.

14
docs/4.0-migration-guide/deprecated-removals.md Normal file
View File

@@ -0,0 +1,14 @@
## Removal of deprecated functions
### Removal of deprecated X.509 functions
The deprecated function `mbedtls_x509write_crt_set_serial()` has been removed. The function was superseded by `mbedtls_x509write_crt_set_serial_raw()`.
### Removal of deprecated SSL functions
The deprecated function `mbedtls_ssl_conf_curves()` has been removed.
The function was superseded by `mbedtls_ssl_conf_groups()`.
### Removal of `compat-2.x.h`
The header `compat-2.x.h`, containing some definitions for backward compatibility with Mbed TLS 2.x, has been removed.

28
docs/4.0-migration-guide/error-codes.md Normal file
View File

@@ -0,0 +1,28 @@
## Error codes
### Unified error code space
The convention still applies that functions return 0 for success and a negative value between -32767 and -1 on error. PSA functions (`psa_xxx()` or `mbedtls_psa_xxx()`) still return a `PSA_ERROR_xxx` error codes. Non-PSA functions (`mbedtls_xxx()` excluding `mbedtls_psa_xxx()`) can return either `PSA_ERROR_xxx` or `MBEDTLS_ERR_xxx` error codes.
There may be cases where an `MBEDTLS_ERR_xxx` constant has the same numerical value as a `PSA_ERROR_xxx`. In such cases, they have the same meaning: they are different names for the same error condition.
### Simplified legacy error codes
All values returned by a function to indicate an error now have a defined constant named `MBEDTLS_ERR_xxx` or `PSA_ERROR_xxx`. Functions no longer return the sum of a “low-level” and a “high-level” error code.
Generally, functions that used to return the sum of two error codes now return the low-level code. However, as before, the exact error code returned in a given scenario can change without notice unless the condition is specifically described in the function's documentation and no other condition is applicable.
As a consequence, the functions `mbedtls_low_level_strerr()` and `mbedtls_high_level_strerr()` no longer exist.
### Removed error code names
Many legacy error codes have been removed in favor of PSA error codes. Generally, functions that returned a legacy error code in the table below in Mbed TLS 3.6 now return the PSA error code listed on the same row. Similarly, callbacks should apply the same changes to error code, unless there has been a relevant change to the callback's interface.
| Legacy constant (Mbed TLS 3.6) | PSA constant (Mbed TLS 4.0) |
| ------------------------------ | --------------------------- |
| `MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED` | `PSA_ERROR_CORRUPTION_DETECTED` |
| `MBEDTLS_ERR_ERROR_GENERIC_ERROR` | `PSA_ERROR_GENERIC_ERROR` |
| `MBEDTLS_ERR_OID_BUF_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL`
| `MBEDTLS_ERR_OID_NOT_FOUND` | `PSA_ERROR_NOT_SUPPORTED` |
See also the corresponding section in the TF-PSA-Crypto migration guide, which lists error codes from cryptography modules.

111
docs/4.0-migration-guide/feature-removals.md Normal file
View File

@@ -0,0 +1,111 @@
## Removed features
### Removal of obsolete key exchanges methods in (D)TLS 1.2
Mbed TLS 4.0 no longer supports key exchange methods that rely on finite-field Diffie-Hellman (DHE) in TLS 1.2 and DTLS 1.2. (Only ephemeral Diffie-Hellman was ever supported, Mbed TLS 3.x already did not support static Diffie-Hellman.) Finite-field Diffie-Hellman remains supported in TLS 1.3.
Mbed TLS 4.0 no longer supports key exchange methods that rely on RSA decryption (without forward secrecy). RSA signatures remain supported. This affects TLS 1.2 and DTLS 1.2 (TLS 1.3 does not have key exchanges using RSA decryption).
That is, the following key exchange types are no longer supported:
* RSA-PSK;
* 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).
The full list of removed cipher suites is:
```
TLS-DHE-PSK-WITH-AES-128-CBC-SHA
TLS-DHE-PSK-WITH-AES-128-CBC-SHA256
TLS-DHE-PSK-WITH-AES-128-CCM
TLS-DHE-PSK-WITH-AES-128-CCM-8
TLS-DHE-PSK-WITH-AES-128-GCM-SHA256
TLS-DHE-PSK-WITH-AES-256-CBC-SHA
TLS-DHE-PSK-WITH-AES-256-CBC-SHA384
TLS-DHE-PSK-WITH-AES-256-CCM
TLS-DHE-PSK-WITH-AES-256-CCM-8
TLS-DHE-PSK-WITH-AES-256-GCM-SHA384
TLS-DHE-PSK-WITH-ARIA-128-CBC-SHA256
TLS-DHE-PSK-WITH-ARIA-128-GCM-SHA256
TLS-DHE-PSK-WITH-ARIA-256-CBC-SHA384
TLS-DHE-PSK-WITH-ARIA-256-GCM-SHA384
TLS-DHE-PSK-WITH-CAMELLIA-128-CBC-SHA256
TLS-DHE-PSK-WITH-CAMELLIA-128-GCM-SHA256
TLS-DHE-PSK-WITH-CAMELLIA-256-CBC-SHA384
TLS-DHE-PSK-WITH-CAMELLIA-256-GCM-SHA384
TLS-DHE-PSK-WITH-CHACHA20-POLY1305-SHA256
TLS-DHE-PSK-WITH-NULL-SHA
TLS-DHE-PSK-WITH-NULL-SHA256
TLS-DHE-PSK-WITH-NULL-SHA384
TLS-DHE-RSA-WITH-AES-128-CBC-SHA
TLS-DHE-RSA-WITH-AES-128-CBC-SHA256
TLS-DHE-RSA-WITH-AES-128-CCM
TLS-DHE-RSA-WITH-AES-128-CCM-8
TLS-DHE-RSA-WITH-AES-128-GCM-SHA256
TLS-DHE-RSA-WITH-AES-256-CBC-SHA
TLS-DHE-RSA-WITH-AES-256-CBC-SHA256
TLS-DHE-RSA-WITH-AES-256-CCM
TLS-DHE-RSA-WITH-AES-256-CCM-8
TLS-DHE-RSA-WITH-AES-256-GCM-SHA384
TLS-DHE-RSA-WITH-ARIA-128-CBC-SHA256
TLS-DHE-RSA-WITH-ARIA-128-GCM-SHA256
TLS-DHE-RSA-WITH-ARIA-256-CBC-SHA384
TLS-DHE-RSA-WITH-ARIA-256-GCM-SHA384
TLS-DHE-RSA-WITH-CAMELLIA-128-CBC-SHA
TLS-DHE-RSA-WITH-CAMELLIA-128-CBC-SHA256
TLS-DHE-RSA-WITH-CAMELLIA-128-GCM-SHA256
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-RSA-PSK-WITH-AES-128-CBC-SHA
TLS-RSA-PSK-WITH-AES-128-CBC-SHA256
TLS-RSA-PSK-WITH-AES-128-GCM-SHA256
TLS-RSA-PSK-WITH-AES-256-CBC-SHA
TLS-RSA-PSK-WITH-AES-256-CBC-SHA384
TLS-RSA-PSK-WITH-AES-256-GCM-SHA384
TLS-RSA-PSK-WITH-ARIA-128-CBC-SHA256
TLS-RSA-PSK-WITH-ARIA-128-GCM-SHA256
TLS-RSA-PSK-WITH-ARIA-256-CBC-SHA384
TLS-RSA-PSK-WITH-ARIA-256-GCM-SHA384
TLS-RSA-PSK-WITH-CAMELLIA-128-CBC-SHA256
TLS-RSA-PSK-WITH-CAMELLIA-128-GCM-SHA256
TLS-RSA-PSK-WITH-CAMELLIA-256-CBC-SHA384
TLS-RSA-PSK-WITH-CAMELLIA-256-GCM-SHA384
TLS-RSA-PSK-WITH-CHACHA20-POLY1305-SHA256
TLS-RSA-PSK-WITH-NULL-SHA
TLS-RSA-PSK-WITH-NULL-SHA256
TLS-RSA-PSK-WITH-NULL-SHA384
TLS-RSA-WITH-AES-128-CBC-SHA
TLS-RSA-WITH-AES-128-CBC-SHA256
TLS-RSA-WITH-AES-128-CCM
TLS-RSA-WITH-AES-128-CCM-8
TLS-RSA-WITH-AES-128-GCM-SHA256
TLS-RSA-WITH-AES-256-CBC-SHA
TLS-RSA-WITH-AES-256-CBC-SHA256
TLS-RSA-WITH-AES-256-CCM
TLS-RSA-WITH-AES-256-CCM-8
TLS-RSA-WITH-AES-256-GCM-SHA384
TLS-RSA-WITH-ARIA-128-CBC-SHA256
TLS-RSA-WITH-ARIA-128-GCM-SHA256
TLS-RSA-WITH-ARIA-256-CBC-SHA384
TLS-RSA-WITH-ARIA-256-GCM-SHA384
TLS-RSA-WITH-CAMELLIA-128-CBC-SHA
TLS-RSA-WITH-CAMELLIA-128-CBC-SHA256
TLS-RSA-WITH-CAMELLIA-128-GCM-SHA256
TLS-RSA-WITH-CAMELLIA-256-CBC-SHA
TLS-RSA-WITH-CAMELLIA-256-CBC-SHA256
TLS-RSA-WITH-CAMELLIA-256-GCM-SHA384
TLS-RSA-WITH-NULL-MD5
TLS-RSA-WITH-NULL-SHA
TLS-RSA-WITH-NULL-SHA256
```
As a consequence of the removal of support for DHE in (D)TLS 1.2, the following functions are no longer useful and have been removed:
```
mbedtls_ssl_conf_dh_param_bin()
mbedtls_ssl_conf_dh_param_ctx()
mbedtls_ssl_conf_dhm_min_bitlen()
```

89
docs/4.0-migration-guide/function-prototype-changes.md Normal file
View File

@@ -0,0 +1,89 @@
## Function prototype changes
A number of existing functions now take a different list of arguments, mostly to migrate them to the PSA API.
### Public functions no longer take a RNG callback
Functions that need randomness no longer take an RNG callback in the form of `f_rng, p_rng` arguments. Instead, they use the PSA Crypto random generator (accessible as `psa_generate_random()`). All software using the X.509 or SSL modules must call `psa_crypto_init()` before calling any of the functions listed here.
### RNG removal in X.509
The following function prototypes have been changed in `mbedtls/x509_crt.h`:
```c
int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
```
to
```c
int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size);
int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size);
```
The following function prototypes have been changed in `mbedtls/x509_csr.h`:
```c
int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
```
to
```c
int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size);
int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size);
```
### RNG removal in SSL
The following function prototype has been changed in `mbedtls/ssl_cookie.h`:
```c
int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
```
to
```c
int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx);
```
### Removal of `mbedtls_ssl_conf_rng`
`mbedtls_ssl_conf_rng()` has been removed from the library. Its sole purpose was to configure the RNG used for TLS, but now the PSA Crypto random generator is used throughout the library.
### Changes to mbedtls_ssl_ticket_setup
In the arguments of the function `mbedtls_ssl_ticket_setup()`, the `mbedtls_cipher_type_t` argument specifying the AEAD mechanism for ticket protection has been replaced by an equivalent PSA description consisting of a key type, a size and an algorithm. Also, the function no longer takes RNG arguments.
The prototype in `mbedtls/ssl_ticket.h` has changed from
```c
int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx,
mbedtls_f_rng_t *f_rng, void *p_rng,
mbedtls_cipher_type_t cipher,
uint32_t lifetime);
```
to
```c
int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx,
psa_algorithm_t alg, psa_key_type_t key_type, psa_key_bits_t key_bits,
uint32_t lifetime);
```

7
docs/4.0-migration-guide/oid.md Normal file
View File

@@ -0,0 +1,7 @@
## OID module
The compilation option `MBEDTLS_OID_C` no longer exists. OID tables are included in the build automatically as needed for parsing and writing X.509 data.
Mbed TLS no longer offers interfaces to look up values by OID or OID by enum values (`mbedtls_oid_get_<thing>()` and `mbedtls_oid_get_oid_by_<thing>()`).
The header `<mbedtls/oid.h>` now only provides functions to convert between binary and dotted string OID representations. These functions are now part of `libmbedx509` rather than the crypto library. The function `mbedtls_oid_get_numeric_string()` is guarded by `MBEDTLS_X509_USE_C`, and `mbedtls_oid_from_numeric_string()` by `MBEDTLS_X509_CREATE_C`. The header also still defines macros for OID strings that are relevant to X.509.

33
docs/4.0-migration-guide/private-decls.md Normal file
View File

@@ -0,0 +1,33 @@
## Private declarations
Since Mbed TLS 3.0, some things that are declared in a public header are not part of the stable application programming interface (API), but instead are considered private. Private elements may be removed or may have their semantics changed in a future minor release without notice.
### Understanding private declarations in public headers
In Mbed TLS 4.x, private elements in header files include:
* Anything appearing in a header file whose path contains `/private` (unless re-exported and documented in another non-private header).
* Structure and union fields declared with `MBEDTLS_PRIVATE(field_name)` in the source code, and appearing as `private_field_name` in the rendered documentation. (This was already the case since Mbed TLS 3.0.)
* Any preprocessor macro that is not documented with a Doxygen comment.
In the source code, Doxygen comments start with `/**` or `/*!`. If a macro only has a comment above that starts with `/*`, the macro is considered private.
In the rendered documentation, private macros appear with only an automatically rendered parameter list, value and location, but no custom text.
* Any declaration that is guarded by the preprocessor macro `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS`.
### Usage of private declarations
Some private declarations are present in public headers for technical reasons, because they need to be visible to the compiler. Others are present for historical reasons and may be cleaned up in later versions of the library. We strongly recommend against relying on these declarations, since they may be removed or may have their semantics changed without notice.
Note that Mbed TLS 4.0 still relies on some private interfaces of TF-PSA-Crypto 1.0. We expect to remove this reliance gradually in future minor releases.
Sample programs have not been fully updated yet and some of them might still
use APIs that are no longer public. You can recognize them by the fact that they
define the macro `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS` (or
`MBEDTLS_ALLOW_PRIVATE_ACCESS`) at the very top (before including headers). When
you see one of these two macros in a sample program, be aware it has not been
updated and parts of it do not demonstrate current practice.
We strongly recommend against defining `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS` or
`MBEDTLS_ALLOW_PRIVATE_ACCESS` in your own application. If you do so, your code
may not compile or work with future minor releases. If there's something you
want to do that you feel can only be achieved by using one of these two macros,
please reach out on github or the mailing list.

23
docs/4.0-migration-guide/psa-only.md Normal file
View File

@@ -0,0 +1,23 @@
## PSA as the only cryptography API
The PSA API is now the only API for cryptographic primitives.
### Impact on application code
The X.509, PKCS7 and SSL modules always use PSA for cryptography, with a few exceptions documented in the [PSA limitations](../architecture/psa-migration/psa-limitations.md) document. (These limitations are mostly transparent unless you want to leverage PSA accelerator drivers.) This corresponds to the behavior of Mbed TLS 3.x when `MBEDTLS_USE_PSA_CRYPTO` is enabled. In effect, `MBEDTLS_USE_PSA_CRYPTO` is now always enabled.
`psa_crypto_init()` must be called before performing any cryptographic operation, including indirect requests such as parsing a key or certificate or starting a TLS handshake.
A few functions take different parameters to migrate them to the PSA API. See “[Function prototype changes](#function-prototype-changes)”.
### No random generator instantiation
Formerly, applications using TLS, asymmetric cryptography operations involving a private key, or other features needing random numbers, needed to provide a random generator, generally by instantiating an entropy context (`mbedtls_entropy_context`) and a DRBG context (`mbedtls_ctr_drbg_context` or `mbedtls_hmac_drbg_context`). This is no longer necessary, or possible. All features that require a random generator (RNG) now use the one provided by the PSA subsystem.
Instead, applications that use random generators or keys (even public keys) need to call `psa_crypto_init()` before any cryptographic operation or key management operation.
See also [function prototype changes](#function-prototype-changes), many of which are related to the move from RNG callbacks to a global RNG.
### Impact on the library configuration
Mbed TLS follows the configuration of TF-PSA-Crypto with respect to cryptographic mechanisms. They are now based on `PSA_WANT_xxx` macros instead of legacy configuration macros such as `MBEDTLS_RSA_C`, `MBEDTLS_PKCS1_V15`, etc. The configuration of X.509 and TLS is not directly affected by the configuration. However, applications and middleware that rely on these configuration symbols to know which cryptographic mechanisms to support will need to migrate to `PSA_WANT_xxx` macros. For more information, consult the PSA transition guide in TF-PSA-Crypto.

1318
docs/psa-transition.md
View File

File diff suppressed because it is too large Load Diff

41
doxygen/input/doc_mainpage.h
View File

@@ -12,8 +12,41 @@
/**
* @mainpage Mbed TLS v4.0.0 API Documentation
*
* This documentation describes the internal structure of Mbed TLS. It was
* automatically generated from specially formatted comment blocks in
* Mbed TLS's source code using Doxygen. (See
* https://www.doxygen.nl for more information on Doxygen)
* This documentation describes the application programming interface (API)
* of Mbed TLS.
* It was automatically generated from specially formatted comment blocks in
* Mbed TLS's source code using [Doxygen](https://www.doxygen.nl).
*
* ## Main entry points
*
* You can explore the full API from the “Files” or “Files list” section.
* Locate the header file for the module that you are interested in and
* explore its contents.
*
* Some parts of the API are best explored from the “Topics” or
* “Group list” section.
* This is notably the case for the PSA Cryptography API.
* Note that many parts of the API are not classified under a topic and
* can only be seen through the file structure.
*
* For information on configuring the library at compile time, see the
* configuration header files mbedtls/mbedtls_config.h and
* psa/crypto_config.h.
*
* ## Private interfaces
*
* For technical reasons, the rendered documentation includes elements
* that are not considered part of the stable API. Private elements may
* be removed or may have their semantics changed in a future minor release
* without notice.
*
* The following elements are considered private:
*
* - Any header file whose path contains `/private`, and its contents
* (unless re-exported and documented in another non-private header).
* - Any structure or union field whose name starts with `private_`.
* - Any preprocessor macro that is just listed with its automatically
* rendered parameter list, value and location. Macros are part of
* the API only if their documentation has custom text.
*
*/