[openssl-commits] [openssl] master update

Emilia Kasper emilia at openssl.org
Wed May 20 13:44:47 UTC 2015

The branch master has been updated
       via  1554d55318a7bb3347f4ccfadf78cca56e51ee79 (commit)
       via  1f302db3e70f50f9b5e0860581a18e117eafcf20 (commit)
       via  b5a379aae5e05d18a17e41cd7591a038e21395eb (commit)
      from  5a1d2509060da8ca99fa41135eff7bf3a193f69f (commit)

- Log -----------------------------------------------------------------
commit 1554d55318a7bb3347f4ccfadf78cca56e51ee79
Author: Emilia Kasper <emilia at openssl.org>
Date:   Mon May 18 13:57:01 2015 +0200

    Remove dh512.pem
    Reviewed-by: Rich Salz <rsalz at openssl.org>

commit 1f302db3e70f50f9b5e0860581a18e117eafcf20
Author: Emilia Kasper <emilia at openssl.org>
Date:   Tue May 12 16:10:05 2015 +0200

    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 <keylength> - it is currently called
    with 1024 bits, but this value can and should be safely ignored by
    Reviewed-by: Rich Salz <rsalz at openssl.org>

commit b5a379aae5e05d18a17e41cd7591a038e21395eb
Author: Emilia Kasper <emilia at openssl.org>
Date:   Wed May 13 12:05:41 2015 +0200

    dhparam: fix documentation
    The default bitlength is now 2048. Also clarify that either the number
    of bits or the generator must be present:
    $ openssl dhparam -2
    $ openssl dhparam 2048
    generate parameters but
    $ openssl dhparam
    does not.
    Reviewed-by: Matt Caswell <matt at openssl.org>


Summary of changes:
 apps/dh512.pem                          |   9 ---
 doc/apps/dhparam.pod                    |  13 ++--
 doc/ssl/SSL_CTX_set_tmp_dh_callback.pod | 104 +++++++++++++-------------------
 3 files changed, 49 insertions(+), 77 deletions(-)
 delete mode 100644 apps/dh512.pem

diff --git a/apps/dh512.pem b/apps/dh512.pem
deleted file mode 100644
index 200d16c..0000000
--- a/apps/dh512.pem
+++ /dev/null
@@ -1,9 +0,0 @@
-These are the 512 bit DH parameters from "Assigned Number for SKIP Protocols"
-See there for how they were generated.
-Note that g is not a generator, but this is not a problem since p is a safe prime.
diff --git a/doc/apps/dhparam.pod b/doc/apps/dhparam.pod
index 6e27cf5..1cd4c76 100644
--- a/doc/apps/dhparam.pod
+++ b/doc/apps/dhparam.pod
@@ -71,8 +71,10 @@ check if the parameters are valid primes and generator.
 =item B<-2>, B<-5>
-The generator to use, either 2 or 5. 2 is the default. If present then the
-input file is ignored and parameters are generated instead.
+The generator to use, either 2 or 5. If present then the
+input file is ignored and parameters are generated instead. If not
+present but B<numbits> is present, parameters are generated with the
+default generator 2.
 =item B<-rand> I<file(s)>
@@ -85,9 +87,10 @@ all others.
 =item I<numbits>
 this option specifies that a parameter set should be generated of size
-I<numbits>. It must be the last option. If not present then a value of 512
-is used. If this option is present then the input file is ignored and 
-parameters are generated instead.
+I<numbits>. It must be the last option. If this option is present then
+the input file is ignored and parameters are generated instead. If
+this option is not present but a generator (B<-2> or B<-5>) is
+present, parameters are generated with a default length of 2048 bits.
 =item B<-noout>
diff --git a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
index a9995fc..64c8b65 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,61 @@ 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<dhparam(1)|dhparam(1)> application. In order to reduce the computer
-time needed for this generation, it is possible to use DSA parameters
-instead (see L<dhparam(1)|dhparam(1)>), but in this case SSL_OP_SINGLE_DH_USE
-is mandatory.
+openssl L<dhparam(1)|dhparam(1)> 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<dhparam(1)|dhparam(1)> application.
-Authors may also generate their own set of parameters using
-L<dhparam(1)|dhparam(1)>, but a user may not be sure how the parameters were
-generated. The generation of DH parameters during installation is therefore
+L<dhparam(1)|dhparam(1)> application. Generation of custom DH
+parameters during installation should still be preferred to stop an
+attacker from specializing on a commonly used group. File dh1024.pem
+contains 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<tmp_dh_callback> is called with the B<keylength> needed and
-the B<is_export> information. The B<is_export> flag is set, when the
-ephemeral DH key exchange is performed with an export cipher.
+Previous versions of the callback used B<is_export> and B<keylength>
+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<keylength> and B<is_export> 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);
+ } 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);
+ ...

More information about the openssl-commits mailing list