From 74cf948ba803b10ff3223e5294ac0270f972bce1 Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Tue, 11 Oct 2016 19:36:26 +0200 Subject: doc: discuss the set_known_dh_params and use it in the examples --- doc/cha-bib.texi | 5 ++++ doc/cha-gtls-app.texi | 56 +++++++++++++++++++++------------------------ doc/examples/ex-serv-anon.c | 22 +----------------- doc/examples/ex-serv-dtls.c | 20 +--------------- doc/examples/ex-serv-psk.c | 24 +------------------ doc/examples/ex-serv-x509.c | 24 +++---------------- doc/latex/gnutls.bib | 13 +++++++++++ 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}", -- cgit v1.2.1