Merge pull request #7023 from daverodgman/3DES-warning-2.28
Backport 2.28: Improve warnings for DES/3DES
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index 02421e4..aa155d7 100644
--- a/include/mbedtls/cipher.h
+++ b/include/mbedtls/cipher.h
@@ -83,16 +83,16 @@
/**
* \brief Supported cipher types.
*
- * \warning RC4 and DES are considered weak ciphers and their use
- * constitutes a security risk. Arm recommends considering stronger
+ * \warning RC4 and DES/3DES are considered weak ciphers and their use
+ * constitutes a security risk. We recommend considering stronger
* ciphers instead.
*/
typedef enum {
MBEDTLS_CIPHER_ID_NONE = 0, /**< Placeholder to mark the end of cipher ID lists. */
MBEDTLS_CIPHER_ID_NULL, /**< The identity cipher, treated as a stream cipher. */
MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */
- MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. */
- MBEDTLS_CIPHER_ID_3DES, /**< The Triple DES cipher. */
+ MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. \warning DES is considered weak. */
+ MBEDTLS_CIPHER_ID_3DES, /**< The Triple DES cipher. \warning 3DES is considered weak. */
MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */
MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */
MBEDTLS_CIPHER_ID_ARC4, /**< The RC4 cipher. */
@@ -103,8 +103,8 @@
/**
* \brief Supported {cipher type, cipher mode} pairs.
*
- * \warning RC4 and DES are considered weak ciphers and their use
- * constitutes a security risk. Arm recommends considering stronger
+ * \warning RC4 and DES/3DES are considered weak ciphers and their use
+ * constitutes a security risk. We recommend considering stronger
* ciphers instead.
*/
typedef enum {
@@ -140,12 +140,12 @@
MBEDTLS_CIPHER_CAMELLIA_128_GCM, /**< Camellia cipher with 128-bit GCM mode. */
MBEDTLS_CIPHER_CAMELLIA_192_GCM, /**< Camellia cipher with 192-bit GCM mode. */
MBEDTLS_CIPHER_CAMELLIA_256_GCM, /**< Camellia cipher with 256-bit GCM mode. */
- MBEDTLS_CIPHER_DES_ECB, /**< DES cipher with ECB mode. */
- MBEDTLS_CIPHER_DES_CBC, /**< DES cipher with CBC mode. */
- MBEDTLS_CIPHER_DES_EDE_ECB, /**< DES cipher with EDE ECB mode. */
- MBEDTLS_CIPHER_DES_EDE_CBC, /**< DES cipher with EDE CBC mode. */
- MBEDTLS_CIPHER_DES_EDE3_ECB, /**< DES cipher with EDE3 ECB mode. */
- MBEDTLS_CIPHER_DES_EDE3_CBC, /**< DES cipher with EDE3 CBC mode. */
+ MBEDTLS_CIPHER_DES_ECB, /**< DES cipher with ECB mode. \warning DES is considered weak. */
+ MBEDTLS_CIPHER_DES_CBC, /**< DES cipher with CBC mode. \warning DES is considered weak. */
+ MBEDTLS_CIPHER_DES_EDE_ECB, /**< DES cipher with EDE ECB mode. \warning 3DES is considered weak. */
+ MBEDTLS_CIPHER_DES_EDE_CBC, /**< DES cipher with EDE CBC mode. \warning 3DES is considered weak. */
+ MBEDTLS_CIPHER_DES_EDE3_ECB, /**< DES cipher with EDE3 ECB mode. \warning 3DES is considered weak. */
+ MBEDTLS_CIPHER_DES_EDE3_CBC, /**< DES cipher with EDE3 CBC mode. \warning 3DES is considered weak. */
MBEDTLS_CIPHER_BLOWFISH_ECB, /**< Blowfish cipher with ECB mode. */
MBEDTLS_CIPHER_BLOWFISH_CBC, /**< Blowfish cipher with CBC mode. */
MBEDTLS_CIPHER_BLOWFISH_CFB64, /**< Blowfish cipher with CFB64 mode. */
@@ -226,11 +226,11 @@
enum {
/** Undefined key length. */
MBEDTLS_KEY_LENGTH_NONE = 0,
- /** Key length, in bits (including parity), for DES keys. */
+ /** Key length, in bits (including parity), for DES keys. \warning DES is considered weak. */
MBEDTLS_KEY_LENGTH_DES = 64,
- /** Key length in bits, including parity, for DES in two-key EDE. */
+ /** Key length in bits, including parity, for DES in two-key EDE. \warning 3DES is considered weak. */
MBEDTLS_KEY_LENGTH_DES_EDE = 128,
- /** Key length in bits, including parity, for DES in three-key EDE. */
+ /** Key length in bits, including parity, for DES in three-key EDE. \warning 3DES is considered weak. */
MBEDTLS_KEY_LENGTH_DES_EDE3 = 192,
};
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 9a2de67..5dcbdd1 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -2765,7 +2765,7 @@
*
* PEM_PARSE uses DES/3DES for decrypting encrypted keys.
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers instead.
*/
#define MBEDTLS_DES_C
diff --git a/include/mbedtls/des.h b/include/mbedtls/des.h
index 2944d5c..f2bc581 100644
--- a/include/mbedtls/des.h
+++ b/include/mbedtls/des.h
@@ -3,7 +3,7 @@
*
* \brief DES block cipher
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*/
@@ -60,7 +60,7 @@
/**
* \brief DES context structure
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*/
@@ -71,6 +71,10 @@
/**
* \brief Triple-DES context structure
+ *
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
typedef struct mbedtls_des3_context {
uint32_t sk[96]; /*!< 3DES subkeys */
@@ -86,7 +90,7 @@
*
* \param ctx DES context to be initialized
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*/
@@ -97,7 +101,7 @@
*
* \param ctx DES context to be cleared
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*/
@@ -107,6 +111,10 @@
* \brief Initialize Triple-DES context
*
* \param ctx DES3 context to be initialized
+ *
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
void mbedtls_des3_init(mbedtls_des3_context *ctx);
@@ -114,6 +122,10 @@
* \brief Clear Triple-DES context
*
* \param ctx DES3 context to be cleared
+ *
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
void mbedtls_des3_free(mbedtls_des3_context *ctx);
@@ -125,7 +137,7 @@
*
* \param key 8-byte secret key
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*/
@@ -141,7 +153,7 @@
*
* \return 0 is parity was ok, 1 if parity was not correct.
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*/
@@ -155,7 +167,7 @@
*
* \return 0 if no weak key was found, 1 if a weak key was identified.
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*/
@@ -170,7 +182,7 @@
*
* \return 0
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*/
@@ -185,7 +197,7 @@
*
* \return 0
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*/
@@ -199,6 +211,10 @@
* \param key 16-byte secret key
*
* \return 0
+ *
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
MBEDTLS_CHECK_RETURN_TYPICAL
int mbedtls_des3_set2key_enc(mbedtls_des3_context *ctx,
@@ -211,6 +227,10 @@
* \param key 16-byte secret key
*
* \return 0
+ *
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
MBEDTLS_CHECK_RETURN_TYPICAL
int mbedtls_des3_set2key_dec(mbedtls_des3_context *ctx,
@@ -223,6 +243,10 @@
* \param key 24-byte secret key
*
* \return 0
+ *
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
MBEDTLS_CHECK_RETURN_TYPICAL
int mbedtls_des3_set3key_enc(mbedtls_des3_context *ctx,
@@ -235,6 +259,10 @@
* \param key 24-byte secret key
*
* \return 0
+ *
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
MBEDTLS_CHECK_RETURN_TYPICAL
int mbedtls_des3_set3key_dec(mbedtls_des3_context *ctx,
@@ -249,7 +277,7 @@
*
* \return 0 if successful
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*/
@@ -277,7 +305,7 @@
* \param input buffer holding the input data
* \param output buffer holding the output data
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*/
@@ -298,6 +326,10 @@
* \param output 64-bit output block
*
* \return 0 if successful
+ *
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
MBEDTLS_CHECK_RETURN_TYPICAL
int mbedtls_des3_crypt_ecb(mbedtls_des3_context *ctx,
@@ -324,6 +356,10 @@
* \param output buffer holding the output data
*
* \return 0 if successful, or MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH
+ *
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
MBEDTLS_CHECK_RETURN_TYPICAL
int mbedtls_des3_crypt_cbc(mbedtls_des3_context *ctx,
@@ -342,7 +378,7 @@
* \param SK Round keys
* \param key Base key
*
- * \warning DES is considered a weak cipher and its use constitutes a
+ * \warning DES/3DES are considered weak ciphers and their use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*/