lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3

   1 .\"     $OpenBSD: SSL_CTX_set_tmp_dh_callback.3,v 1.7 2018/03/27 17:35:50 schwarze Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
   5 .\" Copyright (c) 2001, 2014, 2015 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: March 27 2018 $
  52 .Dt SSL_CTX_SET_TMP_DH_CALLBACK 3
  53 .Os
  54 .Sh NAME
  55 .Nm SSL_CTX_set_tmp_dh_callback ,
  56 .Nm SSL_CTX_set_tmp_dh ,
  57 .Nm SSL_set_tmp_dh_callback ,
  58 .Nm SSL_set_tmp_dh
  59 .Nd handle DH keys for ephemeral key exchange
  60 .Sh SYNOPSIS
  61 .In openssl/ssl.h
  62 .Ft void
  63 .Fo SSL_CTX_set_tmp_dh_callback
  64 .Fa "SSL_CTX *ctx"
  65 .Fa "DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)"
  66 .Fc
  67 .Ft long
  68 .Fn SSL_CTX_set_tmp_dh "SSL_CTX *ctx" "DH *dh"
  69 .Ft void
  70 .Fo SSL_set_tmp_dh_callback
  71 .Fa "SSL *ssl"
  72 .Fa "DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength"
  73 .Fc
  74 .Ft long
  75 .Fn SSL_set_tmp_dh "SSL *ssl" "DH *dh"
  76 .Sh DESCRIPTION
  77 .Fn SSL_CTX_set_tmp_dh_callback
  78 sets the callback function for
  79 .Fa ctx
  80 to be used when a DH parameters are required to
  81 .Fa tmp_dh_callback .
  82 The callback is inherited by all
  83 .Vt ssl
  84 objects created from
  85 .Fa ctx .
  86 .Pp
  87 .Fn SSL_CTX_set_tmp_dh
  88 sets DH parameters to be used by
  89 .Fa ctx .
  90 The key is inherited by all
  91 .Fa ssl
  92 objects created from
  93 .Fa ctx .
  94 .Pp
  95 .Fn SSL_set_tmp_dh_callback
  96 sets the callback only for
  97 .Fa ssl .
  98 .Pp
  99 .Fn SSL_set_tmp_dh
 100 sets the parameters only for
 101 .Fa ssl .
 102 .Pp
 103 These functions apply to SSL/TLS servers only.
 104 .Pp
 105 When using a cipher with RSA authentication,
 106 an ephemeral DH key exchange can take place.
 107 Ciphers with DSA keys always use ephemeral DH keys as well.
 108 In these cases, the session data are negotiated using the ephemeral/temporary
 109 DH key and the key supplied and certified by the certificate chain is only used
 110 for signing.
 111 Anonymous ciphers (without a permanent server key) also use ephemeral DH keys.
 112 .Pp
 113 Using ephemeral DH key exchange yields forward secrecy,
 114 as the connection can only be decrypted when the DH key is known.
 115 By generating a temporary DH key inside the server application that is lost
 116 when the application is left, it becomes impossible for an attacker to decrypt
 117 past sessions, even if he gets hold of the normal (certified) key,
 118 as this key was only used for signing.
 119 .Pp
 120 In order to perform a DH key exchange the server must use a DH group
 121 (DH parameters) and generate a DH key.
 122 The server will always generate a new DH key during the negotiation.
 123 .Pp
 124 As generating DH parameters is extremely time consuming, an application should
 125 not generate the parameters on the fly but supply the parameters.
 126 DH parameters can be reused,
 127 as the actual key is newly generated during the negotiation.
 128 The risk in reusing DH parameters is that an attacker may specialize on a very
 129 often used DH group.
 130 Applications should therefore generate their own DH parameters during the
 131 installation process using the
 132 .Xr openssl 1
 133 .Cm dhparam
 134 application.
 135 This application guarantees that "strong" primes are used.
 136 .Pp
 137 Files
 138 .Pa dh2048.pem
 139 and
 140 .Pa dh4096.pem
 141 in the
 142 .Pa apps
 143 directory of the current version of the OpenSSL distribution contain the
 144 .Sq SKIP
 145 DH parameters,
 146 which use safe primes and were generated verifiably pseudo-randomly.
 147 These files can be converted into C code using the
 148 .Fl C
 149 option of the
 150 .Xr openssl 1
 151 .Cm dhparam
 152 application.
 153 Generation of custom DH parameters during installation should still
 154 be preferred to stop an attacker from specializing on a commonly
 155 used group.
 156 The file
 157 .Pa dh1024.pem
 158 contains old parameters that must not be used by applications.
 159 .Pp
 160 An application may either directly specify the DH parameters or can supply the
 161 DH parameters via a callback function.
 162 .Pp
 163 Previous versions of the callback used
 164 .Fa is_export
 165 and
 166 .Fa keylength
 167 parameters to control parameter generation for export and non-export
 168 cipher suites.
 169 Modern servers that do not support export ciphersuites are advised
 170 to either use
 171 .Fn SSL_CTX_set_tmp_dh
 172 or alternatively, use the callback but ignore
 173 .Fa keylength
 174 and
 175 .Fa is_export
 176 and simply supply at least 2048-bit parameters in the callback.
 177 .Sh RETURN VALUES
 178 .Fn SSL_CTX_set_tmp_dh_callback
 179 and
 180 .Fn SSL_set_tmp_dh_callback
 181 do not return diagnostic output.
 182 .Pp
 183 .Fn SSL_CTX_set_tmp_dh
 184 and
 185 .Fn SSL_set_tmp_dh
 186 do return 1 on success and 0 on failure.
 187 Check the error queue to find out the reason of failure.
 188 .Sh EXAMPLES
 189 Set up DH parameters with a key length of 2048 bits.
 190 Error handling is partly left out.
 191 .Pp
 192 Command-line parameter generation:
 193 .Pp
 194 .Dl openssl dhparam -out dh_param_2048.pem 2048
 195 .Pp
 196 Code for setting up parameters during server initialization:
 197 .Bd -literal
 198 SSL_CTX ctx = SSL_CTX_new();
 199 \&...
 200
 201 /* Set up ephemeral DH parameters. */
 202 DH *dh_2048 = NULL;
 203 FILE *paramfile;
 204 paramfile = fopen("dh_param_2048.pem", "r");
 205 if (paramfile) {
 206         dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
 207         fclose(paramfile);
 208 } else {
 209         /* Error. */
 210 }
 211 if (dh_2048 == NULL) {
 212         /* Error. */
 213 }
 214 if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) {
 215         /* Error. */
 216 }
 217 .Ed
 218 .Sh SEE ALSO
 219 .Xr openssl 1 ,
 220 .Xr ssl 3 ,
 221 .Xr SSL_CTX_set_cipher_list 3 ,
 222 .Xr SSL_CTX_set_options 3 ,
 223 .Xr SSL_set_tmp_ecdh 3
 224 .Sh HISTORY
 225 .Fn SSL_CTX_set_tmp_dh_callback
 226 and
 227 .Fn SSL_CTX_set_tmp_dh
 228 first appeared in SSLeay 0.8.0 and have been available since
 229 .Ox 2.4 .
 230 .Pp
 231 .Fn SSL_set_tmp_dh_callback
 232 and
 233 .Fn SSL_set_tmp_dh
 234 first appeared in OpenSSL 0.9.2b and have been available since
 235 .Ox 2.6 .