Hello,

Following consultations with the community and internal discussions among the Mbed TLS maintenance team, we can now present the major changes that will happen in the next major version of Mbed TLS. Our plan remains to release in the second quarter of 2025.

The next major version will focus on two things:

The cryptography library will be a separate product called TF-PSA-Crypto 1.0. The X.509 and TLS library will be called Mbed TLS 4.0, and will rely on TF-PSA-Crypto for all cryptographic functionality.
This release completes the migration of cryptography APIs from classic mbedtls APIs to PSA APIs.

Please find more information below about what this means in practice. What follows are just headlines, not an exhaustive list of changes. We expect many small changes that do not affect major functionality.

Please note that the changes presented here are our current plan. We may revise it based on new inputs, new insights or unexpected hurdles. You can follow the advancement of the design, planning and development of the next release on the 4.0+1.0 planning board at https://github.com/orgs/Mbed-TLS/projects/15/views/1 .

Removal of legacy APIs

The following low-level application interfaces will no longer be present in the API of TF-PSA-Crypto 1.0 and Mbed TLS 4.0:

Hashes: hkdf.h, md5.h, ripemd160.h, sha1.h, sha3.h, sha256.h, sha512.h;
Random generation: ctr_drbg.h, hmac_drbg.h, entropy.h;
Ciphers and modes: aes.h, aria.h, camellia.h, chacha20.h, chachapoly.h, cipher.h, cmac.h, gcm.h, poly1305.h;
Private key encryption mechanisms: pkcs5.h, pkcs12.h.
Asymmetric cryptography: bignum.h, dhm.h, ecdh.h, ecdsa.h, ecjpake.h, ecp.h, rsa.h.

The cryptographic mechanisms remain present, but they will only be accessible via the PSA API (psa_xxx functions introduced gradually starting with Mbed TLS 2.17).

If you maintain code that uses these interfaces, you can already start migrating it today, since almost all PSA interfaces are available in the mbedtls-3.6 long-time support branch (and many even in 2.28 LTS). Please consult the PSA transition guide https://github.com/Mbed-TLS/mbedtls/blob/mbedtls-3.6/docs/psa-transition.md for guidance.

Some non-PSA crypto interfaces will still be present in TF-PSA-Crypto 1.0:

pk.h will remain with some changes, mainly to provide an interface to key parsing and formatting which does not have a PSA equivalent yet.
md.h will remain as a thin layer over PSA hash functions (not HMAC) to ease the transition.
nist_kw.h will remain because it does not have a PSA equivalent yet.

Removal of legacy integration interfaces

TF-PSA-Crypto 1.0 and Mbed TLS 4.0 will no longer support MBEDTLS_xxx_ALT replacement of functions and modules. Use PSA transparent drivers instead.

TF-PSA-Crypto 1.0 and Mbed TLS 4.0 will no longer support MBEDTLS_PK_RSA_ALT and MBEDTLS_PSA_CRYPTO_SE_C. Use PSA opaque drivers instead.

TF-PSA-Crypto 1.0 and Mbed TLS 4.0 will no longer have the mbedtls/entropy.h interface to configure entropy sources. This will be replaced by PSA random drivers.

In addition, we are planning to rework the platform abstraction layer (MBEDTLS_PLATFORM_xxx configuration options). More details will be available in the coming months.

Removal of legacy mechanisms

The following cryptographic mechanisms are planned to be removed in TF-PSA-Crypto 1.0 and Mbed TLS 4.0:

DES (including 3DES).
PKCS#1v1.5 encryption/decryption (RSAES-PKCS1-v1_5). (OAEP, PSS, and PKCS#1v1.5 signature are staying.)
Finite-field Diffie-Hellman with custom groups. (RFC 7919 groups remain supported.)
Elliptic curves of size 225 bits or less.

The following cipher suites are planned to be removed from (D)TLS 1.2 in Mbed TLS 4.0:

TLS_RSA_* (including TLS_RSA_PSK_*), i.e. cipher suites using RSA decryption. (RSA signatures, i.e. TLS_ECDHE_RSA_*, are staying.)
TLS_ECDH_*, i.e. cipher suites using static ECDH. (Ephemeral ECDH, i.e. TLS_ECDHE_*, is staying.)
TLS_DHE_*, i.e. cipher suites using finite-field Diffie-Hellman. (Ephemeral ECDH, i.e. TLS_ECDHE_*, is staying.)
TLS_*CBC*, i.e. all cipher suites using CBC.

Non-functional changes

Due to the separation into two separate products (TF-PSA-Crypto and Mbed TLS), there will be major changes to the directory structure and to the build system. We plan to use CMake as the primary build system.

Since TF-PSA-Crypto is a new product, identifiers that are not PSA interfaces (such as optimisation options and platform interfaces) will be renamed with a new prefix.

Best regards,

--
Gilles Peskine
Mbed TLS developer