iaik.security.ssl

Class SessionTicket

java.lang.Object

iaik.security.ssl.Extension

iaik.security.ssl.SessionTicket

All Implemented Interfaces:

java.lang.Cloneable

public class SessionTicket
extends Extension
implements java.lang.Cloneable

This class implements the session_ticket TLS extension as specified by RFC 4507 (and its successor RFC 5077).

The session_ticket extension is used to do session resuming based on session tickets that are sent from the server to the client. When using ticket based session resuming the server does not have to keep any session related information. Rather he packs this information into a session ticket, encrypts the ticket and sends it to the client within a NewSessionTicket handshake message. For protecting the integrity of the encrypted session ticket a MAC (HMAC-SHA256) is calculated and sent along with the ticket (see RFC 5077):

 struct {
     opaque key_name[16];
     opaque iv[16];
     opaque encrypted_state<0..2^16-1>;
     opaque mac[32];
 } ticket; 
 

If the client wants to use ticket based session resuming he sends an empty SessionTicket extension within an extended ClientHello message. If the server is willing to do ticket based session resuming, too, he responds with an empty SessionTicket extension and later (after he has verified the Finished message of the client) sends an encrypted session ticket within a NewSessionTicket handshake message. The client keeps the ticket received from the server. When he then wants to resume the corresponding session he sends a SessionTicket extension with the ticket to the server who decrypts it to get the required session information (see RFC 5077). Note that the SessionTicket encoding has been changed from RFC 4507 to RFC 5077 which simply puts the ticket into the extension_data field since done so by most applications. This version of iSaSiLk now also uses the 5077 format when sending a SessionTicket extension, but is able to parse both, the 4507 and 5077 format.

On the client side, to enable session_ticket extension support for your SSLClientContext configuration create and set an empty SessionTicket object:

 // create SessionTicket
 SessionTicket sessionTicket = new SessionTicket();
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(sessionTicket);
 ...
 // set extensions for the SSLClientContext configuration:
 SSLClientContext clientContext = new SSLClientContext();
 // extensions are only defined for TLS
 clientContext.setAllowedProtocolVersions(SSLContext.VERSION_TLS10, SSLContext.VERSION_TLS12); 
 ...
 clientContext.setExtensions(extensions);
 ...
 

If you set the critical flag of a client-side SessionTicket to true (client-side default), the handshake will be aborted if the server does not respond with a session_ticket extension.

Since the server needs AES keys and HMAC keys for ticket en/decryption and MAC protection, you may specify a TicketKeyBag when creating a SessionTicket extension object for your iSaSiLk server:

 // specify ticket encryption and mac keys
 TicketKeyBag ticketKeys = ...;
 // create SessionTicket
 SessionTicket sessionTicket = new SessionTicket(ticketKeys);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(sessionTicket);
 ...
 // set extensions for the SSLServerContext configuration:
 SSLServerContext serverContext = new SSLServerContext();
 ...
 serverContext.setExtensions(extensions);
 ...
 

If the specified TicketKeyBag is empty or null, AES and MAC keys will be automatically generated when the server has to encrypt and integrity a session ticket.

If you set the critical flag of a server-side session_ticket extension to true, the handshake will be aborted if the client does not send a session_ticket extension within the extended ClientHello message. If the server receives an encrypted SessionTicket and cannot process it (e.g. because no ticket keys are available to decrypt the SessionTicket) the handshake will be aborted if the critical flag is set to true. Otherwise ( critical flag false) the server will all back to a full handshake.

Version:

File Revision 32

See Also:

Extension, ExtensionList, TicketKeyBag

Field Summary

Fields

Modifier and Type	Field and Description
static ExtensionType	TYPE The type (35) of the session_ticket extension.

Constructor Summary

Constructors

Constructor and Description
SessionTicket() Creates a new SessionTicket extension object.
SessionTicket(TicketKeyBag ticketKeys) Creates a new SessionTicket extension object for the given ticket encryption and mac keys.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Returns a clone of this SessionTicket extension object.
void	setTicketKeysManager(TicketKeysManager manager) Sets the TicketKeysManager to be used on the server side.
void	setTicketLifetime(int lifetime) Sets the session ticket life time.
java.lang.String	toString() Gets a String representation of this SessionTicket.

