Formally deprecate the DES module

[gilles-peskine-arm]

Triple-DES (a.k.a 3DES a.k.a. DES3) is on its way out. NIST SP 800-131A disallows TDEA encryption after 31 December 2023 (decryption of legacy data remains allowed). 3DES was widely deprecated for TLS after Sweet32 in 2016, and we removed 3DES in TLS in Mbed TLS 3.0. Today, the main use of (3)DES in Mbed TLS is to support encrypted PEM files.

Currently (as of Mbed TLS 3.3.0), we have warnings in the documentation saying not to use single-key DES. Our plans regarding DES and 3DES are:

1. Extend the warnings to 3DES as well.
2. Formally deprecate the DES module.
3. Have equivalent test coverage with and without PEM: pem, pkcs5, pkparse and x509write.
4. In Mbed TLS 4.0, remove all support for DES (including 3DES).

The goal of this task is to deprecate DES (including 3DES). That is:

• The documentation of the DES module, and any other function or constant that explicitly refers to DES, should state that DES is deprecated, with a \deprecated Doxygen directive. (enum constants might be excluded from \deprecated if that's a problem, because we don't exclude them from the build.)
• DES-specific functions should be declared with an MBEDTLS_DEPRECATED annotation.
• DES-specific constants should be declared with MBEDTLS_DEPRECATED_NUMERIC_CONSTANT (or MBEDTLS_DEPRECATED_STRING_CONSTANT if applicable).

This may require tweaking some CI scripts to disable MBEDTLS_DES_C when testing with MBEDTLS_DEPRECATED_WARNING or MBEDTLS_DEPRECATED_REMOVED.

[GiPa-renesas]

TDES is still widely accepted and used within payment industry (PCI etc). Although a migration to AES/ECC is being considered and planned, also in light of future PQC crypto algorithms, it is still part of the requirements. Therefore, making the API deprecated (or rather say 'not recommended for new designs') is maybe ok but removing the support completely might have an impact.

[mpg]

Note: des.h will be made internal (non-public), see #8663

[gilles-peskine-arm]

It's too late to announce DES as deprecated in Mbed TLS 3.x. But since more time has passed, we are considering completely removing DES in Mbed TLS 4.