doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CTX_set_tlsext_ticket_key_evp_cb,
   6 SSL_CTX_set_tlsext_ticket_key_cb
   7 - set a callback for session ticket processing
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/tls1.h>
  12
  13  int SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL_CTX sslctx,
  14      int (*cb)(SSL *s, unsigned char key_name[16],
  15                unsigned char iv[EVP_MAX_IV_LENGTH],
  16                EVP_CIPHER_CTX *ctx, EVP_MAC_CTX *hctx, int enc));
  17
  18 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
  19 B<OPENSSL_API_COMPAT> with a suitable version value, see
  20 L<openssl_user_macros(7)>:
  21
  22  int SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx,
  23      int (*cb)(SSL *s, unsigned char key_name[16],
  24                unsigned char iv[EVP_MAX_IV_LENGTH],
  25                EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc));
  26
  27 =head1 DESCRIPTION
  28
  29 SSL_CTX_set_tlsext_ticket_key_evp_cb() sets a callback function I<cb> for handling
  30 session tickets for the ssl context I<sslctx>. Session tickets, defined in
  31 RFC5077 provide an enhanced session resumption capability where the server
  32 implementation is not required to maintain per session state. It only applies
  33 to TLS and there is no SSLv3 implementation.
  34
  35 The callback function I<cb> will be called for every client instigated TLS
  36 session when session ticket extension is presented in the TLS hello
  37 message. It is the responsibility of this function to create or retrieve the
  38 cryptographic parameters and to maintain their state.
  39
  40 The OpenSSL library uses your callback function to help implement a common TLS
  41 ticket construction state according to RFC5077 Section 4 such that per session
  42 state is unnecessary and a small set of cryptographic variables needs to be
  43 maintained by the callback function implementation.
  44
  45 In order to reuse a session, a TLS client must send the a session ticket
  46 extension to the server. The client can only send exactly one session ticket.
  47 The server, through the callback function, either agrees to reuse the session
  48 ticket information or it starts a full TLS handshake to create a new session
  49 ticket.
  50
  51 Before the callback function is started I<ctx> and I<hctx> have been
  52 initialised with L<EVP_CIPHER_CTX_reset(3)> and L<EVP_MAC_CTX_new(3)>
  53 respectively.
  54
  55 For new sessions tickets, when the client doesn't present a session ticket, or
  56 an attempted retrieval of the ticket failed, or a renew option was indicated,
  57 the callback function will be called with I<enc> equal to 1. The OpenSSL
  58 library expects that the function will set an arbitrary I<name>, initialize
  59 I<iv>, and set the cipher context I<ctx> and the hash context I<hctx>.
  60
  61 The I<name> is 16 characters long and is used as a key identifier.
  62
  63 The I<iv> length is the length of the IV of the corresponding cipher. The
  64 maximum IV length is B<EVP_MAX_IV_LENGTH> bytes defined in B<evp.h>.
  65
  66 The initialization vector I<iv> should be a random value. The cipher context
  67 I<ctx> should use the initialisation vector I<iv>. The cipher context can be
  68 set using L<EVP_EncryptInit_ex(3)>. The hmac context and digest can be set using
  69 L<EVP_MAC_CTX_set_params(3)> with the B<OSSL_MAC_PARAM_KEY> and
  70 B<OSSL_MAC_PARAM_DIGEST> parameters respectively.
  71
  72 When the client presents a session ticket, the callback function with be called
  73 with I<enc> set to 0 indicating that the I<cb> function should retrieve a set
  74 of parameters. In this case I<name> and I<iv> have already been parsed out of
  75 the session ticket. The OpenSSL library expects that the I<name> will be used
  76 to retrieve a cryptographic parameters and that the cryptographic context
  77 I<ctx> will be set with the retrieved parameters and the initialization vector
  78 I<iv>. using a function like L<EVP_DecryptInit_ex(3)>. The key material and
  79 digest for I<hctx> need to be set using L<EVP_MAC_CTX_set_params(3)> with the
  80 B<OSSL_MAC_PARAM_KEY> and B<OSSL_MAC_PARAM_DIGEST> parameters respectively.
  81
  82 If the I<name> is still valid but a renewal of the ticket is required the
  83 callback function should return 2. The library will call the callback again
  84 with an argument of enc equal to 1 to set the new ticket.
  85
  86 The return value of the I<cb> function is used by OpenSSL to determine what
  87 further processing will occur. The following return values have meaning:
  88
  89 =over 4
  90
  91 =item Z<>2
  92
  93 This indicates that the I<ctx> and I<hctx> have been set and the session can
  94 continue on those parameters. Additionally it indicates that the session
  95 ticket is in a renewal period and should be replaced. The OpenSSL library will
  96 call I<cb> again with an enc argument of 1 to set the new ticket (see RFC5077
  97 3.3 paragraph 2).
  98
  99 =item Z<>1
 100
 101 This indicates that the I<ctx> and I<hctx> have been set and the session can
 102 continue on those parameters.
 103
 104 =item Z<>0
 105
 106 This indicates that it was not possible to set/retrieve a session ticket and
 107 the SSL/TLS session will continue by negotiating a set of cryptographic
 108 parameters or using the alternate SSL/TLS resumption mechanism, session ids.
 109
 110 If called with enc equal to 0 the library will call the I<cb> again to get
 111 a new set of parameters.
 112
 113 =item less than 0
 114
 115 This indicates an error.
 116
 117 =back
 118
 119 The SSL_CTX_set_tlsext_ticket_key_cb() function is identical to
 120 SSL_CTX_set_tlsext_ticket_key_evp_cb() except that it takes a deprecated
 121 HMAC_CTX pointer instead of an EVP_MAC_CTX one.
 122 Before this callback function is started I<hctx> will have been
 123 initialised with L<EVP_MAC_CTX_new(3)> and the digest set with
 124 L<EVP_MAC_CTX_set_params(3)>.
 125 The I<hctx> key material can be set using L<HMAC_Init_ex(3)>.
 126
 127 =head1 NOTES
 128
 129 Session resumption shortcuts the TLS so that the client certificate
 130 negotiation don't occur. It makes up for this by storing client certificate
 131 an all other negotiated state information encrypted within the ticket. In a
 132 resumed session the applications will have all this state information available
 133 exactly as if a full negotiation had occurred.
 134
 135 If an attacker can obtain the key used to encrypt a session ticket, they can
 136 obtain the master secret for any ticket using that key and decrypt any traffic
 137 using that session: even if the cipher suite supports forward secrecy. As
 138 a result applications may wish to use multiple keys and avoid using long term
 139 keys stored in files.
 140
 141 Applications can use longer keys to maintain a consistent level of security.
 142 For example if a cipher suite uses 256 bit ciphers but only a 128 bit ticket key
 143 the overall security is only 128 bits because breaking the ticket key will
 144 enable an attacker to obtain the session keys.
 145
 146 =head1 RETURN VALUES
 147
 148 returns 0 to indicate the callback function was set.
 149
 150 =head1 EXAMPLES
 151
 152 Reference Implementation:
 153
 154  SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL, ssl_tlsext_ticket_key_cb);
 155  ...
 156
 157  static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16],
 158                                      unsigned char *iv, EVP_CIPHER_CTX *ctx,
 159                                      EVP_MAC_CTX *hctx, int enc)
 160  {
 161      OSSL_PARAM params[3];
 162      your_type_t *key; /* something that you need to implement */
 163
 164      if (enc) { /* create new session */
 165          if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) <= 0)
 166              return -1; /* insufficient random */
 167
 168          key = currentkey(); /* something that you need to implement */
 169          if (key == NULL) {
 170              /* current key doesn't exist or isn't valid */
 171              key = createkey(); /*
 172                                  * Something that you need to implement.
 173                                  * createkey needs to initialise a name,
 174                                  * an aes_key, a hmac_key and optionally
 175                                  * an expire time.
 176                                  */
 177              if (key == NULL) /* key couldn't be created */
 178                  return 0;
 179          }
 180          memcpy(key_name, key->name, 16);
 181
 182          EVP_EncryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key->aes_key, iv);
 183
 184          params[0] = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY,
 185                                                        key->hmac_key, 32);
 186          params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
 187                                                       "sha256", 0);
 188          params[2] = OSSL_PARAM_construct_end();
 189          EVP_MAC_CTX_set_params(hctx, params);
 190
 191          return 1;
 192
 193      } else { /* retrieve session */
 194          time_t t = time(NULL);
 195          key = findkey(key_name); /* something that you need to implement */
 196
 197          if (key == NULL || key->expire < t)
 198              return 0;
 199
 200          params[0] = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
 201                                                        key->hmac_key, 32);
 202          params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
 203                                                       "sha256", 0);
 204          params[2] = OSSL_PARAM_construct_end();
 205          EVP_MAC_CTX_set_params(hctx, params);
 206
 207          EVP_DecryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key->aes_key, iv);
 208
 209          if (key->expire < t - RENEW_TIME) { /* RENEW_TIME: implement */
 210              /*
 211               * return 2 - This session will get a new ticket even though the
 212               * current one is still valid.
 213               */
 214              return 2;
 215          }
 216          return 1;
 217      }
 218  }
 219
 220 =head1 SEE ALSO
 221
 222 L<ssl(7)>, L<SSL_set_session(3)>,
 223 L<SSL_session_reused(3)>,
 224 L<SSL_CTX_add_session(3)>,
 225 L<SSL_CTX_sess_number(3)>,
 226 L<SSL_CTX_sess_set_get_cb(3)>,
 227 L<SSL_CTX_set_session_id_context(3)>,
 228
 229 =head1 HISTORY
 230
 231 The SSL_CTX_set_tlsext_ticket_key_cb() function was deprecated in OpenSSL 3.0.
 232
 233 The SSL_CTX_set_tlsext_ticket_key_evp_cb() function was introduced in
 234 OpenSSL 3.0.
 235
 236 =head1 COPYRIGHT
 237
 238 Copyright 2014-2020 The OpenSSL Project Authors. All Rights Reserved.
 239
 240 Licensed under the Apache License 2.0 (the "License").  You may not use
 241 this file except in compliance with the License.  You can obtain a copy
 242 in the file LICENSE in the source distribution or at
 243 L<https://www.openssl.org/source/license.html>.
 244
 245 =cut