Merge pull request #9457 from gilles-peskine-arm/announce-4.0-removals-202408
3.6 only: Announce the main removals planned for 4.0
diff --git a/ChangeLog.d/announce-4.0-removals.txt b/ChangeLog.d/announce-4.0-removals.txt
new file mode 100644
index 0000000..bf941e2
--- /dev/null
+++ b/ChangeLog.d/announce-4.0-removals.txt
@@ -0,0 +1,39 @@
+New deprecations
+ * The following cryptographic mechanisms are planned to be removed
+ in 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.
+ * 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;
+ - 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) 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
+ 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.