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