Add warnings regarding the use of DHM in general
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 47c7196..b490e33 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 43c4940..542592d 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