1 files changed, 95 insertions, 108 deletions

diff --git a/src/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3 b/src/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3
index ad734839a9..94ec9e9b90 100644
--- a/src/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3
+++ b/src/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3
@@ -1,7 +1,54 @@
+.\"     $OpenBSD: SSL_CTX_set_tmp_dh_callback.3,v 1.2 2016/12/01 21:53:42 schwarze Exp $
+.\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
-.\"     $OpenBSD: SSL_CTX_set_tmp_dh_callback.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $
+.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
+.\" Copyright (c) 2001, 2014, 2015 The OpenSSL Project.  All rights reserved.
 .\"
-.Dd $Mdocdate: November 5 2016 $
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: December 1 2016 $
 .Dt SSL_CTX_SET_TMP_DH_CALLBACK 3
 .Os
 .Sh NAME
@@ -54,7 +101,7 @@ sets the parameters only for
 .Fa ssl .
 .Pp
 These functions apply to SSL/TLS servers only.
-.Sh NOTES
+.Pp
 When using a cipher with RSA authentication,
 an ephemeral DH key exchange can take place.
 Ciphers with DSA keys always use ephemeral DH keys as well.
@@ -72,35 +119,7 @@ as this key was only used for signing.
 .Pp
 In order to perform a DH key exchange the server must use a DH group
 (DH parameters) and generate a DH key.
-The server will always generate a new DH key during the negotiation,
-when the DH parameters are supplied via callback and/or when the
-.Dv SSL_OP_SINGLE_DH_USE
-option of
-.Xr SSL_CTX_set_options 3
-is set.
-It will immediately create a DH key, when DH parameters are supplied via
-.Fn SSL_CTX_set_tmp_dh
-and
-.Dv SSL_OP_SINGLE_DH_USE
-is not set.
-In this case, it may happen that a key is generated on initialization without
-later being needed, while on the other hand the computer time during the
-negotiation is being saved.
-.Pp
-If
-.Dq 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
-.Dq strong
-primes were used (see especially the section about DSA parameters below),
-.Dv SSL_OP_SINGLE_DH_USE
-must be used in order to prevent small subgroup attacks.
-Always using
-.Dv 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 server will always generate a new DH key during the negotiation.
 .Pp
 As generating DH parameters is extremely time consuming, an application should
 not generate the parameters on the fly but supply the parameters.
@@ -109,21 +128,14 @@ 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
+installation process using the
 .Xr openssl 1
+.Cm dhparam
 application.
-In order to reduce the computer time needed for this generation,
-it is possible to use DSA parameters instead (see
-.Xr openssl 1 ) ,
-but in this case
-.Dv SSL_OP_SINGLE_DH_USE
-is mandatory.
+This application guarantees that "strong" primes are used.
 .Pp
-Application authors may compile in DH parameters.
 Files
-.Pa dh512.pem ,
-.Pa dh1024.pem ,
-.Pa dh2048.pem ,
+.Pa dh2048.pem
 and
 .Pa dh4096.pem
 in the
@@ -136,28 +148,32 @@ These files can be converted into C code using the
 .Fl C
 option of the
 .Xr openssl 1
+.Cm dhparam
 application.
-Authors may also generate their own set of parameters using
-.Xr openssl 1 ,
-but a user may not be sure how the parameters were generated.
-The generation of DH parameters during installation is therefore recommended.
+Generation of custom DH parameters during installation should still
+be preferred to stop an attacker from specializing on a commonly
+used group.
+The file
+.Pa dh1024.pem
+contains old parameters that must not be used by applications.
 .Pp
 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.
 .Pp
-The
-.Fa tmp_dh_callback
-is called with the
-.Fa keylength
-needed and the
+Previous versions of the callback used
 .Fa is_export
-information.
-The
+and
+.Fa 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
+.Fn SSL_CTX_set_tmp_dh
+or alternatively, use the callback but ignore
+.Fa keylength
+and
 .Fa is_export
-flag is set when the ephemeral DH key exchange is performed with an export
-cipher.
+and simply supply at least 2048-bit parameters in the callback.
 .Sh RETURN VALUES
 .Fn SSL_CTX_set_tmp_dh_callback
 and
@@ -170,66 +186,37 @@ and
 do return 1 on success and 0 on failure.
 Check the error queue to find out the reason of failure.
 .Sh EXAMPLES
-Handle DH parameters for key lengths of 512 and 1024 bits.
-(Error handling partly left out.)
+Set up DH parameters with a key length of 2048 bits.
+Error handling is partly left out.
+.Pp
+Command-line parameter generation:
+.Pp
+.Dl openssl dhparam -out dh_param_2048.pem 2048
+.Pp
+Code for setting up parameters during server initialization:
 .Bd -literal
-\&...
-/* Set up ephemeral DH stuff */
-DH *dh_512 = NULL;
-DH *dh_1024 = NULL;
-FILE *paramfile;
-
+SSL_CTX ctx = SSL_CTX_new();
 \&...
 
-/* "openssl dhparam -out dh_param_512.pem -2 512" */
-paramfile = fopen("dh_param_512.pem", "r");
+/* 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. */
 }
 .Ed
 .Sh SEE ALSO
 .Xr openssl 1 ,
 .Xr ssl 3 ,
 .Xr SSL_CTX_set_cipher_list 3 ,
-.Xr SSL_CTX_set_options 3 ,
-.Xr SSL_CTX_set_tmp_rsa_callback 3
+.Xr SSL_CTX_set_options 3