doc/man3/SSL_CTX_set_session_ticket_cb.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CTX_set_session_ticket_cb,
   6 SSL_SESSION_get0_ticket_appdata,
   7 SSL_SESSION_set1_ticket_appdata,
   8 SSL_CTX_generate_session_ticket_fn,
   9 SSL_CTX_decrypt_session_ticket_fn - manage session ticket application data
  10
  11 =head1 SYNOPSIS
  12
  13  #include <openssl/ssl.h>
  14
  15  typedef int (*SSL_CTX_generate_session_ticket_fn)(SSL *s, void *arg);
  16  typedef SSL_TICKET_RETURN (*SSL_CTX_decrypt_session_ticket_fn)(SSL *s, SSL_SESSION *ss,
  17                                                                 const unsigned char *keyname,
  18                                                                 size_t keyname_len,
  19                                                                 SSL_TICKET_STATUS status,
  20                                                                 void *arg);
  21  int SSL_CTX_set_session_ticket_cb(SSL_CTX *ctx,
  22                                    SSL_CTX_generate_session_ticket_fn gen_cb,
  23                                    SSL_CTX_decrypt_session_ticket_fn dec_cb,
  24                                    void *arg);
  25  int SSL_SESSION_set1_ticket_appdata(SSL_SESSION *ss, const void *data, size_t len);
  26  int SSL_SESSION_get0_ticket_appdata(SSL_SESSION *ss, void **data, size_t *len);
  27
  28 =head1 DESCRIPTION
  29
  30 SSL_CTX_set_set_session_ticket_cb() sets the application callbacks B<gen_cb>
  31 and B<dec_cb> that are used by a server to set and get application data stored
  32 with a session, and placed into a session ticket. Either callback function may
  33 be set to NULL. The value of B<arg> is passed to the callbacks.
  34
  35 B<gen_cb> is the application defined callback invoked when a session ticket is
  36 about to be created. The application can call SSL_SESSION_set1_ticket_appdata()
  37 at this time to add application data to the session ticket. The value of B<arg>
  38 is the same as that given to SSL_CTX_set_session_ticket_cb(). The B<gen_cb>
  39 callback is defined as type B<SSL_CTX_generate_session_ticket_fn>.
  40
  41 B<dec_cb> is the application defined callback invoked after session ticket
  42 decryption has been attempted and any session ticket application data is
  43 available. If ticket decryption was successful then the B<ss> argument contains
  44 the session data. The B<keyname> and B<keyname_len> arguments identify the key
  45 used to decrypt the session ticket. The B<status> argument is the result of the
  46 ticket decryption. See the L<NOTES> section below for further details. The value
  47 of B<arg> is the same as that given to SSL_CTX_set_session_ticket_cb(). The
  48 B<dec_cb> callback is defined as type B<SSL_CTX_decrypt_session_ticket_fn>.
  49
  50 SSL_SESSION_set1_ticket_appdata() sets the application data specified by
  51 B<data> and B<len> into B<ss> which is then placed into any generated session
  52 tickets. It can be called at any time before a session ticket is created to
  53 update the data placed into the session ticket. However, given that sessions
  54 and tickets are created by the handshake, the B<gen_cb> is provided to notify
  55 the application that a session ticket is about to be generated.
  56
  57 SSL_SESSION_get0_ticket_appdata() assigns B<data> to the session ticket
  58 application data and assigns B<len> to the length of the session ticket
  59 application data from B<ss>. The application data can be set via
  60 SSL_SESSION_set1_ticket_appdata() or by a session ticket. NULL will be assigned
  61 to B<data> and 0 will be assigned to B<len> if there is no session ticket
  62 application data. SSL_SESSION_get0_ticket_appdata() can be called any time
  63 after a session has been created. The B<dec_cb> is provided to notify the
  64 application that a session ticket has just been decrypted.
  65
  66 =head1 NOTES
  67
  68 When the B<dec_cb> callback is invoked, the SSL_SESSION B<ss> has not yet been
  69 assigned to the SSL B<s>. The B<status> indicates the result of the ticket
  70 decryption. The callback must check the B<status> value before performing any
  71 action, as it is called even if ticket decryption fails.
  72
  73 The B<keyname> and B<keyname_len> arguments to B<dec_cb> may be used to identify
  74 the key that was used to encrypt the session ticket.
  75
  76 The B<status> argument can be any of these values:
  77
  78 =over 4
  79
  80 =item SSL_TICKET_EMPTY
  81
  82 Empty ticket present. No ticket data will be used and a new ticket should be
  83 sent to the client. This only occurs in TLSv1.2 or below. In TLSv1.3 it is not
  84 valid for a client to send an empty ticket.
  85
  86 =item SSL_TICKET_NO_DECRYPT
  87
  88 The ticket couldn't be decrypted. No ticket data will be used and a new ticket
  89 should be sent to the client.
  90
  91 =item SSL_TICKET_SUCCESS
  92
  93 A ticket was successfully decrypted, any session ticket application data should
  94 be available. A new ticket should not be sent to the client.
  95
  96 =item SSL_TICKET_SUCCESS_RENEW
  97
  98 Same as B<SSL_TICKET_SUCCESS>, but a new ticket should be sent to the client.
  99
 100 =back
 101
 102 The return value can be any of these values:
 103
 104 =over 4
 105
 106 =item SSL_TICKET_RETURN_ABORT
 107
 108 The handshake should be aborted, either because of an error or because of some
 109 policy. Note that in TLSv1.3 a client may send more than one ticket in a single
 110 handshake. Therefore just because one ticket is unacceptable it does not mean
 111 that all of them are. For this reason this option should be used with caution.
 112
 113 =item SSL_TICKET_RETURN_IGNORE
 114
 115 Do not use a ticket (if one was available). Do not send a renewed ticket to the
 116 client.
 117
 118 =item SSL_TICKET_RETURN_IGNORE_RENEW
 119
 120 Do not use a ticket (if one was available). Send a renewed ticket to the client.
 121
 122 If the callback does not wish to change the default ticket behaviour then it
 123 should return this value if B<status> is B<SSL_TICKET_EMPTY> or
 124 B<SSL_TICKET_NO_DECRYPT>.
 125
 126 =item SSL_TICKET_RETURN_USE
 127
 128 Use the ticket. Do not send a renewed ticket to the client. It is an error for
 129 the callback to return this value if B<status> has a value other than
 130 B<SSL_TICKET_SUCCESS> or B<SSL_TICKET_SUCCESS_RENEW>.
 131
 132 If the callback does not wish to change the default ticket behaviour then it
 133 should return this value if B<status> is B<SSL_TICKET_SUCCESS>.
 134
 135 =item SSL_TICKET_RETURN_USE_RENEW
 136
 137 Use the ticket. Send a renewed ticket to the client. It is an error for the
 138 callback to return this value if B<status> has a value other than
 139 B<SSL_TICKET_SUCCESS> or B<SSL_TICKET_SUCCESS_RENEW>.
 140
 141 If the callback does not wish to change the default ticket behaviour then it
 142 should return this value if B<status> is B<SSL_TICKET_SUCCESS_RENEW>.
 143
 144 =back
 145
 146 If B<status> has the value B<SSL_TICKET_EMPTY> or B<SSL_TICKET_NO_DECRYPT> then
 147 no session data will be available and the callback must not use the B<ss>
 148 argument. If B<status> has the value B<SSL_TICKET_SUCCESS> or
 149 B<SSL_TICKET_SUCCESS_RENEW> then the application can call
 150 SSL_SESSION_get0_ticket_appdata() using the session provided in the B<ss>
 151 argument to retrieve the application data.
 152
 153 When the B<gen_cb> callback is invoked, the SSL_get_session() function can be
 154 used to retrieve the SSL_SESSION for SSL_SESSION_set1_ticket_appdata().
 155
 156 By default, in TLSv1.2 and below, a new session ticket is not issued on a
 157 successful resumption and therefore B<gen_cb> will not be called. In TLSv1.3 the
 158 default behaviour is to always issue a new ticket on resumption. In both cases
 159 this behaviour can be changed if a ticket key callback is in use (see
 160 L<SSL_CTX_set_tlsext_ticket_key_cb(3)>).
 161
 162 =head1 RETURN VALUES
 163
 164 The SSL_CTX_set_session_ticket_cb(), SSL_SESSION_set1_ticket_appdata() and
 165 SSL_SESSION_get0_ticket_appdata() functions return 1 on success and 0 on
 166 failure.
 167
 168 The B<gen_cb> callback must return 1 to continue the connection. A return of 0
 169 will terminate the connection with an INTERNAL_ERROR alert.
 170
 171 The B<dec_cb> callback must return a value as described in L<NOTES> above.
 172
 173 =head1 SEE ALSO
 174
 175 L<ssl(7)>,
 176 L<SSL_get_session(3)>
 177
 178 =head1 HISTORY
 179
 180 The SSL_CTX_set_session_ticket_cb(), SSSL_SESSION_set1_ticket_appdata()
 181 and SSL_SESSION_get_ticket_appdata() functions were added in OpenSSL 1.1.1.
 182
 183 =head1 COPYRIGHT
 184
 185 Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
 186
 187 Licensed under the Apache License 2.0 (the "License").  You may not use
 188 this file except in compliance with the License.  You can obtain a copy
 189 in the file LICENSE in the source distribution or at
 190 L<https://www.openssl.org/source/license.html>.
 191
 192 =cut