diff --git a/include/polarssl/config.h b/include/polarssl/config.h
index 60d96ec..d805624 100644
--- a/include/polarssl/config.h
+++ b/include/polarssl/config.h
@@ -256,6 +256,12 @@
  *
  * Uncomment a macro to enable alternate implementation for core algorithm
  * functions
+ *
+ * \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 POLARSSL_AES_ALT
 //#define POLARSSL_ARC4_ALT
@@ -370,6 +376,9 @@
  *      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 POLARSSL_ENABLE_WEAK_CIPHERSUITES
 
@@ -1349,6 +1358,11 @@
  *      TLS_RSA_WITH_RC4_128_MD5
  *      TLS_RSA_PSK_WITH_RC4_128_SHA
  *      TLS_PSK_WITH_RC4_128_SHA
+ *
+ * \warning  ARC4 is considered a weak cipher and its use constitutes a
+ *           security risk. If possible, we recommend avoiding dependencies on
+ *           it, and considering stronger ciphers instead.
+ *
  */
 #define POLARSSL_ARC4_C
 
@@ -1563,6 +1577,9 @@
  *      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 POLARSSL_DES_C
 
@@ -1722,6 +1739,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 POLARSSL_MD2_C
 
@@ -1734,6 +1756,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 POLARSSL_MD4_C
 
@@ -1747,8 +1774,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 it can be used in
+ * TLS 1.2 through the choice on 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 POLARSSL_MD5_C
 
@@ -2025,6 +2059,11 @@
  *          library/x509write_crt.c
  *
  * This module is required for SSL/TLS and 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 POLARSSL_SHA1_C