6.12.1 Session resumption

Client side

To reduce time and roundtrips spent in a handshake the client can request session resumption from a server that previously shared a session with. For that 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_get_id2 (gnutls_session_t session, gnutls_datum_t * session_id)

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 structure.

Check whether session is resumed or not.

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

Server side

In order to support resumption a server can store the session security parameters in a local database or by using session tickets (see Session tickets) to delegate storage to the client. Because session tickets might not be supported by all clients, servers could combine the two methods.

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 utilizing tickets should 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.

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

session: is a gnutls_session_t structure.

key: key to encrypt session parameters.

Request that the server should attempt session resumption using SessionTicket. key must be initialized with gnutls_session_ticket_key_generate() .

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 structure.

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.

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