Add documentation warnings for weak algorithms
MD2, MD4, MD5, DES and SHA-1 are considered weak and their use
constitutes a security risk. If possible, we recommend avoiding
dependencies on them, and considering stronger message digests and
ciphers instead.
diff --git a/include/polarssl/des.h b/include/polarssl/des.h
index 3f7236c..59538a3 100644
--- a/include/polarssl/des.h
+++ b/include/polarssl/des.h
@@ -20,6 +20,10 @@
* You should have received a copy of the GNU General Public License along
* with this program; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers instead.
+ *
*/
#ifndef POLARSSL_DES_H
#define POLARSSL_DES_H
@@ -56,6 +60,10 @@
/**
* \brief DES context structure
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
typedef struct
{
@@ -78,6 +86,10 @@
* \brief Initialize DES context
*
* \param ctx DES context to be initialized
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
void des_init( des_context *ctx );
@@ -85,6 +97,10 @@
* \brief Clear DES context
*
* \param ctx DES context to be cleared
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
void des_free( des_context *ctx );
@@ -109,6 +125,10 @@
* a parity bit to allow verification.
*
* \param key 8-byte secret key
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
void des_key_set_parity( unsigned char key[DES_KEY_SIZE] );
@@ -121,6 +141,10 @@
* \param key 8-byte secret key
*
* \return 0 is parity was ok, 1 if parity was not correct.
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
int des_key_check_key_parity( const unsigned char key[DES_KEY_SIZE] );
@@ -130,6 +154,10 @@
* \param key 8-byte secret key
*
* \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
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
int des_key_check_weak( const unsigned char key[DES_KEY_SIZE] );
@@ -140,6 +168,10 @@
* \param key 8-byte secret key
*
* \return 0
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
int des_setkey_enc( des_context *ctx, const unsigned char key[DES_KEY_SIZE] );
@@ -150,6 +182,10 @@
* \param key 8-byte secret key
*
* \return 0
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
int des_setkey_dec( des_context *ctx, const unsigned char key[DES_KEY_SIZE] );
@@ -205,6 +241,10 @@
* \param output 64-bit output block
*
* \return 0 if successful
+ *
+ * \warning DES is considered a weak cipher and its use constitutes a
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
int des_crypt_ecb( des_context *ctx,
const unsigned char input[8],
@@ -228,6 +268,10 @@
* \param iv initialization vector (updated after use)
* \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
+ * security risk. We recommend considering stronger ciphers
+ * instead.
*/
int des_crypt_cbc( des_context *ctx,
int mode,