lib/libssl/man/SSL_CTX_set_tmp_rsa_callback.3

   1 .\"     $OpenBSD: SSL_CTX_set_tmp_rsa_callback.3,v 1.3 2016/12/06 22:55:35 schwarze Exp $
   2 .\"     OpenSSL 0b30fc90 Dec 19 15:23:05 2013 -0500
   3 .\"
   4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
   5 .\" Copyright (c) 2001, 2006, 2013 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: December 6 2016 $
  52 .Dt SSL_CTX_SET_TMP_RSA_CALLBACK.POD 3
  53 .Os
  54 .Sh NAME
  55 .Nm SSL_CTX_set_tmp_rsa_callback ,
  56 .Nm SSL_CTX_set_tmp_rsa ,
  57 .Nm SSL_CTX_need_tmp_RSA ,
  58 .Nm SSL_set_tmp_rsa_callback ,
  59 .Nm SSL_set_tmp_rsa ,
  60 .Nm SSL_need_tmp_rsa
  61 .Nd handle RSA keys for ephemeral key exchange
  62 .Sh SYNOPSIS
  63 .In openssl/ssl.h
  64 .Ft void
  65 .Fo SSL_CTX_set_tmp_rsa_callback
  66 .Fa "SSL_CTX *ctx"
  67 .Fa "RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)"
  68 .Fc
  69 .Ft long
  70 .Fn SSL_CTX_set_tmp_rsa "SSL_CTX *ctx" "RSA *rsa"
  71 .Ft long
  72 .Fn SSL_CTX_need_tmp_RSA "SSL_CTX *ctx"
  73 .Ft void
  74 .Fo SSL_set_tmp_rsa_callback
  75 .Fa "SSL_CTX *ctx"
  76 .Fa "RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)"
  77 .Fc
  78 .Ft long
  79 .Fn SSL_set_tmp_rsa "SSL *ssl" "RSA *rsa"
  80 .Ft long
  81 .Fn SSL_need_tmp_rsa "SSL *ssl"
  82 .Ft RSA *
  83 .Fn "(*tmp_rsa_callback)" "SSL *ssl" "int is_export" "int keylength"
  84 .Sh DESCRIPTION
  85 .Fn SSL_CTX_set_tmp_rsa_callback
  86 sets the callback function for
  87 .Fa ctx
  88 to be used when a temporary/ephemeral RSA key is required to
  89 .Fa tmp_rsa_callback .
  90 The callback is inherited by all
  91 .Vt SSL
  92 objects newly created from
  93 .Fa ctx
  94 with
  95 .Xr SSL_new 3 .
  96 Already created SSL objects are not affected.
  97 .Pp
  98 .Fn SSL_CTX_set_tmp_rsa
  99 sets the temporary/ephemeral RSA key to be used to be
 100 .Fa rsa .
 101 The key is inherited by all
 102 .Vt SSL
 103 objects newly created from
 104 .Fa ctx
 105 with
 106 .Xr SSL_new 3 .
 107 Already created SSL objects are not affected.
 108 .Pp
 109 .Fn SSL_CTX_need_tmp_RSA
 110 returns 1,
 111 if a temporary/ephemeral RSA key is needed for RSA-based strength-limited
 112 .Sq exportable
 113 ciphersuites because a RSA key with a keysize larger than 512 bits is installed.
 114 .Pp
 115 .Fn SSL_set_tmp_rsa_callback
 116 sets the callback only for
 117 .Fa ssl .
 118 .Pp
 119 .Fn SSL_set_tmp_rsa
 120 sets the key only for
 121 .Fa ssl .
 122 .Pp
 123 .Fn SSL_need_tmp_rsa
 124 returns 1,
 125 if a temporary/ephemeral RSA key is needed for RSA-based strength-limited
 126 .Sq exportable
 127 ciphersuites because a RSA key with a keysize larger than 512 bits is installed.
 128 .Pp
 129 These functions apply to SSL/TLS servers only.
 130 .Sh NOTES
 131 When using a cipher with RSA authentication,
 132 an ephemeral RSA key exchange can take place.
 133 In this case the session data are negotiated using the ephemeral/temporary RSA
 134 key and the RSA key supplied and certified by the certificate chain is only
 135 used for signing.
 136 .Pp
 137 Under previous export restrictions, ciphers with RSA keys shorter (512 bits)
 138 than the usual key length of 1024 bits were created.
 139 To use these ciphers with RSA keys of usual length, an ephemeral key exchange
 140 must be performed, as the normal (certified) key cannot be directly used.
 141 .Pp
 142 Using ephemeral RSA key exchange yields forward secrecy,
 143 as the connection can only be decrypted when the RSA key is known.
 144 By generating a temporary RSA key inside the server application that is lost
 145 when the application is left, it becomes impossible for an attacker to decrypt
 146 past sessions, even if he gets hold of the normal (certified) RSA key,
 147 as this key was used for signing only.
 148 The downside is that creating a RSA key is computationally expensive.
 149 .Pp
 150 Additionally, the use of ephemeral RSA key exchange is only allowed in the TLS
 151 standard when the RSA key can be used for signing only, that is,
 152 for export ciphers.
 153 Using ephemeral RSA key exchange for other purposes violates the standard and
 154 can break interoperability with clients.
 155 It is therefore strongly recommended to not use ephemeral RSA key exchange and
 156 use DHE (Ephemeral Diffie-Hellman) key exchange instead in order to achieve
 157 forward secrecy (see
 158 .Xr SSL_CTX_set_tmp_dh_callback 3 ) .
 159 .Pp
 160 On OpenSSL servers ephemeral RSA key exchange is therefore disabled by default
 161 and must be explicitly enabled using the
 162 .Dv SSL_OP_EPHEMERAL_RSA
 163 option of
 164 .Xr SSL_CTX_set_options 3 ,
 165 violating the TLS/SSL
 166 standard.
 167 When ephemeral RSA key exchange is required for export ciphers,
 168 it will automatically be used without this option!
 169 .Pp
 170 An application may either directly specify the key or can supply the key via
 171 a callback function.
 172 The callback approach has the advantage that the callback may generate the key
 173 only in case it is actually needed.
 174 However, as the generation of a RSA key is costly,
 175 it will lead to a significant delay in the handshake procedure.
 176 Another advantage of the callback function is that it can supply keys of
 177 different size (e.g., for
 178 .Dv SSL_OP_EPHEMERAL_RSA
 179 usage) while the explicit setting of the key is only useful for key size of
 180 512 bits to satisfy the export restricted ciphers and does give away key length
 181 if a longer key would be allowed.
 182 .Pp
 183 The
 184 .Fa tmp_rsa_callback
 185 is called with the
 186 .Fa keylength
 187 needed and the
 188 .Fa is_export
 189 information.
 190 The
 191 .Fa is_export
 192 flag is set when the ephemeral RSA key exchange is performed with an export
 193 cipher.
 194 .Sh RETURN VALUES
 195 .Fn SSL_CTX_set_tmp_rsa_callback
 196 and
 197 .Fn SSL_set_tmp_rsa_callback
 198 do not return diagnostic output.
 199 .Pp
 200 .Fn SSL_CTX_set_tmp_rsa
 201 and
 202 .Fn SSL_set_tmp_rsa
 203 return 1 on success and 0 on failure.
 204 Check the error queue to find out the reason of failure.
 205 .Pp
 206 .Fn SSL_CTX_need_tmp_RSA
 207 and
 208 .Fn SSL_need_tmp_rsa
 209 return 1 if a temporary RSA key is needed and 0 otherwise.
 210 .Sh EXAMPLES
 211 Generate temporary RSA keys to prepare ephemeral RSA key exchange.
 212 As the generation of a RSA key costs a lot of computer time,
 213 they are saved for later reuse.
 214 For demonstration purposes, two keys for 512 bits and 1024 bits
 215 respectively are generated.
 216 .Bd -literal
 217 \&...
 218
 219 /* Set up ephemeral RSA stuff */
 220 RSA *rsa_512 = NULL;
 221 RSA *rsa_1024 = NULL;
 222
 223 rsa_512 = RSA_generate_key(512, RSA_F4, NULL, NULL);
 224 if (rsa_512 == NULL)
 225         evaluate_error_queue();
 226
 227 rsa_1024 = RSA_generate_key(1024, RSA_F4, NULL, NULL);
 228 if (rsa_1024 == NULL)
 229         evaluate_error_queue();
 230
 231 \&...
 232
 233 RSA *
 234 tmp_rsa_callback(SSL *s, int is_export, int keylength)
 235 {
 236         RSA *rsa_tmp = NULL;
 237
 238         switch (keylength) {
 239         case 512:
 240                 if (rsa_512)
 241                         rsa_tmp = rsa_512;
 242                 else {
 243                         /*
 244                          * generate on the fly,
 245                          * should not happen in this example
 246                          */
 247                         rsa_tmp = RSA_generate_key(keylength, RSA_F4, NULL,
 248                             NULL);
 249                         rsa_512 = rsa_tmp; /* Remember for later reuse */
 250                 }
 251                 break;
 252         case 1024:
 253                 if (rsa_1024)
 254                         rsa_tmp = rsa_1024;
 255                 else
 256                         should_not_happen_in_this_example();
 257                 break;
 258         default:
 259                 /*
 260                  * Generating a key on the fly is very costly,
 261                  * so use what is there
 262                  */
 263                 if (rsa_1024)
 264                         rsa_tmp = rsa_1024;
 265                 else
 266                         /* Use at least a shorter key */
 267                         rsa_tmp = rsa_512;
 268         }
 269         return rsa_tmp;
 270 }
 271 .Ed
 272 .Sh SEE ALSO
 273 .Xr openssl 1 ,
 274 .Xr ssl 3 ,
 275 .Xr SSL_CTX_set_cipher_list 3 ,
 276 .Xr SSL_CTX_set_options 3 ,
 277 .Xr SSL_CTX_set_tmp_dh_callback 3 ,
 278 .Xr SSL_new 3