6.12.2 Session resumption

To reduce time and network traffic spent in a handshake the client can request session resumption from a server that previously shared a session with the client.

Under TLS 1.2, in order to support resumption a server can either store the session security parameters in a local database or use session tickets (see Session tickets) to delegate storage to the client.

Under TLS 1.3, session resumption is only available through session tickets, and multiple tickets could be sent from server to client. That provides the following advantages:

• When tickets are not re-used the subsequent client sessions cannot be associated with each other by an eavesdropper
• On post-handshake authentication the server may send different tickets asynchronously for each identity used by client.

Client side

The client has to retrieve and store the session parameters. Before establishing a new session to the same server the parameters must be re-associated with the GnuTLS session using gnutls_session_set_data.

int gnutls_session_get_data2 (gnutls_session_t session, gnutls_datum_t * data)

int gnutls_session_set_data (gnutls_session_t session, const void * session_data, size_t session_data_size)

Keep in mind that sessions will be expired after some time, depending on the server, and a server may choose not to resume a session even when requested to. The expiration is to prevent temporal session keys from becoming long-term keys. Also note that as a client you must enable, using the priority functions, at least the algorithms used in the last session.

Function: int gnutls_session_is_resumed (gnutls_session_t session)

session: is a gnutls_session_t type.

Checks whether session is resumed or not. This is functional for both server and client side.

Returns: non zero if this session is resumed, or a zero if this is a new session.

Function: int gnutls_session_get_id2 (gnutls_session_t session, gnutls_datum_t * session_id)

session: is a gnutls_session_t type.

session_id: will point to the session ID.

Returns the TLS session identifier. The session ID is selected by the server, and in older versions of TLS was a unique identifier shared between client and server which was persistent across resumption. In the latest version of TLS (1.3) or TLS 1.2 with session tickets, the notion of session identifiers is undefined and cannot be relied for uniquely identifying sessions across client and server.

In client side this function returns the identifier returned by the server, and cannot be assumed to have any relation to session resumption. In server side this function is guaranteed to return a persistent identifier of the session since GnuTLS 3.6.4, which may not necessarily map into the TLS session ID value. Prior to that version the value could only be considered a persistent identifier, under TLS1.2 or earlier and when no session tickets were in use.

The session identifier value returned is always less than GNUTLS_MAX_SESSION_ID_SIZE and should be treated as constant.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise an error code is returned.

Since: 3.1.4

Server side

A server enabling both session tickets and a storage for session data would use session tickets when clients support it and the storage otherwise.

A storing server needs to specify callback functions to store, retrieve and delete session data. These can be registered with the functions below. The stored sessions in the database can be checked using gnutls_db_check_entry for expiration.

void gnutls_db_set_retrieve_function (gnutls_session_t session, gnutls_db_retr_func retr_func)

void gnutls_db_set_store_function (gnutls_session_t session, gnutls_db_store_func store_func)

void gnutls_db_set_ptr (gnutls_session_t session, void * ptr)

void gnutls_db_set_remove_function (gnutls_session_t session, gnutls_db_remove_func rem_func)

int gnutls_db_check_entry (gnutls_session_t session, gnutls_datum_t session_entry)

A server supporting session tickets must generate ticket encryption and authentication keys using gnutls_session_ticket_key_generate. Those keys should be associated with the GnuTLS session using gnutls_session_ticket_enable_server.

Those will be the initial keys, but GnuTLS will rotate them regularly. The key rotation interval can be changed with gnutls_db_set_cache_expiration and will be set to three times the ticket expiration time (ie. three times the value given in that function). Every such interval, new keys will be generated from those initial keys. This is a necessary mechanism to prevent the keys from becoming long-term keys and as such preserve forward-secrecy in the issued session tickets. If no explicit key rotation interval is provided, GnuTLS will rotate them every 18 hours by default.

The master key can be shared between processes or between systems. Processes which share the same master key will generate the same rotated subkeys, assuming they share the same time (irrespective of timezone differences).

Function: int gnutls_session_ticket_enable_server (gnutls_session_t session, const gnutls_datum_t * key)

session: is a gnutls_session_t type.

key: key to encrypt session parameters.

Request that the server should attempt session resumption using session tickets, i.e., by delegating storage to the client. key must be initialized using gnutls_session_ticket_key_generate() . To avoid leaking that key, use gnutls_memset() prior to releasing it.

The default ticket expiration time can be overridden using gnutls_db_set_cache_expiration() .

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, or an error code.

Since: 2.10.0

Function: int gnutls_session_ticket_key_generate (gnutls_datum_t * key)

key: is a pointer to a gnutls_datum_t which will contain a newly created key.

Generate a random key to encrypt security parameters within SessionTicket.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, or an error code.

Since: 2.10.0

Function: int gnutls_session_resumption_requested (gnutls_session_t session)

session: is a gnutls_session_t type.

Check whether the client has asked for session resumption. This function is valid only on server side.

Returns: non zero if session resumption was asked, or a zero if not.

The expiration time for session resumption, either in tickets or stored data is set using gnutls_db_set_cache_expiration. This function also controls the ticket key rotation period. Currently, the session key rotation interval is set to 3 times the expiration time set by this function.

Under TLS 1.3, the server sends by default 2 tickets, and can send additional session tickets at any time using gnutls_session_ticket_send.

Function: int gnutls_session_ticket_send (gnutls_session_t session, unsigned nr, unsigned flags)

session: is a gnutls_session_t type.

nr: the number of tickets to send

flags: must be zero

Sends a fresh session ticket to the peer. This is relevant only in server side under TLS1.3. This function may also return GNUTLS_E_AGAIN or GNUTLS_E_INTERRUPTED and in that case it must be called again.

Returns: GNUTLS_E_SUCCESS on success, or a negative error code.