=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> arguement 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