From 1b240c7ec1fb8507c94ea5074d97d9dde51bc622 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 7 Aug 2024 22:38:52 +0200 Subject: [PATCH 1/9] Announce the main removals planned for 4.0 Signed-off-by: Gilles Peskine --- ChangeLog.d/announce-4.0-removals.txt | 29 +++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 ChangeLog.d/announce-4.0-removals.txt diff --git a/ChangeLog.d/announce-4.0-removals.txt b/ChangeLog.d/announce-4.0-removals.txt new file mode 100644 index 0000000000..9ae61c1219 --- /dev/null +++ b/ChangeLog.d/announce-4.0-removals.txt @@ -0,0 +1,29 @@ +New deprecations + * The following cryptographic mechanisms are planned to be removed + in Mbed TLS 4.0: + - DES (including 3DES). + - PKCS#1v1.5 encryption (RSA-PKCS1-v1_5). (OAEP, PSS, and PKCS#1v1.5 + signature are staying.) + - Finite-field Diffie-Hellman with custom groups. (RFC 7919 remain + supported.) + - Elliptic curves of size 225 bits or less. + * The following mechanisms are planned to be removed from (D)TLS 1.2 + in Mbed TLS 4.0: + - RSA decryption (i.e. cipher suites using RSA without a key exchange: + cipher suites using an RSA signature and ECDHE are staying). + - Static ECDH (ephemeral ECDH, i.e. cipher suites using ECDHE, is staying). + - Finite-field Diffie-Hellman (i.e. DHE; ECDHE is staying) + - All cipher suites using CBC. + * The following low-level interfaces are planned to be removed from the + public API in Mbed TLS 4.0: + - Hashes: md5.h, ripemd160.h, sha1.h, sha3.h, sha256.h, sha512.h; + - Pseudorandom generation: ctr_drbg.h, hmac_drbg.h. + - Cipher primitives: aes.h, aria.h, camellia.h, chacha20.h, + chachapoly.h, poly1305.h; + - Cipher modes: ccm.h, cipher.h, cmac.h, gcm.h, hkdf.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 in + Mbed TLS 2.17.0) and, where relevant, PK. From aada0c869f8b710fb64d8a4d9df00e9b829d85b0 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 7 Aug 2024 23:05:45 +0200 Subject: [PATCH 2/9] Mention the PSA transition guide Signed-off-by: Gilles Peskine --- ChangeLog.d/announce-4.0-removals.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ChangeLog.d/announce-4.0-removals.txt b/ChangeLog.d/announce-4.0-removals.txt index 9ae61c1219..65f48468f1 100644 --- a/ChangeLog.d/announce-4.0-removals.txt +++ b/ChangeLog.d/announce-4.0-removals.txt @@ -27,3 +27,5 @@ New deprecations The cryptographic mechanisms remain present, but they will only be accessible via the PSA API (psa_xxx functions introduced in Mbed TLS 2.17.0) and, where relevant, PK. + For guidance on migrating application code to the PSA API, please consult + the PSA transition guide (docs/psa-transition.md). From 5e64de034e072a6d563610bdfb4d47448d2cdde8 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 8 Aug 2024 14:41:12 +0200 Subject: [PATCH 3/9] Fix missing bits in crypto mechanisms Signed-off-by: Gilles Peskine --- ChangeLog.d/announce-4.0-removals.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ChangeLog.d/announce-4.0-removals.txt b/ChangeLog.d/announce-4.0-removals.txt index 65f48468f1..02de358dfd 100644 --- a/ChangeLog.d/announce-4.0-removals.txt +++ b/ChangeLog.d/announce-4.0-removals.txt @@ -2,10 +2,10 @@ New deprecations * The following cryptographic mechanisms are planned to be removed in Mbed TLS 4.0: - DES (including 3DES). - - PKCS#1v1.5 encryption (RSA-PKCS1-v1_5). (OAEP, PSS, and PKCS#1v1.5 - signature are staying.) - - Finite-field Diffie-Hellman with custom groups. (RFC 7919 remain - supported.) + - 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 mechanisms are planned to be removed from (D)TLS 1.2 in Mbed TLS 4.0: From 086bc911792aedc4b243bf09ffeeccc7cd6e5cc9 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 8 Aug 2024 14:45:35 +0200 Subject: [PATCH 4/9] Improve mechanism grouping Signed-off-by: Gilles Peskine --- ChangeLog.d/announce-4.0-removals.txt | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/ChangeLog.d/announce-4.0-removals.txt b/ChangeLog.d/announce-4.0-removals.txt index 02de358dfd..d9bbd16338 100644 --- a/ChangeLog.d/announce-4.0-removals.txt +++ b/ChangeLog.d/announce-4.0-removals.txt @@ -16,11 +16,10 @@ New deprecations - All cipher suites using CBC. * The following low-level interfaces are planned to be removed from the public API in Mbed TLS 4.0: - - Hashes: md5.h, ripemd160.h, sha1.h, sha3.h, sha256.h, sha512.h; - - Pseudorandom generation: ctr_drbg.h, hmac_drbg.h. - - Cipher primitives: aes.h, aria.h, camellia.h, chacha20.h, - chachapoly.h, poly1305.h; - - Cipher modes: ccm.h, cipher.h, cmac.h, gcm.h, hkdf.h; + - Hashes: hkdf.h, md5.h, ripemd160.h, sha1.h, sha3.h, sha256.h, sha512.h; + - Pseudorandom generation: ctr_drbg.h, hmac_drbg.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. From 6df289a56fd2c6c65423d585c30a218cd70d4a1b Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 8 Aug 2024 14:45:57 +0200 Subject: [PATCH 5/9] More relevant characterisation of PSA being from before 3.0 Signed-off-by: Gilles Peskine --- ChangeLog.d/announce-4.0-removals.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ChangeLog.d/announce-4.0-removals.txt b/ChangeLog.d/announce-4.0-removals.txt index d9bbd16338..aac1f7d217 100644 --- a/ChangeLog.d/announce-4.0-removals.txt +++ b/ChangeLog.d/announce-4.0-removals.txt @@ -24,7 +24,7 @@ New deprecations - 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 in - Mbed TLS 2.17.0) and, where relevant, PK. + accessible via the PSA API (psa_xxx functions introduced before + Mbed TLS 2.28.0) and, where relevant, PK. For guidance on migrating application code to the PSA API, please consult the PSA transition guide (docs/psa-transition.md). From a11687e543e47e9984e0de4593d0bc462125a8bd Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 8 Aug 2024 14:58:35 +0200 Subject: [PATCH 6/9] Revised presentation of cipher suites Include patterns on the official names. Signed-off-by: Gilles Peskine --- ChangeLog.d/announce-4.0-removals.txt | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/ChangeLog.d/announce-4.0-removals.txt b/ChangeLog.d/announce-4.0-removals.txt index aac1f7d217..5942e3adb5 100644 --- a/ChangeLog.d/announce-4.0-removals.txt +++ b/ChangeLog.d/announce-4.0-removals.txt @@ -7,13 +7,16 @@ New deprecations - Finite-field Diffie-Hellman with custom groups. (RFC 7919 groups remain supported.) - Elliptic curves of size 225 bits or less. - * The following mechanisms are planned to be removed from (D)TLS 1.2 + * The following cipher suites are planned to be removed from (D)TLS 1.2 in Mbed TLS 4.0: - - RSA decryption (i.e. cipher suites using RSA without a key exchange: - cipher suites using an RSA signature and ECDHE are staying). - - Static ECDH (ephemeral ECDH, i.e. cipher suites using ECDHE, is staying). - - Finite-field Diffie-Hellman (i.e. DHE; ECDHE is staying) - - All cipher suites using CBC. + - 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. * The following low-level interfaces are planned to be removed from the public API in Mbed TLS 4.0: - Hashes: hkdf.h, md5.h, ripemd160.h, sha1.h, sha3.h, sha256.h, sha512.h; From ee7332104d1a18121d3c39edb1a1b1b3b4674cf3 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Sat, 10 Aug 2024 17:22:45 +0200 Subject: [PATCH 7/9] Mention interfaces replaced by PSA drivers Signed-off-by: Gilles Peskine --- ChangeLog.d/announce-4.0-removals.txt | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/ChangeLog.d/announce-4.0-removals.txt b/ChangeLog.d/announce-4.0-removals.txt index 5942e3adb5..ba78386407 100644 --- a/ChangeLog.d/announce-4.0-removals.txt +++ b/ChangeLog.d/announce-4.0-removals.txt @@ -17,8 +17,8 @@ New deprecations - 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. - * The following low-level interfaces are planned to be removed from the - public API in Mbed TLS 4.0: + * The following low-level application interfaces are planned to be removed + from the public API in Mbed TLS 4.0: - Hashes: hkdf.h, md5.h, ripemd160.h, sha1.h, sha3.h, sha256.h, sha512.h; - Pseudorandom generation: ctr_drbg.h, hmac_drbg.h; - Ciphers and modes: aes.h, aria.h, camellia.h, chacha20.h, chachapoly.h, @@ -31,3 +31,9 @@ New deprecations Mbed TLS 2.28.0) and, where relevant, PK. For guidance on migrating application code to the PSA API, please consult the PSA transition guide (docs/psa-transition.md). + * The following integration interfaces are planned to be removed + in Mbed TLS 4.0: + - MBEDTLS_xxx_ALT replacement of cryptographic modules and functions. + Use PSA transparent drivers instead. + - MBEDTLS_PK_RSA_ALT and MBEDTLS_PSA_CRYPTO_SE_C. + Use PSA opaque drivers instead. From ce629a6ce7b1d0af15485d7fd7f5eb3800e01798 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 12 Aug 2024 11:21:10 +0200 Subject: [PATCH 8/9] entropy.h is also going away Signed-off-by: Gilles Peskine --- ChangeLog.d/announce-4.0-removals.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ChangeLog.d/announce-4.0-removals.txt b/ChangeLog.d/announce-4.0-removals.txt index ba78386407..49dbf802b0 100644 --- a/ChangeLog.d/announce-4.0-removals.txt +++ b/ChangeLog.d/announce-4.0-removals.txt @@ -20,7 +20,7 @@ New deprecations * The following low-level application interfaces are planned to be removed from the public API in Mbed TLS 4.0: - Hashes: hkdf.h, md5.h, ripemd160.h, sha1.h, sha3.h, sha256.h, sha512.h; - - Pseudorandom generation: ctr_drbg.h, hmac_drbg.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. From 47bf23f74887aca4384b023a6921444a52b03c4e Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 12 Aug 2024 11:21:54 +0200 Subject: [PATCH 9/9] PSA PAKE wasn't in 2.28 Signed-off-by: Gilles Peskine --- ChangeLog.d/announce-4.0-removals.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ChangeLog.d/announce-4.0-removals.txt b/ChangeLog.d/announce-4.0-removals.txt index 49dbf802b0..bf941e22a2 100644 --- a/ChangeLog.d/announce-4.0-removals.txt +++ b/ChangeLog.d/announce-4.0-removals.txt @@ -27,8 +27,8 @@ New deprecations - 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 before - Mbed TLS 2.28.0) and, where relevant, PK. + accessible via the PSA API (psa_xxx functions introduced gradually + starting with Mbed TLS 2.17) and, where relevant, `pk.h`. For guidance on migrating application code to the PSA API, please consult the PSA transition guide (docs/psa-transition.md). * The following integration interfaces are planned to be removed