doc: discuss the set_known_dh_params and use it in the examples

7 files changed, 50 insertions, 114 deletions

diff --git a/doc/cha-bib.texi b/doc/cha-bib.texi
index 69bffa4dc3..106c8f7c71 100644
--- a/doc/cha-bib.texi
+++ b/doc/cha-bib.texi
@@ -66,6 +66,11 @@ P. Hallam-Baker, "X.509v3 Transport Layer Security (TLS) Feature Extension",
 October 2015, Available from
 @url{http://www.ietf.org/rfc/rfc7633.txt}.
 
+@item @anchor{RFC7919}[RFC7919]
+D. Gillmor, "Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for Transport Layer Security (TLS)",
+August 2016, Available from
+@url{http://www.ietf.org/rfc/rfc7919.txt}.
+
 @item @anchor{RFC4514}[RFC4514]
 Kurt D.  Zeilenga, "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names",
 June 2006, Available from
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 4abeef856a..63843124c8 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -1688,36 +1688,32 @@ the discussion in @ref{Safe renegotiation}).
 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
-the group parameters to be provided. Those can either be
-be generated on the fly using @funcref{gnutls_dh_params_generate2}
-or imported from pregenerated data using @funcref{gnutls_dh_params_import_pkcs3}.
-The parameters can be used in a @acronym{TLS} session by calling
-@funcref{gnutls_certificate_set_dh_params} or
-@funcref{gnutls_anon_set_server_dh_params} for anonymous sessions.
-
-@showfuncD{gnutls_dh_params_generate2,gnutls_dh_params_import_pkcs3,gnutls_certificate_set_dh_params,gnutls_anon_set_server_dh_params}
-
-Due to the time-consuming calculations required for the generation
-of Diffie-Hellman parameters we suggest against performing generation
-of them within an application. The @code{certtool} tool can be used to 
-generate or export known safe values that can be stored in code
-or in a configuration file to provide the ability to replace. We also
-recommend the usage of @funcref{gnutls_sec_param_to_pk_bits} 
-(see @ref{Selecting cryptographic key sizes}) to determine
-the bit size of the generated parameters.
-
-Note that the information stored in the generated PKCS #3 structure
-changed with GnuTLS 3.0.9. Since that version the @code{privateValueLength}
-member of the structure is set, allowing the server utilizing the
-parameters to use keys of the size of the security parameter. This
-provides better performance in key exchange.
-
-To allow renewal of the parameters within an application without
-accessing the credentials, which are a shared structure,
-an alternative interface is available using a callback function.  
-
-@showfuncdesc{gnutls_certificate_set_params_function}
-
+the group parameters to be provided. 
+These parameters can be specified in a @acronym{TLS} credentials
+structure by calling
+@funcref{gnutls_certificate_set_known_dh_params},
+@funcref{gnutls_anon_set_server_known_dh_params}, or
+@funcref{gnutls_psk_set_server_known_dh_params}, depending on the type
+of the credentials.
+
+@showfuncC{gnutls_certificate_set_known_dh_params,gnutls_anon_set_server_known_dh_params,gnutls_psk_set_server_known_dh_params}
+
+The functions above will set DH parameters pre-configured in the library
+based on the security level provided. The GnuTLS' included parameters are
+the FFDHE parameters from @xcite{RFC7919}.
+
+@subsubsection Legacy parameter generation
+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}
+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.
 
 @node Deriving keys for other applications/protocols
 @subsection Deriving keys for other applications/protocols
diff --git a/doc/examples/ex-serv-anon.c b/doc/examples/ex-serv-anon.c
index abb4af51c6..51e3be4df2 100644
--- a/doc/examples/ex-serv-anon.c
+++ b/doc/examples/ex-serv-anon.c
@@ -23,24 +23,6 @@
 #define MAX_BUF 1024
 #define PORT 5556               /* listen to 5556 port */
 
