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
servers.

Reviewed-by: Rich Salz <rsalz@openssl.org>

doc/ssl/SSL_CTX_set_tmp_dh_callback.pod

@@ -61,12 +61,12 @@ 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
+secrecy. If it is not assured that "strong" primes were used,
-the section about DSA parameters below), SSL_OP_SINGLE_DH_USE must be used
+SSL_OP_SINGLE_DH_USE must be used in order to prevent small subgroup
-in order to prevent small subgroup attacks. Always using SSL_OP_SINGLE_DH_USE
+attacks. Always using SSL_OP_SINGLE_DH_USE has an impact on the
-has an impact on the computer time needed during negotiation, but it is not
+computer time needed during negotiation, but it is not very large, so
-very large, so application authors/users should consider to always enable
+application authors/users should consider always enabling this option.
-this option.
+The option is required to implement perfect forward secrecy (PFS).
 
 As generating DH parameters is extremely time consuming, an application
 should not generate the parameters on the fly but supply the parameters.
@@ -74,83 +74,63 @@ 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
+openssl L<dhparam(1)|dhparam(1)> application. This application
-time needed for this generation, it is possible to use DSA parameters
+guarantees that "strong" primes are used.
-instead (see L<dhparam(1)|dhparam(1)>), but in this case SSL_OP_SINGLE_DH_USE
-is mandatory.
 
-Application authors may compile in DH parameters. Files dh512.pem,
+Files dh2048.pem, and dh4096.pem in the 'apps' directory of the current
-dh1024.pem, dh2048.pem, and dh4096.pem in the 'apps' directory of 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.
+L<dhparam(1)|dhparam(1)> application. Generation of custom DH
-Authors may also generate their own set of parameters using
+parameters during installation should still be preferred to stop an
-L<dhparam(1)|dhparam(1)>, but a user may not be sure how the parameters were
+attacker from specializing on a commonly used group. Files dh1024.pem
-generated. The generation of DH parameters during installation is therefore
+and dh512.pem contain old parameters that must not be used by
-recommended.
+applications.
 
 An application may either directly specify the DH parameters or
-can supply the DH parameters via a callback function. The callback approach
+can supply the DH parameters via a callback function.
-has the advantage, that the callback may supply DH parameters for different
-key lengths.
 
-The B<tmp_dh_callback> is called with the B<keylength> needed and
+Previous versions of the callback used B<is_export> and B<keylength>
-the B<is_export> information. The B<is_export> flag is set, when the
+parameters to control parameter generation for export and non-export
-ephemeral DH key exchange is performed with an export cipher.
+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.)
 
+ Command-line parameter generation:
+ $ openssl dhparam -out dh_param_2048.pem 2048
+
+ Code for setting up parameters during server initialization:
+
  ...
- /* Set up ephemeral DH stuff */
+ SSL_CTX ctx = SSL_CTX_new();
- DH *dh_512 = NULL;
+ ...
- DH *dh_1024 = NULL;
+
+ /* Set up ephemeral DH parameters. */
+ DH *dh_2048 = NULL;
  FILE *paramfile;
-
+ paramfile = fopen("dh_param_2048.pem", "r");
- ...
- /* "openssl dhparam -out dh_param_512.pem -2 512" */
- paramfile = fopen("dh_param_512.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" */
+ if (dh_2048 == NULL) {
- paramfile = fopen("dh_param_1024.pem", "r");
+  /* Error. */
- if (paramfile) {
-   dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
-   fclose(paramfile);
  }
+ if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) {
+   /* Error. */
+ }
+ SSL_CTX_set_options(ctx, SSL_OP_SINGLE_DH_USE);
  ...
 
- /* "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);
- }
-
 =head1 RETURN VALUES
 
 SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return