From bbca8c5d3c531cb26cad0a642cbdf48287a79cab Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Mon, 25 Sep 2017 14:53:51 +0100 Subject: [PATCH] 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. --- include/mbedtls/arc4.h | 35 +++++++++++++++++- include/mbedtls/cipher.h | 14 +++++++ include/mbedtls/config.h | 64 ++++++++++++++++++++++++++++++-- include/mbedtls/des.h | 49 ++++++++++++++++++++++++ include/mbedtls/md.h | 8 ++++ include/mbedtls/md2.h | 80 ++++++++++++++++++++++++++++++++++++++++ include/mbedtls/md4.h | 79 +++++++++++++++++++++++++++++++++++++++ include/mbedtls/md5.h | 79 +++++++++++++++++++++++++++++++++++++++ include/mbedtls/sha1.h | 79 +++++++++++++++++++++++++++++++++++++++ 9 files changed, 482 insertions(+), 5 deletions(-) diff --git a/include/mbedtls/arc4.h b/include/mbedtls/arc4.h index 875c57431..f9d93f822 100644 --- a/include/mbedtls/arc4.h +++ b/include/mbedtls/arc4.h @@ -2,6 +2,9 @@ * \file arc4.h * * \brief The ARCFOUR stream cipher + * + * \warning ARC4 is considered a weak cipher and its use constitutes a + * security risk. We recommend considering stronger ciphers instead. */ /* * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved @@ -20,6 +23,7 @@ * limitations under the License. * * This file is part of mbed TLS (https://tls.mbed.org) + * */ #ifndef MBEDTLS_ARC4_H #define MBEDTLS_ARC4_H @@ -43,7 +47,11 @@ extern "C" { #endif /** - * \brief ARC4 context structure + * \brief ARC4 context structure + * + * \warning ARC4 is considered a weak cipher and its use constitutes a + * security risk. We recommend considering stronger ciphers instead. + * */ typedef struct { @@ -57,6 +65,11 @@ mbedtls_arc4_context; * \brief Initialize ARC4 context * * \param ctx ARC4 context to be initialized + * + * \warning ARC4 is considered a weak cipher and its use constitutes a + * security risk. We recommend considering stronger ciphers + * instead. + * */ void mbedtls_arc4_init( mbedtls_arc4_context *ctx ); @@ -64,6 +77,11 @@ void mbedtls_arc4_init( mbedtls_arc4_context *ctx ); * \brief Clear ARC4 context * * \param ctx ARC4 context to be cleared + * + * \warning ARC4 is considered a weak cipher and its use constitutes a + * security risk. We recommend considering stronger ciphers + * instead. + * */ void mbedtls_arc4_free( mbedtls_arc4_context *ctx ); @@ -73,6 +91,11 @@ void mbedtls_arc4_free( mbedtls_arc4_context *ctx ); * \param ctx ARC4 context to be setup * \param key the secret key * \param keylen length of the key, in bytes + * + * \warning ARC4 is considered a weak cipher and its use constitutes a + * security risk. We recommend considering stronger ciphers + * instead. + * */ void mbedtls_arc4_setup( mbedtls_arc4_context *ctx, const unsigned char *key, unsigned int keylen ); @@ -86,6 +109,11 @@ void mbedtls_arc4_setup( mbedtls_arc4_context *ctx, const unsigned char *key, * \param output buffer for the output data * * \return 0 if successful + * + * \warning ARC4 is considered a weak cipher and its use constitutes a + * security risk. We recommend considering stronger ciphers + * instead. + * */ int mbedtls_arc4_crypt( mbedtls_arc4_context *ctx, size_t length, const unsigned char *input, unsigned char *output ); @@ -106,6 +134,11 @@ extern "C" { * \brief Checkup routine * * \return 0 if successful, or 1 if the test failed + * + * \warning ARC4 is considered a weak cipher and its use constitutes a + * security risk. We recommend considering stronger ciphers + * instead. + * */ int mbedtls_arc4_self_test( int verbose ); diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 97b9226f5..7ac0fd1a5 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -68,6 +68,13 @@ extern "C" { #endif +/** + * \brief An enumeration of supported ciphers. + * + * \warning ARC4 and DES are considered weak ciphers and their use + * constitutes a security risk. We recommend considering stronger + * ciphers instead. + */ typedef enum { MBEDTLS_CIPHER_ID_NONE = 0, MBEDTLS_CIPHER_ID_NULL, @@ -79,6 +86,13 @@ typedef enum { MBEDTLS_CIPHER_ID_ARC4, } mbedtls_cipher_id_t; +/** + * \brief An enumeration of supported (cipher, mode) pairs. + * + * \warning ARC4 and DES are considered weak ciphers and their use + * constitutes a security risk. We recommend considering stronger + * ciphers instead. + */ typedef enum { MBEDTLS_CIPHER_NONE = 0, MBEDTLS_CIPHER_NULL, diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 6f62a8772..25ae1da77 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -262,6 +262,12 @@ * * Uncomment a macro to enable alternate implementation of the corresponding * module. + * + * \warning MD2, MD4, MD5, ARC4, 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. + * */ //#define MBEDTLS_AES_ALT //#define MBEDTLS_ARC4_ALT @@ -321,6 +327,12 @@ * * Uncomment a macro to enable alternate implementation of the corresponding * function. + * + * \warning 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. + * */ //#define MBEDTLS_MD2_PROCESS_ALT //#define MBEDTLS_MD4_PROCESS_ALT @@ -525,6 +537,9 @@ * MBEDTLS_TLS_DHE_RSA_WITH_DES_CBC_SHA * * Uncomment this macro to enable weak ciphersuites + * + * \warning DES is considered a weak cipher and its use constitutes a + * security risk. We recommend considering stronger ciphers instead. */ //#define MBEDTLS_ENABLE_WEAK_CIPHERSUITES @@ -1615,6 +1630,11 @@ * MBEDTLS_TLS_RSA_WITH_RC4_128_MD5 * MBEDTLS_TLS_RSA_PSK_WITH_RC4_128_SHA * MBEDTLS_TLS_PSK_WITH_RC4_128_SHA + * + * \warning ARC4 is considered a weak cipher and its use constitutes a + * security risk. If possible, we recommend avoidng dependencies on + * it, and considering stronger ciphers instead. + * */ #define MBEDTLS_ARC4_C @@ -1841,6 +1861,9 @@ * MBEDTLS_TLS_PSK_WITH_3DES_EDE_CBC_SHA * * PEM_PARSE uses DES/3DES for decrypting encrypted keys. + * + * \warning DES is considered a weak cipher and its use constitutes a + * security risk. We recommend considering stronger ciphers instead. */ #define MBEDTLS_DES_C @@ -2020,6 +2043,11 @@ * Caller: * * Uncomment to enable support for (rare) MD2-signed X.509 certs. + * + * \warning MD2 is considered a weak message digest and its use constitutes a + * security risk. If possible, we recommend avoiding dependencies on + * it, and considering stronger message digests instead. + * */ //#define MBEDTLS_MD2_C @@ -2032,6 +2060,11 @@ * Caller: * * Uncomment to enable support for (rare) MD4-signed X.509 certs. + * + * \warning MD4 is considered a weak message digest and its use constitutes a + * security risk. If possible, we recommend avoiding dependencies on + * it, and considering stronger message digests instead. + * */ //#define MBEDTLS_MD4_C @@ -2045,8 +2078,15 @@ * library/pem.c * library/ssl_tls.c * - * This module is required for SSL/TLS and X.509. - * PEM_PARSE uses MD5 for decrypting encrypted keys. + * This module is required for SSL/TLS up to version 1.1, and for TLS 1.2 + * depending on the handshake parameters. Further, it is used for checking + * MD5-signed certificates, and for PBKDF1 when decrypting PEM-encoded + * encrypted keys. + * + * \warning MD5 is considered a weak message digest and its use constitutes a + * security risk. If possible, we recommend avoiding dependencies on + * it, and considering stronger message digests instead. + * */ #define MBEDTLS_MD5_C @@ -2309,6 +2349,11 @@ * * This module is required for SSL/TLS up to version 1.1, for TLS 1.2 * depending on the handshake parameters, and for SHA1-signed certificates. + * + * \warning SHA-1 is considered a weak message digest and its use constitutes + * a security risk. If possible, we recommend avoiding dependencies + * on it, and considering stronger message digests instead. + * */ #define MBEDTLS_SHA1_C @@ -2697,8 +2742,13 @@ * Allow SHA-1 in the default TLS configuration for certificate signing. * Without this build-time option, SHA-1 support must be activated explicitly * through mbedtls_ssl_conf_cert_profile. Turning on this option is not - * recommended because of it is possible to generte SHA-1 collisions, however + * recommended because of it is possible to generate SHA-1 collisions, however * this may be safe for legacy infrastructure where additional controls apply. + * + * \warning SHA-1 is considered a weak message digest and its use constitutes + * a security risk. If possible, we recommend avoiding dependencies + * on it, and considering stronger message digests instead. + * */ // #define MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES @@ -2709,7 +2759,13 @@ * The use of SHA-1 in TLS <= 1.1 and in HMAC-SHA-1 is always allowed by * default. At the time of writing, there is no practical attack on the use * of SHA-1 in handshake signatures, hence this option is turned on by default - * for compatibility with existing peers. + * to preserve compatibility with existing peers, but the general + * warning applies nonetheless: + * + * \warning SHA-1 is considered a weak message digest and its use constitutes + * a security risk. If possible, we recommend avoiding dependencies + * on it, and considering stronger message digests instead. + * */ #define MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE diff --git a/include/mbedtls/des.h b/include/mbedtls/des.h index 175289850..5a1a63652 100644 --- a/include/mbedtls/des.h +++ b/include/mbedtls/des.h @@ -2,6 +2,10 @@ * \file des.h * * \brief DES block cipher + * + * \warning DES is considered a weak cipher and its use constitutes a + * security risk. We recommend considering stronger ciphers + * instead. */ /* * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved @@ -20,6 +24,7 @@ * limitations under the License. * * This file is part of mbed TLS (https://tls.mbed.org) + * */ #ifndef MBEDTLS_DES_H #define MBEDTLS_DES_H @@ -51,6 +56,10 @@ extern "C" { /** * \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 { @@ -71,6 +80,10 @@ mbedtls_des3_context; * \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 mbedtls_des_init( mbedtls_des_context *ctx ); @@ -78,6 +91,10 @@ void mbedtls_des_init( mbedtls_des_context *ctx ); * \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 mbedtls_des_free( mbedtls_des_context *ctx ); @@ -102,6 +119,10 @@ void mbedtls_des3_free( mbedtls_des3_context *ctx ); * 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 mbedtls_des_key_set_parity( unsigned char key[MBEDTLS_DES_KEY_SIZE] ); @@ -114,6 +135,10 @@ void mbedtls_des_key_set_parity( unsigned char key[MBEDTLS_DES_KEY_SIZE] ); * \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 mbedtls_des_key_check_key_parity( const unsigned char key[MBEDTLS_DES_KEY_SIZE] ); @@ -123,6 +148,10 @@ int mbedtls_des_key_check_key_parity( const unsigned char key[MBEDTLS_DES_KEY_SI * \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 mbedtls_des_key_check_weak( const unsigned char key[MBEDTLS_DES_KEY_SIZE] ); @@ -133,6 +162,10 @@ int mbedtls_des_key_check_weak( const unsigned char key[MBEDTLS_DES_KEY_SIZE] ); * \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 mbedtls_des_setkey_enc( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] ); @@ -143,6 +176,10 @@ int mbedtls_des_setkey_enc( mbedtls_des_context *ctx, const unsigned char key[MB * \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 mbedtls_des_setkey_dec( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] ); @@ -198,6 +235,10 @@ int mbedtls_des3_set3key_dec( mbedtls_des3_context *ctx, * \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 mbedtls_des_crypt_ecb( mbedtls_des_context *ctx, const unsigned char input[8], @@ -221,6 +262,10 @@ int mbedtls_des_crypt_ecb( mbedtls_des_context *ctx, * \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 mbedtls_des_crypt_cbc( mbedtls_des_context *ctx, int mode, @@ -279,6 +324,10 @@ 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 + * security risk. We recommend considering stronger ciphers + * instead. */ void mbedtls_des_setkey( uint32_t SK[32], const unsigned char key[MBEDTLS_DES_KEY_SIZE] ); diff --git a/include/mbedtls/md.h b/include/mbedtls/md.h index 57c27a6f0..bdea393bc 100644 --- a/include/mbedtls/md.h +++ b/include/mbedtls/md.h @@ -44,6 +44,14 @@ extern "C" { #endif +/** + * \brief Enumeration of supported message digests + * + * \warning MD2, MD4, MD5 and SHA-1 are considered weak message digests and + * their use constitutes a security risk. We recommend considering + * stronger message digests instead. + * + */ typedef enum { MBEDTLS_MD_NONE=0, MBEDTLS_MD_MD2, diff --git a/include/mbedtls/md2.h b/include/mbedtls/md2.h index b245b5b7b..2ff3f171a 100644 --- a/include/mbedtls/md2.h +++ b/include/mbedtls/md2.h @@ -2,6 +2,10 @@ * \file md2.h * * \brief MD2 message digest algorithm (hash function) + * + * \warning MD2 is considered a weak message digest and its use constitutes a + * security risk. We recommend considering stronger message digests + * instead. */ /* * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved @@ -20,6 +24,7 @@ * limitations under the License. * * This file is part of mbed TLS (https://tls.mbed.org) + * */ #ifndef MBEDTLS_MD2_H #define MBEDTLS_MD2_H @@ -49,6 +54,11 @@ extern "C" { /** * \brief MD2 context structure + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ typedef struct { @@ -63,6 +73,11 @@ mbedtls_md2_context; * \brief Initialize MD2 context * * \param ctx MD2 context to be initialized + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ void mbedtls_md2_init( mbedtls_md2_context *ctx ); @@ -70,6 +85,11 @@ void mbedtls_md2_init( mbedtls_md2_context *ctx ); * \brief Clear MD2 context * * \param ctx MD2 context to be cleared + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ void mbedtls_md2_free( mbedtls_md2_context *ctx ); @@ -78,6 +98,11 @@ void mbedtls_md2_free( mbedtls_md2_context *ctx ); * * \param dst The destination context * \param src The context to be cloned + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ void mbedtls_md2_clone( mbedtls_md2_context *dst, const mbedtls_md2_context *src ); @@ -88,6 +113,11 @@ void mbedtls_md2_clone( mbedtls_md2_context *dst, * \param ctx context to be initialized * * \return 0 if successful + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md2_starts_ret( mbedtls_md2_context *ctx ); @@ -99,6 +129,11 @@ int mbedtls_md2_starts_ret( mbedtls_md2_context *ctx ); * \param ilen length of the input data * * \return 0 if successful + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md2_update_ret( mbedtls_md2_context *ctx, const unsigned char *input, @@ -111,6 +146,11 @@ int mbedtls_md2_update_ret( mbedtls_md2_context *ctx, * \param output MD2 checksum result * * \return 0 if successful + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md2_finish_ret( mbedtls_md2_context *ctx, unsigned char output[16] ); @@ -121,6 +161,11 @@ int mbedtls_md2_finish_ret( mbedtls_md2_context *ctx, * \param ctx MD2 context * * \return 0 if successful + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_internal_md2_process( mbedtls_md2_context *ctx ); @@ -136,6 +181,11 @@ int mbedtls_internal_md2_process( mbedtls_md2_context *ctx ); * \deprecated Superseded by mbedtls_md2_starts_ret() in 2.7.0 * * \param ctx context to be initialized + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md2_starts( mbedtls_md2_context *ctx ) @@ -151,6 +201,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_md2_starts( * \param ctx MD2 context * \param input buffer holding the data * \param ilen length of the input data + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md2_update( mbedtls_md2_context *ctx, @@ -167,6 +222,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_md2_update( * * \param ctx MD2 context * \param output MD2 checksum result + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md2_finish( mbedtls_md2_context *ctx, @@ -181,6 +241,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_md2_finish( * \deprecated Superseded by mbedtls_internal_md2_process() in 2.7.0 * * \param ctx MD2 context + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md2_process( mbedtls_md2_context *ctx ) @@ -209,6 +274,11 @@ extern "C" { * \param input buffer holding the data * \param ilen length of the input data * \param output MD2 checksum result + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md2_ret( const unsigned char *input, size_t ilen, @@ -228,6 +298,11 @@ int mbedtls_md2_ret( const unsigned char *input, * \param input buffer holding the data * \param ilen length of the input data * \param output MD2 checksum result + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md2( const unsigned char *input, size_t ilen, @@ -243,6 +318,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_md2( const unsigned char *input, * \brief Checkup routine * * \return 0 if successful, or 1 if the test failed + * + * \warning MD2 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md2_self_test( int verbose ); diff --git a/include/mbedtls/md4.h b/include/mbedtls/md4.h index 886a66939..a2ab57f07 100644 --- a/include/mbedtls/md4.h +++ b/include/mbedtls/md4.h @@ -2,6 +2,10 @@ * \file md4.h * * \brief MD4 message digest algorithm (hash function) + * + * \warning MD4 is considered a weak message digest and its use constitutes a + * security risk. We recommend considering stronger message digests + * instead. */ /* * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved @@ -20,6 +24,7 @@ * limitations under the License. * * This file is part of mbed TLS (https://tls.mbed.org) + * */ #ifndef MBEDTLS_MD4_H #define MBEDTLS_MD4_H @@ -50,6 +55,11 @@ extern "C" { /** * \brief MD4 context structure + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ typedef struct { @@ -63,6 +73,11 @@ mbedtls_md4_context; * \brief Initialize MD4 context * * \param ctx MD4 context to be initialized + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ void mbedtls_md4_init( mbedtls_md4_context *ctx ); @@ -70,6 +85,11 @@ void mbedtls_md4_init( mbedtls_md4_context *ctx ); * \brief Clear MD4 context * * \param ctx MD4 context to be cleared + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ void mbedtls_md4_free( mbedtls_md4_context *ctx ); @@ -78,6 +98,11 @@ void mbedtls_md4_free( mbedtls_md4_context *ctx ); * * \param dst The destination context * \param src The context to be cloned + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ void mbedtls_md4_clone( mbedtls_md4_context *dst, const mbedtls_md4_context *src ); @@ -88,6 +113,10 @@ void mbedtls_md4_clone( mbedtls_md4_context *dst, * \param ctx context to be initialized * * \return 0 if successful + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. */ int mbedtls_md4_starts_ret( mbedtls_md4_context *ctx ); @@ -99,6 +128,11 @@ int mbedtls_md4_starts_ret( mbedtls_md4_context *ctx ); * \param ilen length of the input data * * \return 0 if successful + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md4_update_ret( mbedtls_md4_context *ctx, const unsigned char *input, @@ -111,6 +145,11 @@ int mbedtls_md4_update_ret( mbedtls_md4_context *ctx, * \param output MD4 checksum result * * \return 0 if successful + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md4_finish_ret( mbedtls_md4_context *ctx, unsigned char output[16] ); @@ -122,6 +161,11 @@ int mbedtls_md4_finish_ret( mbedtls_md4_context *ctx, * \param data buffer holding one block of data * * \return 0 if successful + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_internal_md4_process( mbedtls_md4_context *ctx, const unsigned char data[64] ); @@ -138,6 +182,11 @@ int mbedtls_internal_md4_process( mbedtls_md4_context *ctx, * \deprecated Superseded by mbedtls_md4_starts_ret() in 2.7.0 * * \param ctx context to be initialized + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md4_starts( mbedtls_md4_context *ctx ) @@ -153,6 +202,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_md4_starts( * \param ctx MD4 context * \param input buffer holding the data * \param ilen length of the input data + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md4_update( mbedtls_md4_context *ctx, @@ -169,6 +223,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_md4_update( * * \param ctx MD4 context * \param output MD4 checksum result + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md4_finish( mbedtls_md4_context *ctx, @@ -184,6 +243,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_md4_finish( * * \param ctx MD4 context * \param data buffer holding one block of data + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md4_process( mbedtls_md4_context *ctx, @@ -215,6 +279,11 @@ extern "C" { * \param output MD4 checksum result * * \return 0 if successful + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md4_ret( const unsigned char *input, size_t ilen, @@ -234,6 +303,11 @@ int mbedtls_md4_ret( const unsigned char *input, * \param input buffer holding the data * \param ilen length of the input data * \param output MD4 checksum result + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md4( const unsigned char *input, size_t ilen, @@ -249,6 +323,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_md4( const unsigned char *input, * \brief Checkup routine * * \return 0 if successful, or 1 if the test failed + * + * \warning MD4 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md4_self_test( int verbose ); diff --git a/include/mbedtls/md5.h b/include/mbedtls/md5.h index 5734b4099..d49391f81 100644 --- a/include/mbedtls/md5.h +++ b/include/mbedtls/md5.h @@ -2,6 +2,10 @@ * \file md5.h * * \brief MD5 message digest algorithm (hash function) + * + * \warning MD5 is considered a weak message digest and its use constitutes a + * security risk. We recommend considering stronger message + * digests instead. */ /* * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved @@ -50,6 +54,11 @@ extern "C" { /** * \brief MD5 context structure + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ typedef struct { @@ -63,6 +72,11 @@ mbedtls_md5_context; * \brief Initialize MD5 context * * \param ctx MD5 context to be initialized + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ void mbedtls_md5_init( mbedtls_md5_context *ctx ); @@ -70,6 +84,11 @@ void mbedtls_md5_init( mbedtls_md5_context *ctx ); * \brief Clear MD5 context * * \param ctx MD5 context to be cleared + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ void mbedtls_md5_free( mbedtls_md5_context *ctx ); @@ -78,6 +97,11 @@ void mbedtls_md5_free( mbedtls_md5_context *ctx ); * * \param dst The destination context * \param src The context to be cloned + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ void mbedtls_md5_clone( mbedtls_md5_context *dst, const mbedtls_md5_context *src ); @@ -88,6 +112,11 @@ void mbedtls_md5_clone( mbedtls_md5_context *dst, * \param ctx context to be initialized * * \return 0 if successful + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md5_starts_ret( mbedtls_md5_context *ctx ); @@ -99,6 +128,11 @@ int mbedtls_md5_starts_ret( mbedtls_md5_context *ctx ); * \param ilen length of the input data * * \return 0 if successful + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md5_update_ret( mbedtls_md5_context *ctx, const unsigned char *input, @@ -111,6 +145,11 @@ int mbedtls_md5_update_ret( mbedtls_md5_context *ctx, * \param output MD5 checksum result * * \return 0 if successful + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md5_finish_ret( mbedtls_md5_context *ctx, unsigned char output[16] ); @@ -122,6 +161,11 @@ int mbedtls_md5_finish_ret( mbedtls_md5_context *ctx, * \param data buffer holding one block of data * * \return 0 if successful + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_internal_md5_process( mbedtls_md5_context *ctx, const unsigned char data[64] ); @@ -138,6 +182,11 @@ int mbedtls_internal_md5_process( mbedtls_md5_context *ctx, * \deprecated Superseded by mbedtls_md5_starts_ret() in 2.7.0 * * \param ctx context to be initialized + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md5_starts( mbedtls_md5_context *ctx ) @@ -153,6 +202,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_md5_starts( * \param ctx MD5 context * \param input buffer holding the data * \param ilen length of the input data + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md5_update( mbedtls_md5_context *ctx, @@ -169,6 +223,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_md5_update( * * \param ctx MD5 context * \param output MD5 checksum result + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md5_finish( mbedtls_md5_context *ctx, @@ -184,6 +243,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_md5_finish( * * \param ctx MD5 context * \param data buffer holding one block of data + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md5_process( mbedtls_md5_context *ctx, @@ -215,6 +279,11 @@ extern "C" { * \param output MD5 checksum result * * \return 0 if successful + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md5_ret( const unsigned char *input, size_t ilen, @@ -234,6 +303,11 @@ int mbedtls_md5_ret( const unsigned char *input, * \param input buffer holding the data * \param ilen length of the input data * \param output MD5 checksum result + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_md5( const unsigned char *input, size_t ilen, @@ -249,6 +323,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_md5( const unsigned char *input, * \brief Checkup routine * * \return 0 if successful, or 1 if the test failed + * + * \warning MD5 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_md5_self_test( int verbose ); diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h index 4d3a16401..613407a2f 100644 --- a/include/mbedtls/sha1.h +++ b/include/mbedtls/sha1.h @@ -2,6 +2,10 @@ * \file sha1.h * * \brief SHA-1 cryptographic hash function + * + * \warning SHA-1 is considered a weak message digest and its use constitutes + * a security risk. We recommend considering stronger message + * digests instead. */ /* * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved @@ -50,6 +54,11 @@ extern "C" { /** * \brief SHA-1 context structure + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ typedef struct { @@ -63,6 +72,11 @@ mbedtls_sha1_context; * \brief Initialize SHA-1 context * * \param ctx SHA-1 context to be initialized + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ void mbedtls_sha1_init( mbedtls_sha1_context *ctx ); @@ -70,6 +84,11 @@ void mbedtls_sha1_init( mbedtls_sha1_context *ctx ); * \brief Clear SHA-1 context * * \param ctx SHA-1 context to be cleared + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ void mbedtls_sha1_free( mbedtls_sha1_context *ctx ); @@ -78,6 +97,11 @@ void mbedtls_sha1_free( mbedtls_sha1_context *ctx ); * * \param dst The destination context * \param src The context to be cloned + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ void mbedtls_sha1_clone( mbedtls_sha1_context *dst, const mbedtls_sha1_context *src ); @@ -88,6 +112,11 @@ void mbedtls_sha1_clone( mbedtls_sha1_context *dst, * \param ctx context to be initialized * * \return 0 if successful + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx ); @@ -99,6 +128,11 @@ int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx ); * \param ilen length of the input data * * \return 0 if successful + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx, const unsigned char *input, @@ -111,6 +145,11 @@ int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx, * \param output SHA-1 checksum result * * \return 0 if successful + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx, unsigned char output[20] ); @@ -122,6 +161,11 @@ int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx, * \param data buffer holding one block of data * * \return 0 if successful + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx, const unsigned char data[64] ); @@ -138,6 +182,11 @@ int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx, * \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0 * * \param ctx context to be initialized + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_starts( mbedtls_sha1_context *ctx ) @@ -153,6 +202,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_starts( * \param ctx SHA-1 context * \param input buffer holding the data * \param ilen length of the input data + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_update( mbedtls_sha1_context *ctx, @@ -169,6 +223,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_update( * * \param ctx SHA-1 context * \param output SHA-1 checksum result + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_finish( mbedtls_sha1_context *ctx, @@ -184,6 +243,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_finish( * * \param ctx SHA-1 context * \param data buffer holding one block of data + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_process( mbedtls_sha1_context *ctx, @@ -215,6 +279,11 @@ extern "C" { * \param output SHA-1 checksum result * * \return 0 if successful + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_sha1_ret( const unsigned char *input, size_t ilen, @@ -234,6 +303,11 @@ int mbedtls_sha1_ret( const unsigned char *input, * \param input buffer holding the data * \param ilen length of the input data * \param output SHA-1 checksum result + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1( const unsigned char *input, size_t ilen, @@ -249,6 +323,11 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1( const unsigned char *input, * \brief Checkup routine * * \return 0 if successful, or 1 if the test failed + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * */ int mbedtls_sha1_self_test( int verbose );