-/* These are global */
-static gnutls_dh_params_t dh_params;
-
-static int generate_dh_params(void)
-{
-        unsigned int bits = gnutls_sec_param_to_pk_bits(GNUTLS_PK_DH,
-                                                        GNUTLS_SEC_PARAM_LEGACY);
-        /* Generate Diffie-Hellman parameters - for use with DHE
-         * kx algorithms. These should be discarded and regenerated
-         * once a day, once a week or once a month. Depending on the
-         * security requirements.
-         */
-        gnutls_dh_params_init(&dh_params);
-        gnutls_dh_params_generate2(dh_params, bits);
-
-        return 0;
-}
-
 int main(void)
 {
         int err, listen_sd;
@@ -64,9 +46,7 @@ int main(void)
 
         gnutls_anon_allocate_server_credentials(&anoncred);
 
-        generate_dh_params();
-
-        gnutls_anon_set_server_dh_params(anoncred, dh_params);
+        gnutls_anon_set_server_known_dh_params(anoncred, GNUTLS_SEC_PARAM_MEDIUM);
 
         /* Socket operations
          */
diff --git a/doc/examples/ex-serv-dtls.c b/doc/examples/ex-serv-dtls.c
index ad51fd96ae..887b4b83df 100644
--- a/doc/examples/ex-serv-dtls.c
+++ b/doc/examples/ex-serv-dtls.c
@@ -45,13 +45,11 @@ static ssize_t pull_func(gnutls_transport_ptr_t p, void *data,
 static const char *human_addr(const struct sockaddr *sa, socklen_t salen,
                               char *buf, size_t buflen);
 static int wait_for_connection(int fd);
-static int generate_dh_params(void);
 
 /* Use global credentials and parameters to simplify
  * the example. */
 static gnutls_certificate_credentials_t x509_cred;
 static gnutls_priority_t priority_cache;
-static gnutls_dh_params_t dh_params;
 
 int main(void)
 {
@@ -88,9 +86,7 @@ int main(void)
                 exit(1);
         }
 
-        generate_dh_params();
-
-        gnutls_certificate_set_dh_params(x509_cred, dh_params);
+        gnutls_certificate_set_known_dh_params(x509_cred, GNUTLS_SEC_PARAM_MEDIUM);
 
         gnutls_priority_init(&priority_cache,
                              "PERFORMANCE:-VERS-TLS-ALL:+VERS-DTLS1.0:%SERVER_PRECEDENCE",
@@ -422,17 +418,3 @@ static const char *human_addr(const struct sockaddr *sa, socklen_t salen,
         return save_buf;
 }
 
-static int generate_dh_params(void)
-{
-        int bits = gnutls_sec_param_to_pk_bits(GNUTLS_PK_DH,
-                                               GNUTLS_SEC_PARAM_LEGACY);
-
-        /* Generate Diffie-Hellman parameters - for use with DHE
-         * kx algorithms. When short bit length is used, it might
-         * be wise to regenerate parameters often.
-         */
-        gnutls_dh_params_init(&dh_params);
-        gnutls_dh_params_generate2(dh_params, bits);
-
-        return 0;
-}
diff --git a/doc/examples/ex-serv-psk.c b/doc/examples/ex-serv-psk.c
index ed61f00d5e..26aad02f47 100644
--- a/doc/examples/ex-serv-psk.c
+++ b/doc/examples/ex-serv-psk.c
@@ -27,26 +27,6 @@
 #define SOCKET_ERR(err,s) if(err==-1) {perror(s);return(1);}
 #define MAX_BUF 1024
 #define PORT 5556               /* listen to 5556 port */
-#define DH_BITS 1024
-
-/* These are global */
-static gnutls_dh_params_t dh_params;
-
-static int generate_dh_params(void)
-{
-
-        /* Generate Diffie-Hellman parameters - for use with DHE
-         * kx algorithms. When short bit length is used, it might
-         * be wise to regenerate parameters.
-         *
-         * Check the ex-serv-export.c example for using static
-         * parameters.
-         */
-        gnutls_dh_params_init(&dh_params);
-        gnutls_dh_params_generate2(dh_params, DH_BITS);
-
-        return 0;
-}
 
 static int
 pskfunc(gnutls_session_t session, const char *username,
@@ -99,13 +79,11 @@ int main(void)
         gnutls_psk_allocate_server_credentials(&psk_cred);
         gnutls_psk_set_server_credentials_function(psk_cred, pskfunc);
 
-        generate_dh_params();
-
         gnutls_priority_init(&priority_cache,
                              "NORMAL:+PSK:+ECDHE-PSK:+DHE-PSK",
                              NULL);
 
-        gnutls_certificate_set_dh_params(x509_cred, dh_params);
+        gnutls_certificate_set_known_dh_params(x509_cred, GNUTLS_SEC_PARAM_MEDIUM);
 
         /* Socket operations
          */
diff --git a/doc/examples/ex-serv-x509.c b/doc/examples/ex-serv-x509.c
index b850ac21e5..e67c9592b5 100644
--- a/doc/examples/ex-serv-x509.c
+++ b/doc/examples/ex-serv-x509.c
@@ -38,24 +38,6 @@
 #define MAX_BUF 1024
 #define PORT 5556               /* listen to 5556 port */
 
-/* These are global */
-static gnutls_dh_params_t dh_params;
-
-static int generate_dh_params(void)
-{
-        unsigned int bits = gnutls_sec_param_to_pk_bits(GNUTLS_PK_DH,
-                                                        GNUTLS_SEC_PARAM_MEDIUM);
-
-        /* Generate Diffie-Hellman parameters - for use with DHE
-         * kx algorithms. When short bit length is used, it might
-         * be wise to regenerate parameters often.
-         */
-        CHECK(gnutls_dh_params_init(&dh_params));
-        CHECK(gnutls_dh_params_generate2(dh_params, bits));
-
-        return 0;
-}
-
 int main(void)
 {
         int listen_sd;
@@ -90,12 +72,12 @@ int main(void)
                                                               OCSP_STATUS_FILE,
                                                               0));
 
-        generate_dh_params();
-
         CHECK(gnutls_priority_init(&priority_cache,
                                    "PERFORMANCE:%SERVER_PRECEDENCE", NULL));
 
-        gnutls_certificate_set_dh_params(x509_cred, dh_params);
+        /* only available since GnuTLS 3.5.6, on previous versions see
+         * gnutls_certificate_set_dh_params(). */
+        gnutls_certificate_set_known_dh_params(x509_cred, GNUTLS_SEC_PARAM_MEDIUM);
 
         /* Socket operations
          */
diff --git a/doc/latex/gnutls.bib b/doc/latex/gnutls.bib
index 16f983dc45..e78bdbdf5b 100644
--- a/doc/latex/gnutls.bib
+++ b/doc/latex/gnutls.bib
@@ -7,6 +7,19 @@
 	url = "http://tools.ietf.org/html/draft-ietf-websec-key-pinning-01"
 }
 
+@misc{rfc7919,
+  author="D. Gillmor",
+  title="{Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for Transport Layer Security (TLS)}",
+  series="Request for Comments",
+  number="7919",
+  howpublished="RFC 7919 (Proposed Standard)",
+  publisher="IETF",
+  organization="Internet Engineering Task Force",
+  year=2016,
+  month=aug,
+    url="http://www.ietf.org/rfc/rfc7919.txt",
+}
+
 @misc{RFC5280,
   author="D. Cooper and S. Santesson and S. Farrell and S. Boeyen and R. Housley and W. Polk",
   title="{Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile}",