Session Ticket app data (df0fed9a) · Commits · CYBER - Cyber Security / TS 103 523 MSP / TLMSP / TLMSP OpenSSL

doc/man3/SSL_CTX_set_session_ticket_cb.pod

0 → 100644

+149 −0

Original line number	Diff line number	Diff line
		=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

include/openssl/ssl.h

+32 −0

Original line number	Diff line number	Diff line
		@@ -2294,6 +2294,38 @@ __owur const struct openssl_ssl_test_functions *SSL_test_functions(void);
		__owur int SSL_free_buffers(SSL *ssl);
		__owur int SSL_alloc_buffers(SSL *ssl);

		/* Return codes for tls_get_ticket_from_client() and tls_decrypt_ticket() */
		typedef int SSL_TICKET_RETURN;

		/* Support for ticket appdata */
		/* fatal error, malloc failure */
		# define SSL_TICKET_FATAL_ERR_MALLOC 0
		/* fatal error, either from parsing or decrypting the ticket */
		# define SSL_TICKET_FATAL_ERR_OTHER 1
		/* No ticket present */
		# define SSL_TICKET_NONE 2
		/* Empty ticket present */
		# define SSL_TICKET_EMPTY 3
		/* the ticket couldn't be decrypted */
		# define SSL_TICKET_NO_DECRYPT 4
		/* a ticket was successfully decrypted */
		# define SSL_TICKET_SUCCESS 5
		/* same as above but the ticket needs to be renewed */
		# define SSL_TICKET_SUCCESS_RENEW 6

		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_length,
		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);

		extern const char SSL_version_str[];

ssl/ssl_asn1.c

+19 −1

Original line number	Diff line number	Diff line
		@@ -43,6 +43,7 @@ typedef struct {
		ASN1_OCTET_STRING *alpn_selected;
		ASN1_OCTET_STRING *tick_nonce;
		uint32_t tlsext_max_fragment_len_mode;
		ASN1_OCTET_STRING *ticket_appdata;
		} SSL_SESSION_ASN1;

		ASN1_SEQUENCE(SSL_SESSION_ASN1) = {
		@@ -73,7 +74,8 @@ ASN1_SEQUENCE(SSL_SESSION_ASN1) = {
		ASN1_EXP_OPT_EMBED(SSL_SESSION_ASN1, max_early_data, ZUINT32, 15),
		ASN1_EXP_OPT(SSL_SESSION_ASN1, alpn_selected, ASN1_OCTET_STRING, 16),
		ASN1_EXP_OPT(SSL_SESSION_ASN1, tick_nonce, ASN1_OCTET_STRING, 17),
		ASN1_EXP_OPT_EMBED(SSL_SESSION_ASN1, tlsext_max_fragment_len_mode, ZUINT32, 18)
		ASN1_EXP_OPT_EMBED(SSL_SESSION_ASN1, tlsext_max_fragment_len_mode, ZUINT32, 18),
		ASN1_EXP_OPT(SSL_SESSION_ASN1, ticket_appdata, ASN1_OCTET_STRING, 19)
		} static_ASN1_SEQUENCE_END(SSL_SESSION_ASN1)

		IMPLEMENT_STATIC_ASN1_ENCODE_FUNCTIONS(SSL_SESSION_ASN1)
		@@ -123,6 +125,7 @@ int i2d_SSL_SESSION(SSL_SESSION in, unsigned char *pp)
		#endif
		ASN1_OCTET_STRING alpn_selected;
		ASN1_OCTET_STRING tick_nonce;
		ASN1_OCTET_STRING ticket_appdata;

		long l;

		@@ -200,6 +203,12 @@ int i2d_SSL_SESSION(SSL_SESSION in, unsigned char *pp)

		as.tlsext_max_fragment_len_mode = in->ext.max_fragment_len_mode;

		if (in->ticket_appdata == NULL)
		as.ticket_appdata = NULL;
		else
		ssl_session_oinit(&as.ticket_appdata, &ticket_appdata,
		in->ticket_appdata, in->ticket_appdata_len);

		return i2d_SSL_SESSION_ASN1(&as, pp);

		}
		@@ -376,6 +385,15 @@ SSL_SESSION d2i_SSL_SESSION(SSL_SESSION a, const unsigned char *pp,

		ret->ext.max_fragment_len_mode = as->tlsext_max_fragment_len_mode;

		if (as->ticket_appdata != NULL) {
		ret->ticket_appdata = as->ticket_appdata->data;
		ret->ticket_appdata_len = as->ticket_appdata->length;
		as->ticket_appdata->data = NULL;
		} else {
		ret->ticket_appdata = NULL;
		ret->ticket_appdata_len = 0;
		}

		M_ASN1_free_of(as, SSL_SESSION_ASN1);

		if ((a != NULL) && (*a == NULL))

ssl/ssl_lib.c

+11 −0

Original line number	Diff line number	Diff line
		@@ -5409,3 +5409,14 @@ int SSL_verify_client_post_handshake(SSL *ssl)
		ossl_statem_set_in_init(ssl, 1);
		return 1;
		}

		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)
		{
		ctx->generate_ticket_cb = gen_cb;
		ctx->decrypt_ticket_cb = dec_cb;
		ctx->ticket_cb_data = arg;
		return 1;
		}

ssl/ssl_locl.h

+13 −24

Original line number	Diff line number	Diff line
		@@ -591,6 +591,8 @@ struct ssl_session_st {
		# ifndef OPENSSL_NO_SRP
		char *srp_username;
		# endif
		unsigned char *ticket_appdata;
		size_t ticket_appdata_len;
		uint32_t flags;
		CRYPTO_RWLOCK *lock;
		};
		@@ -1025,6 +1027,11 @@ struct ssl_ctx_st {
		size_t (record_padding_cb)(SSL s, int type, size_t len, void *arg);
		void *record_padding_arg;
		size_t block_padding;

		/* Session ticket appdata */
		SSL_CTX_generate_session_ticket_fn generate_ticket_cb;
		SSL_CTX_decrypt_session_ticket_fn decrypt_ticket_cb;
		void *ticket_cb_data;
		};

		struct ssl_st {
		@@ -2446,27 +2453,9 @@ void tls1_get_supported_groups(SSL s, const uint16_t *pgroups,

		__owur int tls1_set_server_sigalgs(SSL *s);

		/* Return codes for tls_get_ticket_from_client() and tls_decrypt_ticket() */
		typedef enum ticket_en {
		/* fatal error, malloc failure */
		TICKET_FATAL_ERR_MALLOC,
		/* fatal error, either from parsing or decrypting the ticket */
		TICKET_FATAL_ERR_OTHER,
		/* No ticket present */
		TICKET_NONE,
		/* Empty ticket present */
		TICKET_EMPTY,
		/* the ticket couldn't be decrypted */
		TICKET_NO_DECRYPT,
		/* a ticket was successfully decrypted */
		TICKET_SUCCESS,
		/* same as above but the ticket needs to be renewed */
		TICKET_SUCCESS_RENEW
		} TICKET_RETURN;

		__owur TICKET_RETURN tls_get_ticket_from_client(SSL s, CLIENTHELLO_MSG hello,
		__owur SSL_TICKET_RETURN tls_get_ticket_from_client(SSL s, CLIENTHELLO_MSG hello,
		SSL_SESSION **ret);
		__owur TICKET_RETURN tls_decrypt_ticket(SSL s, const unsigned char etick,
		__owur SSL_TICKET_RETURN tls_decrypt_ticket(SSL s, const unsigned char etick,
		size_t eticklen,
		const unsigned char *sess_id,
		size_t sesslen, SSL_SESSION **psess);