Methods inherited from class iaik.security.ssl.Extension

getAllowedProtocolVersions, getExtensionType, getName, getType, setCritical

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TYPE

public static final ExtensionType TYPE

The type (35) of the session_ticket extension.

Constructor Detail

SessionTicket

public SessionTicket()

Creates a new SessionTicket extension object.
This constructor may be used on the client side to enable session_ticket extension support for the SSLClientContext configuration:

 // create SessionTicket
 SessionTicket sessionTicket = new SessionTicket();
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(sessionTicket);
 ...
 // set extensions for the SSLClientContext configuration:
 SSLClientContext clientContext = new SSLClientContext();
 ...
 clientContext.setExtensions(extensions);
 ...
 

If you set the critical flag of a client-side extension to true (default), the handshake will be aborted if the server does not respond with a session_ticket extension.

Enabling the session_ticket extension for your SSLClientContext means that the client will suggest the server to do session resuming based on session tickets.

On the server side you may use the SessionTicket(TicketKeyBag) constructor to specify the keys to be used for ticket encryption and mac calculation when creating a SessionTicket extension. However, you also may use the default constructor on the server side (in this case the ticket keys are generated automatically when required).

SessionTicket

public SessionTicket(TicketKeyBag ticketKeys)

Creates a new SessionTicket extension object for the given ticket encryption and mac keys.
This constructor may be used on the server side to enable session_ticket extension support for the SSLServerContext configuration and explicitly specify the AES and MAC keys the server shall use for ticket encryption/decryption and MAC calculation/verification:

 // specify ticket encryption and mac keys
 TicketKeyBag ticketKeys = ...;
 // create SessionTicket
 SessionTicket sessionTicket = new SessionTicket(ticketKeys);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(sessionTicket);
 ...
 // set extensions for the SSLServerContext configuration:
 SSLServerContext serverContext = new SSLServerContext();
 ...
 serverContext.setExtensions(extensions);
 ...
 

If you set the critical flag of a server-side session_ticket extension to true, the handshake will be aborted if the client does not send a session_ticket extension.

If the specified TicketKeyBag is empty or null, AES and MAC keys will be generated automatically when the server has to encrypt and integrity protect a session ticket. You also may use the default constructor to create a SessionTicket extension on the server side for automatically generating ticket encryption keys.

Parameters:

ticketKeys - the AES and MAC keys used by the server for ticket en/decryption and MAC calculation/verification; if null or empty, ticket keys will be automatically generated by the server when required

Method Detail

setTicketLifetime

public void setTicketLifetime(int lifetime)

Sets the session ticket life time.
On the server side this value determines the time period within a ticket will be accepted after the corresponding session has been created the first time.
On the client side this value determines how long a ticket will be stored. If the server sends a ticket_lifetime_hint together with a session ticket, the client will store the ticket for min { lifetime, lifetime_hint } seconds.

A ticket lifetime value of 0 specifies that the ticket lifetime is unspecified. If no ticket lifetime has been explicitly set the resume period value of the iSaSiLk SessionManager will be used as ticket lifetime by default.

Parameters:

lifetime - the ticket lifetime (in seconds) indicating how long the ticket shall be valid (0 for unspecified life time)

setTicketKeysManager

public void setTicketKeysManager(TicketKeysManager manager)

Sets the TicketKeysManager to be used on the server side.

This method may be used by a server application to plug-in its own ticket keys manager application. The TicketKeysManager manages the cipher and mac keys for session ticket protection.

If no TicketKeysManager is set by the server application the DefaultTicketKeysManager is used.

clone

public java.lang.Object clone()

Returns a clone of this SessionTicket extension object.

Overrides:

clone in class Extension

Returns:

a clone of this SessionTicket

toString

public java.lang.String toString()

Gets a String representation of this SessionTicket.

Specified by:

toString in class Extension

Returns:

a String representation of this SessionTicket