lib/libssl/man/SSL_CTX_set_tlsext_ticket_key_cb.3

   1 .\"     $OpenBSD: SSL_CTX_set_tlsext_ticket_key_cb.3,v 1.2 2016/12/16 15:39:08 jmc Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Rich Salz <rsalz@akamai.com>
   5 .\" Copyright (c) 2014, 2015, 2016 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 16 2016 $
  52 .Dt SSL_CTX_SET_TLSEXT_TICKET_KEY_CB 3
  53 .Os
  54 .Sh NAME
  55 .Nm SSL_CTX_set_tlsext_ticket_key_cb
  56 .Nd set a callback for session ticket processing
  57 .Sh SYNOPSIS
  58 .In openssl/tls1.h
  59 .Ft long
  60 .Fo SSL_CTX_set_tlsext_ticket_key_cb
  61 .Fa "SSL_CTX sslctx"
  62 .Fa "int (*cb)(SSL *s, unsigned char key_name[16],\
  63  unsigned char iv[EVP_MAX_IV_LENGTH],\
  64  EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)"
  65 .Fc
  66 .Sh DESCRIPTION
  67 .Fn SSL_CTX_set_tlsext_ticket_key_cb
  68 sets a callback function
  69 .Fa cb
  70 for handling session tickets for the ssl context
  71 .Fa sslctx .
  72 Session tickets, defined in RFC5077, provide an enhanced session
  73 resumption capability where the server implementation is not required to
  74 maintain per session state.
  75 .Pp
  76 The callback function
  77 .Fa cb
  78 will be called for every client instigated TLS session when session
  79 ticket extension is presented in the TLS hello message.
  80 It is the responsibility of this function to create or retrieve the
  81 cryptographic parameters and to maintain their state.
  82 .Pp
  83 The OpenSSL library uses the callback function to help implement a
  84 common TLS ticket construction state according to RFC5077 Section 4 such
  85 that per session state is unnecessary and a small set of cryptographic
  86 variables needs to be maintained by the callback function
  87 implementation.
  88 .Pp
  89 In order to reuse a session, a TLS client must send a session ticket
  90 extension to the server.
  91 The client can only send exactly one session ticket.
  92 The server, through the callback function, either agrees to reuse the
  93 session ticket information or it starts a full TLS handshake to create a
  94 new session ticket.
  95 .Pp
  96 Before the callback function is started,
  97 .Fa ctx
  98 and
  99 .Fa hctx
 100 have been initialised with
 101 .Xr EVP_CIPHER_CTX_init 3
 102 and
 103 .Xr HMAC_CTX_init 3 ,
 104 respectively.
 105 .Pp
 106 For new sessions tickets, when the client doesn't present a session
 107 ticket, or an attempted retrieval of the ticket failed, or a renew
 108 option was indicated, the callback function will be called with
 109 .Fa enc
 110 equal to 1.
 111 The OpenSSL library expects that the function will set an arbitrary
 112 .Fa key_name ,
 113 initialize
 114 .Fa iv ,
 115 and set the cipher context
 116 .Fa ctx
 117 and the hash context
 118 .Fa hctx .
 119 .Pp
 120 The
 121 .Fa key_name
 122 is 16 characters long and is used as a key identifier.
 123 .Pp
 124 The
 125 .Fa iv
 126 length is the length of the IV of the corresponding cipher.
 127 The maximum IV length is
 128 .Dv EVP_MAX_IV_LENGTH
 129 bytes defined in
 130 .In opsenssl/evp.h .
 131 .Pp
 132 The initialization vector
 133 .Fa iv
 134 should be a random value.
 135 The cipher context
 136 .Fa ctx
 137 should use the initialisation vector
 138 .Fa iv .
 139 The cipher context can be set using
 140 .Xr EVP_EncryptInit_ex 3 .
 141 The hmac context can be set using
 142 .Xr HMAC_Init_ex 3 .
 143 .Pp
 144 When the client presents a session ticket, the callback function
 145 with be called with
 146 .Fa enc
 147 set to 0 indicating that the
 148 .Fa cb
 149 function should retrieve a set of parameters.
 150 In this case
 151 .Fa key_name
 152 and
 153 .Fa iv
 154 have already been parsed out of the session ticket.
 155 The OpenSSL library expects that the
 156 .Em key_name
 157 will be used to retrieve a cryptographic parameters and that the
 158 cryptographic context
 159 .Fa ctx
 160 will be set with the retrieved parameters and the initialization vector
 161 .Fa iv
 162 using a function like
 163 .Xr EVP_DecryptInit_ex 3 .
 164 The
 165 .Fa hctx
 166 needs to be set using
 167 .Xr HMAC_Init_ex 3 .
 168 .Pp
 169 If the
 170 .Fa key_name
 171 is still valid but a renewal of the ticket is required, the callback
 172 function should return 2.
 173 The library will call the callback again with an argument of
 174 .Fa enc
 175 equal to 1 to set the new ticket.
 176 .Pp
 177 The return value of the
 178 .Fa cb
 179 function is used by OpenSSL to determine what further processing will
 180 occur.
 181 The following return values have meaning:
 182 .Bl -tag -width Ds
 183 .It 2
 184 This indicates that the
 185 .Fa ctx
 186 and
 187 .Fa hctx
 188 have been set and the session can continue on those parameters.
 189 Additionally it indicates that the session ticket is in a renewal period
 190 and should be replaced.
 191 The OpenSSL library will call
 192 .Fa cb
 193 again with an
 194 .Fa enc
 195 argument of 1 to set the new ticket (see RFC5077 3.3 paragraph 2).
 196 .It 1
 197 This indicates that the
 198 .Fa ctx
 199 and
 200 .Fa hctx
 201 have been set and the session can continue on those parameters.
 202 .It 0
 203 This indicates that it was not possible to set/retrieve a session ticket
 204 and the SSL/TLS session will continue by negotiating a set of
 205 cryptographic parameters or using the alternate SSL/TLS resumption
 206 mechanism, session ids.
 207 .Pp
 208 If called with
 209 .Fa enc
 210 equal to 0, the library will call the
 211 .Fa cb
 212 again to get a new set of parameters.
 213 .It less than 0
 214 This indicates an error.
 215 .El
 216 .Pp
 217 Session resumption shortcuts the TLS so that the client certificate
 218 negotiation don't occur.
 219 It makes up for this by storing client certificate and all other
 220 negotiated state information encrypted within the ticket.
 221 In a resumed session the applications will have all this state
 222 information available exactly as if a full negotiation had occurred.
 223 .Pp
 224 If an attacker can obtain the key used to encrypt a session ticket, they
 225 can obtain the master secret for any ticket using that key and decrypt
 226 any traffic using that session: even if the ciphersuite supports forward
 227 secrecy.
 228 As a result applications may wish to use multiple keys and avoid using
 229 long term keys stored in files.
 230 .Pp
 231 Applications can use longer keys to maintain a consistent level of
 232 security.
 233 For example if a ciphersuite uses 256 bit ciphers but only a 128 bit
 234 ticket key the overall security is only 128 bits because breaking the
 235 ticket key will enable an attacker to obtain the session keys.
 236 .Sh RETURN VALUES
 237 This function returns 0 to indicate that the callback function was set.
 238 .Sh EXAMPLES
 239 Reference Implementation:
 240 .Bd -literal
 241 SSL_CTX_set_tlsext_ticket_key_cb(SSL, ssl_tlsext_ticket_key_cb);
 242 \&....
 243 static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16],
 244     unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)
 245 {
 246         if (enc) { /* create new session */
 247                 if (RAND_bytes(iv, EVP_MAX_IV_LENGTH))
 248                         return -1; /* insufficient random */
 249
 250                 key = currentkey(); /* something you need to implement */
 251                 if (!key) {
 252                         /* current key doesn't exist or isn't valid */
 253                         key = createkey();
 254                             /* something that you need to implement.
 255                              * createkey needs to initialise a name,
 256                              * an aes_key, a hmac_key, and optionally
 257                              * an expire time. */
 258                         if (!key) /* key couldn't be created */
 259                                 return 0;
 260                 }
 261                 memcpy(key_name, key->name, 16);
 262
 263                 EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL,
 264                     key->aes_key, iv);
 265                 HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
 266
 267                 return 1;
 268
 269         } else { /* retrieve session */
 270                 key = findkey(name);
 271
 272                 if  (!key || key->expire < now())
 273                         return 0;
 274
 275                 HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
 276                 EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL,
 277                     key->aes_key, iv );
 278
 279                 if (key->expire < (now() - RENEW_TIME))
 280                     /* this session will get a new ticket
 281                      * even though the current is still valid */
 282                     return 2;
 283
 284                 return 1;
 285         }
 286 }
 287 .Ed
 288 .Sh SEE ALSO
 289 .Xr ssl 3 ,
 290 .Xr SSL_CTX_add_session 3 ,
 291 .Xr SSL_CTX_sess_number 3 ,
 292 .Xr SSL_CTX_sess_set_get_cb 3 ,
 293 .Xr SSL_CTX_set_session_id_context 3 ,
 294 .Xr SSL_session_reused 3 ,
 295 .Xr SSL_set_session 3