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

gnutls_session_get_data

gnutls_session_get_id

gnutls_session_set_data

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.

It is highly recommended for clients to enable the session ticket extension using gnutls_session_ticket_enable_client in order to allow resumption with servers that do not store any state.

gnutls_session_ticket_enable_client

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.

gnutls_db_set_retrieve_function

gnutls_db_set_store_function

gnutls_db_set_ptr

gnutls_db_set_remove_function

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