diff options
-rw-r--r-- | doc/cha-gtls-app.texi | 26 | ||||
-rw-r--r-- | lib/dh.c | 18 |
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 @@ -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. **/ |