Merge pull request #7023 from daverodgman/3DES-warning-2.28

Backport 2.28: Improve warnings for DES/3DES
Mbed-TLS · Feb 3, 2023 · c87dc5f · c87dc5f
2 parents a4f9148 + b6c5d04
commit c87dc5f
Show file tree

Hide file tree

Showing 3 changed files with 64 additions and 28 deletions.
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
@@ -83,16 +83,16 @@ extern "C" {
 /**
  * \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 @@ typedef enum {
 /**
  * \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 @@ typedef enum {
     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 @@ typedef enum {
 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
@@ -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
@@ -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 @@ extern "C" {
 /**
  * \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 @@ mbedtls_des_context;
 
 /**
  * \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 @@ mbedtls_des3_context;
  *
  * \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 @@ void mbedtls_des_init(mbedtls_des_context *ctx);
  *
  * \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,13 +111,21 @@ void mbedtls_des_free(mbedtls_des_context *ctx);
  * \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);
 
 /**
  * \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 @@ void mbedtls_des3_free(mbedtls_des3_context *ctx);
  *
  * \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 @@ void mbedtls_des_key_set_parity(unsigned char key[MBEDTLS_DES_KEY_SIZE]);
  *
  * \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 @@ int mbedtls_des_key_check_key_parity(const unsigned char key[MBEDTLS_DES_KEY_SIZ
  *
  * \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 @@ int mbedtls_des_key_check_weak(const unsigned char key[MBEDTLS_DES_KEY_SIZE]);
  *
  * \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 @@ int mbedtls_des_setkey_enc(mbedtls_des_context *ctx, const unsigned char key[MBE
  *
  * \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 @@ int mbedtls_des_setkey_dec(mbedtls_des_context *ctx, const unsigned char key[MBE
  * \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 @@ int mbedtls_des3_set2key_enc(mbedtls_des3_context *ctx,
  * \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 @@ int mbedtls_des3_set2key_dec(mbedtls_des3_context *ctx,
  * \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 @@ int mbedtls_des3_set3key_enc(mbedtls_des3_context *ctx,
  * \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 @@ int mbedtls_des3_set3key_dec(mbedtls_des3_context *ctx,
  *
  * \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 @@ int mbedtls_des_crypt_ecb(mbedtls_des_context *ctx,
  * \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 @@ int mbedtls_des_crypt_cbc(mbedtls_des_context *ctx,
  * \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 @@ int mbedtls_des3_crypt_ecb(mbedtls_des3_context *ctx,
  * \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 @@ int mbedtls_des3_crypt_cbc(mbedtls_des3_context *ctx,
  * \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.
  */