doc: improved documentation on DH parameters [ci skip]

2 files changed, 30 insertions, 14 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index d8bf9adec5..627373405e 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -1693,11 +1693,11 @@ the discussion in @ref{Safe renegotiation}).
 @cindex parameter generation
 @cindex generating parameters
 
-Several TLS ciphersuites require additional parameters that
-need to be generated or provided by the application. The
-Diffie-Hellman based ciphersuites (ANON-DH or DHE), require
+Few TLS ciphersuites require additional parameters that
+need to be generated or provided by the application. In particular,
+the Diffie-Hellman based ciphersuites (ANON-DH or DHE), require
 the group parameters to be provided. 
-These parameters can be specified in a @acronym{TLS} credentials
+Applications can specify these parameters in a @acronym{TLS} credentials
 structure by calling
 @funcref{gnutls_certificate_set_known_dh_params},
 @funcref{gnutls_anon_set_server_known_dh_params}, or
@@ -1714,15 +1714,23 @@ the FFDHE parameters from @xcite{RFC7919}.
 Note that older than 3.5.6 versions of GnuTLS provided functions
 to generate or import arbitrary DH parameters from a file. This
 practice is still supported but discouraged in current versions.
-
-@showfuncC{gnutls_dh_params_generate2,gnutls_dh_params_import_pkcs3,gnutls_certificate_set_dh_params}
-
-For old applications which require explicit DH parameters, we recommend
-using @code{certtool} (of GnuTLS 3.5.6) with the @code{--get-dh-params}
+There is no known advantage from using random parameters, while there
+have been several occasions where applications were utilizing incorrect,
+or insecure parameters. This is the main reason GnuTLS includes the
+well-known parameters of @xcite{RFC7919} and recommends to applications
+utilizing them.
+
+In older applications which require to specify explicit DH parameters, we recommend
+using @code{certtool} (of GnuTLS 3.5.6 or later) with the @code{--get-dh-params}
 option to obtain the FFDHE parameters descussed above. The output
 parameters of the tool are in PKCS#3 format and can be imported by
 most existing applications.
 
+The following functions are still supported but considered obsolete.
+
+@showfuncC{gnutls_dh_params_generate2,gnutls_dh_params_import_pkcs3,gnutls_certificate_set_dh_params}
+
+
 @node Deriving keys for other applications/protocols
 @subsection Deriving keys for other applications/protocols
 @cindex keying material exporters
diff --git a/lib/dh.c b/lib/dh.c
index 62d5f8dbdb..8248baf26c 100644
--- a/lib/dh.c
+++ b/lib/dh.c
@@ -261,16 +261,24 @@ int gnutls_dh_params_cpy(gnutls_dh_params_t dst, gnutls_dh_params_t src)
  * @bits: is the prime's number of bits
  *
  * This function will generate a new pair of prime and generator for use in
- * the Diffie-Hellman key exchange. The new parameters will be allocated using
- * gnutls_malloc() and will be stored in the appropriate datum.
- * This function is normally slow.
+ * the Diffie-Hellman key exchange. This may take long time.
  *
- * Do not set the number of bits directly, use gnutls_sec_param_to_pk_bits() to
- * get bits for %GNUTLS_PK_DSA.
+ * It is recommended not to set the number of bits directly, but 
+ * use gnutls_sec_param_to_pk_bits() instead.
+
  * Also note that the DH parameters are only useful to servers.
  * Since clients use the parameters sent by the server, it's of
  * no use to call this in client side.
  *
+ * The parameters generated are of the DSA form. It also is possible
+ * to generate provable parameters (following the Shawe-Taylor
+ * algorithm), using gnutls_x509_privkey_generate2() with DSA option
+ * and the %GNUTLS_PRIVKEY_FLAG_PROVABLE flag set. These can the
+ * be imported with gnutls_dh_params_import_dsa().
+ *
+ * It is no longer recommended for applications to generate parameters.
+ * See the "Parameter generation" section in the manual.
+ *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned,
  *   otherwise a negative error code is returned.
  **/