diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 47c7196402..b490e33d77 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -618,6 +618,13 @@
  *      MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256
  *      MBEDTLS_TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA
  *      MBEDTLS_TLS_DHE_PSK_WITH_RC4_128_SHA
+ *
+ * \warning    The possibility for the use of custom groups
+ *             in the use of DHM in TLS constitutes a security
+ *             risk. If possible, it is recommended to use
+ *             EC-based key exchanges instead. See the documentation
+ *             at the top of dhm.h for more information.
+ *
  */
 #define MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED
 
@@ -717,6 +724,13 @@
  *      MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256
  *      MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA
  *      MBEDTLS_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
+ *
+ * \warning    The possibility for the use of custom groups
+ *             in the use of DHM in TLS constitutes a security
+ *             risk. If possible, it is recommended to use
+ *             EC-based key exchanges instead. See the documentation
+ *             at the top of dhm.h for more information.
+ *
  */
 #define MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED
 
@@ -1835,6 +1849,13 @@
  *
  * This module is used by the following key exchanges:
  *      DHE-RSA, DHE-PSK
+ *
+ * \warning    The possibility for the use of custom groups
+ *             in the use of DHM in TLS constitutes a security
+ *             risk. If possible, it is recommended to use
+ *             EC-based key exchanges instead. See the documentation
+ *             at the top of dhm.h for more information.
+ *
  */
 #define MBEDTLS_DHM_C
 
diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h
index 43c49402f6..542592d855 100644
--- a/include/mbedtls/dhm.h
+++ b/include/mbedtls/dhm.h
@@ -19,6 +19,29 @@
  *  limitations under the License.
  *
  *  This file is part of mbed TLS (https://tls.mbed.org)
+ *
+ * \warning  The security of the DHM key exchange relies on the proper choice
+ *           of prime modulus - optimally, it should be a safe prime. The usage
+ *           of non-safe primes both decreases the difficulty of the underlying
+ *           discrete logarithm problem and can lead to small subgroup attacks
+ *           leaking private exponent bits when invalid public keys are used
+ *           and not detected. This is especially relevant if the same DHM parameters
+ *           are reused for multiple key exchanges as in static DHM, while the
+ *           criticality of small-subgroup attacks is lower for ephemeral DHM.
+ *
+ *           For performance reasons, the code does neither perform primality
+ *           nor safe primality tests, nor the expensive checks for invalid
+ *           subgroups.
+ *
+ *           The possibility for the use of custom, non-safe primes in DHM
+ *           is a deficiency in the TLS protocol that has been adressed only
+ *           recently through the addition of the named group extension from
+ *           RFC 7919, which however is not yet implemented in Mbed TLS.
+ *
+ *           If possible, we recommend to use elliptic curve based key
+ *           exchanges instead of DHM-based ones, because the former only
+ *           accepts standardized groups.
+ *
  */
 #ifndef MBEDTLS_DHM_H
 #define MBEDTLS_DHM_H