123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149 |
- =pod
- =head1 NAME
- SSL_CTX_set_session_ticket_cb,
- SSL_SESSION_get0_ticket_appdata,
- SSL_SESSION_set1_ticket_appdata,
- SSL_CTX_generate_session_ticket_fn,
- SSL_CTX_decrypt_session_ticket_fn - manage session ticket application data
- =head1 SYNOPSIS
- #include <openssl/ssl.h>
- typedef int (*SSL_CTX_generate_session_ticket_fn)(SSL *s, void *arg);
- typedef SSL_TICKET_RETURN (*SSL_CTX_decrypt_session_ticket_fn)(SSL *s, SSL_SESSION *ss,
- const unsigned char *keyname,
- size_t keyname_len,
- SSL_TICKET_RETURN retv,
- void *arg);
- int SSL_CTX_set_session_ticket_cb(SSL_CTX *ctx,
- SSL_CTX_generate_session_ticket_fn gen_cb,
- SSL_CTX_decrypt_session_ticket_fn dec_cb,
- void *arg);
- int SSL_SESSION_set1_ticket_appdata(SSL_SESSION *ss, const void *data, size_t len);
- int SSL_SESSION_get0_ticket_appdata(SSL_SESSION *ss, void **data, size_t *len);
- =head1 DESCRIPTION
- SSL_CTX_set_set_session_ticket_cb() sets the application callbacks B<gen_cb>
- and B<dec_cb> that are used by a server to set and get application data stored
- with a session, and placed into a session ticket. Either callback function may
- be set to NULL. The value of B<arg> is passed to the callbacks.
- B<gen_cb> is the application defined callback invoked when a session ticket is
- about to be created. The application can call SSL_SESSION_set1_ticket_appdata()
- at this time to add application data to the session ticket. The value of B<arg>
- is the same as that given to SSL_CTX_set_session_ticket_cb(). The B<gen_cb>
- callback is defined as type B<SSL_CTX_generate_session_ticket_fn>.
- B<dec_cb> is the application defined callback invoked after session ticket
- decryption has been attempted and any session ticket application data is available.
- The application can call SSL_SESSION_get_ticket_appdata() at this time to retrieve
- the application data. The value of B<arg> is the same as that given to
- SSL_CTX_set_session_ticket_cb(). The B<retv> argument is the result of the ticket
- decryption. The B<keyname> and B<keyname_len> identify the key used to decrypt the
- session ticket. The B<dec_cb> callback is defined as type
- B<SSL_CTX_decrypt_session_ticket_fn>.
- SSL_SESSION_set1_ticket_appdata() sets the application data specified by
- B<data> and B<len> into B<ss> which is then placed into any generated session
- tickets. It can be called at any time before a session ticket is created to
- update the data placed into the session ticket. However, given that sessions
- and tickets are created by the handshake, the B<gen_cb> is provided to notify
- the application that a session ticket is about to be generated.
- SSL_SESSION_get0_ticket_appdata() assigns B<data> to the session ticket
- application data and assigns B<len> to the length of the session ticket
- application data from B<ss>. The application data can be set via
- SSL_SESSION_set1_ticket_appdata() or by a session ticket. NULL will be assigned
- to B<data> and 0 will be assigned to B<len> if there is no session ticket
- application data. SSL_SESSION_get0_ticket_appdata() can be called any time
- after a session has been created. The B<dec_cb> is provided to notify the
- application that a session ticket has just been decrypted.
- =head1 NOTES
- When the B<dec_cb> callback is invoked, the SSL_SESSION B<ss> has not yet been
- assigned to the SSL B<s>. The B<retv> indicates the result of the ticket
- decryption which can be modified by the callback before being returned. The
- callback must check the B<retv> value before performing any action, as it's
- called even if ticket decryption fails.
- The B<keyname> and B<keyname_len> arguments to B<dec_cb> may be used to identify
- the key that was used to encrypt the session ticket.
- When the B<gen_cb> callback is invoked, the SSL_get_session() function can be
- used to retrieve the SSL_SESSION for SSL_SESSION_set1_ticket_appdata().
- =head1 RETURN VALUES
- The SSL_CTX_set_session_ticket_cb(), SSL_SESSION_set1_ticket_appdata() and
- SSL_SESSION_get0_ticket_appdata() functions return 1 on success and 0 on
- failure.
- The B<gen_cb> callback must return 1 to continue the connection. A return of 0
- will terminate the connection with an INTERNAL_ERROR alert.
- The B<dec_cb> callback must return one of the following B<SSL_TICKET_RETURN>
- values. Under normal circumstances the B<retv> value is returned unmodified,
- but the callback can change the behavior of the post-ticket decryption code
- by returning something different. The B<dec_cb> callback must check the B<retv>
- value before performing any action.
- typedef int SSL_TICKET_RETURN;
- =over 4
- =item SSL_TICKET_FATAL_ERR_MALLOC
- Fatal error, malloc failure.
- =item SSL_TICKET_FATAL_ERR_OTHER
- Fatal error, either from parsing or decrypting the ticket.
- =item SSL_TICKET_NONE
- No ticket present.
- =item SSL_TICKET_EMPTY
- Empty ticket present.
- =item SSL_TICKET_NO_DECRYPT
- The ticket couldn't be decrypted.
- =item SSL_TICKET_SUCCESS
- A ticket was successfully decrypted, any session ticket application data should
- be available.
- =item TICKET_SUCCESS_RENEW
- Same as B<TICKET_SUCCESS>, but the ticket needs to be renewed.
- =back
- =head1 SEE ALSO
- L<ssl(7)>,
- L<SSL_get_session(3)>
- =head1 HISTORY
- SSL_CTX_set_session_ticket_cb(), SSSL_SESSION_set1_ticket_appdata() and
- SSL_SESSION_get_ticket_appdata() were added to OpenSSL 1.1.1.
- =head1 COPYRIGHT
- Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
- Licensed under the OpenSSL license (the "License"). You may not use
- this file except in compliance with the License. You can obtain a copy
- in the file LICENSE in the source distribution or at
- L<https://www.openssl.org/source/license.html>.
- =cut
|