From 137758a4f77d603861bf0b68e2af2d77070d247e Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Thu, 1 Dec 2016 21:53:42 +0000 Subject: Add Copyright and license. Merge various updates from OpenSSL, in particular stop talking about what happens without SSL_OP_SINGLE_DH_USE, which is now always on. --- src/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3 | 203 +++++++++++------------ 1 file changed, 95 insertions(+), 108 deletions(-) (limited to 'src/lib') 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 . +.\" 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 -- cgit v1.2.3-55-g6feb