Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SSL_CTX_SET_SESSION_TICKET_CB(3)    OpenSSL   SSL_CTX_SET_SESSION_TICKET_CB(3)

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

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_STATUS status,
								       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);

DESCRIPTION
       SSL_CTX_set_set_session_ticket_cb() sets	the application	callbacks
       gen_cb and 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 arg is passed	to the
       callbacks.

       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 arg is the same as that given to
       SSL_CTX_set_session_ticket_cb().	The gen_cb callback is defined as type
       SSL_CTX_generate_session_ticket_fn.

       dec_cb is the application defined callback invoked after	session	ticket
       decryption has been attempted and any session ticket application	data
       is available. If	ticket decryption was successful then the ss argument
       contains	the session data. The keyname and keyname_len arguments
       identify	the key	used to	decrypt	the session ticket. The	status
       argument	is the result of the ticket decryption.	See the	NOTES section
       below for further details. The value of arg is the same as that given
       to SSL_CTX_set_session_ticket_cb(). The dec_cb callback is defined as
       type SSL_CTX_decrypt_session_ticket_fn.

       SSL_SESSION_set1_ticket_appdata() sets the application data specified
       by data and len into 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
       gen_cb is provided to notify the	application that a session ticket is
       about to	be generated.

       SSL_SESSION_get0_ticket_appdata() assigns data to the session ticket
       application data	and assigns len	to the length of the session ticket
       application data	from ss. The application data can be set via
       SSL_SESSION_set1_ticket_appdata() or by a session ticket. NULL will be
       assigned	to data	and 0 will be assigned to 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 dec_cb is
       provided	to notify the application that a session ticket	has just been
       decrypted.

NOTES
       When the	dec_cb callback	is invoked, the	SSL_SESSION ss has not yet
       been assigned to	the SSL	s. The status indicates	the result of the
       ticket decryption. The callback must check the status value before
       performing any action, as it is called even if ticket decryption	fails.

       The keyname and keyname_len arguments to	dec_cb may be used to identify
       the key that was	used to	encrypt	the session ticket.

       The status argument can be any of these values:

       SSL_TICKET_EMPTY
	   Empty ticket	present. No ticket data	will be	used and a new ticket
	   should be sent to the client. This only occurs in TLSv1.2 or	below.
	   In TLSv1.3 it is not	valid for a client to send an empty ticket.

       SSL_TICKET_NO_DECRYPT
	   The ticket couldn't be decrypted. No	ticket data will be used and a
	   new ticket should be	sent to	the client.

       SSL_TICKET_SUCCESS
	   A ticket was	successfully decrypted,	any session ticket application
	   data	should be available. A new ticket should not be	sent to	the
	   client.

       SSL_TICKET_SUCCESS_RENEW
	   Same	as SSL_TICKET_SUCCESS, but a new ticket	should be sent to the
	   client.

       The return value	can be any of these values:

       SSL_TICKET_RETURN_ABORT
	   The handshake should	be aborted, either because of an error or
	   because of some policy. Note	that in	TLSv1.3	a client may send more
	   than	one ticket in a	single handshake. Therefore just because one
	   ticket is unacceptable it does not mean that	all of them are. For
	   this	reason this option should be used with caution.

       SSL_TICKET_RETURN_IGNORE
	   Do not use a	ticket (if one was available). Do not send a renewed
	   ticket to the client.

       SSL_TICKET_RETURN_IGNORE_RENEW
	   Do not use a	ticket (if one was available). Send a renewed ticket
	   to the client.

	   If the callback does	not wish to change the default ticket
	   behaviour then it should return this	value if status	is
	   SSL_TICKET_EMPTY or SSL_TICKET_NO_DECRYPT.

       SSL_TICKET_RETURN_USE
	   Use the ticket. Do not send a renewed ticket	to the client. It is
	   an error for	the callback to	return this value if status has	a
	   value other than SSL_TICKET_SUCCESS or SSL_TICKET_SUCCESS_RENEW.

	   If the callback does	not wish to change the default ticket
	   behaviour then it should return this	value if status	is
	   SSL_TICKET_SUCCESS.

       SSL_TICKET_RETURN_USE_RENEW
	   Use the ticket. Send	a renewed ticket to the	client.	It is an error
	   for the callback to return this value if status has a value other
	   than	SSL_TICKET_SUCCESS or SSL_TICKET_SUCCESS_RENEW.

	   If the callback does	not wish to change the default ticket
	   behaviour then it should return this	value if status	is
	   SSL_TICKET_SUCCESS_RENEW.

       If status has the value SSL_TICKET_EMPTY	or SSL_TICKET_NO_DECRYPT then
       no session data will be available and the callback must not use the ss
       argument. If status has the value SSL_TICKET_SUCCESS or
       SSL_TICKET_SUCCESS_RENEW	then the application can call
       SSL_SESSION_get0_ticket_appdata() using the session provided in the ss
       argument	to retrieve the	application data.

       When the	gen_cb callback	is invoked, the	SSL_get_session() function can
       be used to retrieve the SSL_SESSION for
       SSL_SESSION_set1_ticket_appdata().

       By default, in TLSv1.2 and below, a new session ticket is not issued on
       a successful resumption and therefore gen_cb will not be	called.	In
       TLSv1.3 the default behaviour is	to always issue	a new ticket on
       resumption. In both cases this behaviour	can be changed if a ticket key
       callback	is in use (see SSL_CTX_set_tlsext_ticket_key_cb(3)).

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 gen_cb callback must	return 1 to continue the connection. A return
       of 0 will terminate the connection with an INTERNAL_ERROR alert.

       The dec_cb callback must	return a value as described in NOTES above.

SEE ALSO
       ssl(7), SSL_get_session(3)

HISTORY
       The SSL_CTX_set_session_ticket_cb(), SSSL_SESSION_set1_ticket_appdata()
       and SSL_SESSION_get_ticket_appdata() functions were added in OpenSSL
       1.1.1.

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
       <https://www.openssl.org/source/license.html>.

1.1.1d				  2019-09-10  SSL_CTX_SET_SESSION_TICKET_CB(3)

NAME | SYNOPSIS | DESCRIPTION | NOTES | RETURN VALUES | SEE ALSO | HISTORY | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=SSL_CTX_set_session_ticket_cb&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help