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_RETURN retv,
  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 available.
  43 The application can call SSL_SESSION_get_ticket_appdata() at this time to retrieve
  44 the application data. The value of B<arg> is the same as that given to
  45 SSL_CTX_set_session_ticket_cb(). The B<retv> argument is the result of the ticket
  46 decryption. The B<keyname> and B<keyname_len> identify the key used to decrypt the
  47 session ticket. The B<dec_cb> callback is defined as type
  48 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<retv> indicates the result of the ticket
  70 decryption which can be modified by the callback before being returned. The
  71 callback must check the B<retv> value before performing any action, as it's
  72 called even if ticket decryption fails.
  73
  74 The B<keyname> and B<keyname_len> arguments to B<dec_cb> may be used to identify
  75 the key that was used to encrypt the session ticket.
  76
  77 When the B<gen_cb> callback is invoked, the SSL_get_session() function can be
  78 used to retrieve the SSL_SESSION for SSL_SESSION_set1_ticket_appdata().
  79
  80 By default, in TLSv1.2 and below, a new session ticket is not issued on a
  81 successful resumption and therefore B<gen_cb> will not be called. In TLSv1.3 the
  82 default behaviour is to always issue a new ticket on resumption. In both cases
  83 this behaviour can be changed if a ticket key callback is in use (see
  84 L<SSL_CTX_set_tlsext_ticket_key_cb(3)>).
  85
  86 =head1 RETURN VALUES
  87
  88 The SSL_CTX_set_session_ticket_cb(), SSL_SESSION_set1_ticket_appdata() and
  89 SSL_SESSION_get0_ticket_appdata() functions return 1 on success and 0 on
  90 failure.
  91
  92 The B<gen_cb> callback must return 1 to continue the connection. A return of 0
  93 will terminate the connection with an INTERNAL_ERROR alert.
  94
  95 The B<dec_cb> callback must return one of the following B<SSL_TICKET_RETURN>
  96 values. Under normal circumstances the B<retv> value is returned unmodified,
  97 but the callback can change the behavior of the post-ticket decryption code
  98 by returning something different. The B<dec_cb> callback must check the B<retv>
  99 value before performing any action.
 100
 101  typedef int SSL_TICKET_RETURN;
 102
 103 =over 4
 104
 105 =item SSL_TICKET_FATAL_ERR_MALLOC
 106
 107 Fatal error, malloc failure.
 108
 109 =item SSL_TICKET_FATAL_ERR_OTHER
 110
 111 Fatal error, either from parsing or decrypting the ticket.
 112
 113 =item SSL_TICKET_NONE
 114
 115 No ticket present.
 116
 117 =item SSL_TICKET_EMPTY
 118
 119 Empty ticket present.
 120
 121 =item SSL_TICKET_NO_DECRYPT
 122
 123 The ticket couldn't be decrypted.
 124
 125 =item SSL_TICKET_SUCCESS
 126
 127 A ticket was successfully decrypted, any session ticket application data should
 128 be available.
 129
 130 =item TICKET_SUCCESS_RENEW
 131
 132 Same as B<TICKET_SUCCESS>, but the ticket needs to be renewed.
 133
 134 =back
 135
 136 =head1 SEE ALSO
 137
 138 L<ssl(7)>,
 139 L<SSL_get_session(3)>
 140
 141 =head1 HISTORY
 142
 143 SSL_CTX_set_session_ticket_cb(), SSSL_SESSION_set1_ticket_appdata() and
 144 SSL_SESSION_get_ticket_appdata() were added to OpenSSL 1.1.1.
 145
 146 =head1 COPYRIGHT
 147
 148 Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
 149
 150 Licensed under the OpenSSL license (the "License").  You may not use
 151 this file except in compliance with the License.  You can obtain a copy
 152 in the file LICENSE in the source distribution or at
 153 L<https://www.openssl.org/source/license.html>.
 154
 155 =cut