From 1f302db3e70f50f9b5e0860581a18e117eafcf20 Mon Sep 17 00:00:00 2001 From: Emilia Kasper Date: Tue, 12 May 2015 16:10:05 +0200 Subject: Update documentation with Diffie-Hellman best practices. - Do not advise generation of DH parameters with dsaparam to save computation time. - Promote use of custom parameters more, and explicitly forbid use of built-in parameters weaker than 2048 bits. - Advise the callback to ignore - it is currently called with 1024 bits, but this value can and should be safely ignored by servers. Reviewed-by: Rich Salz --- doc/ssl/SSL_CTX_set_tmp_dh_callback.pod | 105 +++++++++++++------------------- 1 file changed, 42 insertions(+), 63 deletions(-) diff --git a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod index a9995fcb64..b754c16a86 100644 --- a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod +++ b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod @@ -61,12 +61,11 @@ negotiation is being saved. If "strong" primes were used to generate the DH parameters, it is not strictly necessary to generate a new key for each handshake but it does improve forward -secrecy. If it is not assured, that "strong" primes were used (see especially -the section about DSA parameters below), SSL_OP_SINGLE_DH_USE must be used -in order to prevent small subgroup attacks. Always using SSL_OP_SINGLE_DH_USE -has an impact on the computer time needed during negotiation, but it is not -very large, so application authors/users should consider to always enable -this option. +secrecy. If it is not assured that "strong" primes were used, +SSL_OP_SINGLE_DH_USE must be used in order to prevent small subgroup +attacks. Always using SSL_OP_SINGLE_DH_USE has an impact on the +computer time needed during negotiation, but it is not very large, so +application authors/users should consider always enabling this option. The option is required to implement perfect forward secrecy (PFS). As generating DH parameters is extremely time consuming, an application @@ -75,82 +74,62 @@ DH parameters can be reused, as the actual key is newly generated during the negotiation. The risk in reusing DH parameters is that an attacker may specialize on a very often used DH group. Applications should therefore generate their own DH parameters during the installation process using the -openssl L application. In order to reduce the computer -time needed for this generation, it is possible to use DSA parameters -instead (see L), but in this case SSL_OP_SINGLE_DH_USE -is mandatory. +openssl L application. This application +guarantees that "strong" primes are used. -Application authors may compile in DH parameters. Files dh512.pem, -dh1024.pem, dh2048.pem, and dh4096.pem in the 'apps' directory of current +Files dh2048.pem, and dh4096.pem in the 'apps' directory of the current version of the OpenSSL distribution contain the 'SKIP' DH parameters, which use safe primes and were generated verifiably pseudo-randomly. These files can be converted into C code using the B<-C> option of the -L application. -Authors may also generate their own set of parameters using -L, but a user may not be sure how the parameters were -generated. The generation of DH parameters during installation is therefore -recommended. +L application. Generation of custom DH +parameters during installation should still be preferred to stop an +attacker from specializing on a commonly used group. Files dh1024.pem +and dh512.pem contain old parameters that must not be used by +applications. An application may either directly specify the DH parameters or -can supply the DH parameters via a callback function. The callback approach -has the advantage, that the callback may supply DH parameters for different -key lengths. +can supply the DH parameters via a callback function. -The B is called with the B needed and -the B information. The B flag is set, when the -ephemeral DH key exchange is performed with an export cipher. +Previous versions of the callback used B and B +parameters to control parameter generation for export and non-export +cipher suites. Modern servers that do not support export ciphersuites +are advised to either use SSL_CTX_set_tmp_dh() in combination with +SSL_OP_SINGLE_DH_USE, or alternatively, use the callback but ignore +B and B and simply supply at least 2048-bit +parameters in the callback. =head1 EXAMPLES -Handle DH parameters for key lengths of 512 and 1024 bits. (Error handling +Setup DH parameters with a key length of 2048 bits. (Error handling partly left out.) - ... - /* Set up ephemeral DH stuff */ - DH *dh_512 = NULL; - DH *dh_1024 = NULL; - FILE *paramfile; + Command-line parameter generation: + $ openssl dhparam -out dh_param_2048.pem 2048 + + Code for setting up parameters during server initialization: ... - /* "openssl dhparam -out dh_param_512.pem -2 512" */ - paramfile = fopen("dh_param_512.pem", "r"); + SSL_CTX ctx = SSL_CTX_new(); + ... + + /* Set up ephemeral DH parameters. */ + DH *dh_2048 = NULL; + FILE *paramfile; + paramfile = fopen("dh_param_2048.pem", "r"); if (paramfile) { - dh_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); + dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); fclose(paramfile); + } else { + /* Error. */ } - /* "openssl dhparam -out dh_param_1024.pem -2 1024" */ - paramfile = fopen("dh_param_1024.pem", "r"); - if (paramfile) { - dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); - fclose(paramfile); + if (dh_2048 == NULL) { + /* Error. */ } - ... - - /* "openssl dhparam -C -2 512" etc... */ - DH *get_dh512() { ... } - DH *get_dh1024() { ... } - - DH *tmp_dh_callback(SSL *s, int is_export, int keylength) - { - DH *dh_tmp=NULL; - - switch (keylength) { - case 512: - if (!dh_512) - dh_512 = get_dh512(); - dh_tmp = dh_512; - break; - case 1024: - if (!dh_1024) - dh_1024 = get_dh1024(); - dh_tmp = dh_1024; - break; - default: - /* Generating a key on the fly is very costly, so use what is there */ - setup_dh_parameters_like_above(); - } - return(dh_tmp); + if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) { + /* Error. */ } + SSL_CTX_set_options(ctx, SSL_OP_SINGLE_DH_USE); + ... =head1 RETURN VALUES -- cgit v1.2.3