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:
1. 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. 2. 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,
Hello,
Do I understand correctly that you are removing AES?
Peter
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 APIsThe 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 mechanismsThe 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 via Mbed-tls-announce mbed-tls-announce@lists.trustedfirmware.org wrote: > 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:
> 1. 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. > 2. This release completes the migration of cryptography APIs from > classic mbedtls APIs to PSA APIs.
I think "this release" refers to MBED TLS 4.0
Can you tell us a bit about how TF-PSA-Crypto's release schedule will differ from or depend upon, or support, MBED TLS 4.x releases? Also symmantic versioning? 1.0.0 and 4.0.0?
Can we expect PSA-Crypto 1.x.y to remain stable, API-wise, particularly internal-API to crypto-off-load, over longer periods of time than MBED TLS?
> 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.
Fantastic.
> 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.
THat feels like too many changes for 4.*0*/1.*0*
> The following cryptographic mechanisms are planned to be removed in > TF-PSA-Crypto 1.0 and Mbed TLS 4.0:
> * DES (including 3DES).
Would a 3DES driver be welcome/possible? Nobody wants to use it for TLS, but there are objects on disk that might have a long lifespan.
> 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.
Sounds good.
On 14/08/2024 23:34, Michael Richardson wrote:
Gilles Peskine via Mbed-tls-announce mbed-tls-announce@lists.trustedfirmware.org wrote: > 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: > 1. 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. > 2. This release completes the migration of cryptography APIs from > classic mbedtls APIs to PSA APIs.I think "this release" refers to MBED TLS 4.0
Can you tell us a bit about how TF-PSA-Crypto's release schedule will differ from or depend upon, or support, MBED TLS 4.x releases? Also symmantic versioning? 1.0.0 and 4.0.0?
It's likely that we'll often release both together, but we don't plan to make it a rule.
We'll keep semantic versioning for both products.
Can we expect PSA-Crypto 1.x.y to remain stable, API-wise, particularly internal-API to crypto-off-load, over longer periods of time than MBED TLS?
For the application-facing interface, I hope so. We're following a specification that's officially maintained by a different team.
For the driver interface, I also hope that we can make it stable in the long term, but I'm still unsure whether we'll be able to freeze it in the 1.0.0 release. There are still unresolved issues like callbacks and thread safety which may require backward-incompatible changes in some cases. We're also behind on tooling and testing, and that might reveal issues that require tweaking the interface. Please see https://github.com/Mbed-TLS/TF-PSA-Crypto/issues/99 if you'd like to follow the discussion or chime in.
> 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.Fantastic.
> 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.THat feels like too many changes for 4.*0*/1.*0*
It does, sometimes, when I look at the planning board. On the other hand, when I look at every single item on there, I think “oh, I'll be glad not to have to maintain the old version anymore”.
> The following cryptographic mechanisms are planned to be removed in > TF-PSA-Crypto 1.0 and Mbed TLS 4.0: > * DES (including 3DES).Would a 3DES driver be welcome/possible? Nobody wants to use it for TLS, but there are objects on disk that might have a long lifespan.
No, sorry. DES isn't much but it tends to infect many little places, like buffer size calculations, rejection of weak keys, etc. That being said, if the use case is specifically to read DES-encrypted private keys, maybe we could keep that as a possibility, without making DES itself directly available through the API? If you strongly want that, please file a feature request.
> 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.Sounds good.
Best regards,
-- Gilles
mbed-tls@lists.trustedfirmware.org
-
Gilles Peskine -
Michael Richardson -
Peter