summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorNikos Mavrogiannopoulos <nmav@gnutls.org>2016-10-11 19:36:26 +0200
committerNikos Mavrogiannopoulos <nmav@gnutls.org>2016-10-14 22:55:38 +0200
commit74cf948ba803b10ff3223e5294ac0270f972bce1 (patch)
treef719af30c25c6f16be0fbe8c91d3a6f205a46e89 /doc
parent4c04aa36cbb5255173e0516b32cb3d07d03b502c (diff)
downloadgnutls-74cf948ba803b10ff3223e5294ac0270f972bce1.tar.gz
doc: discuss the set_known_dh_params and use it in the examples
Diffstat (limited to 'doc')
-rw-r--r--doc/cha-bib.texi5
-rw-r--r--doc/cha-gtls-app.texi56
-rw-r--r--doc/examples/ex-serv-anon.c22
-rw-r--r--doc/examples/ex-serv-dtls.c20
-rw-r--r--doc/examples/ex-serv-psk.c24
-rw-r--r--doc/examples/ex-serv-x509.c24
-rw-r--r--doc/latex/gnutls.bib13
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}",