SSL Session Management

Detailed Description

SSL Session resumption can significantly speed up the SSL handshaking.

Session reuse improves SSL performance in stateless protocols such as HTTP, where the socket connections are frequently recycled. Session reuse also minimizes the hefty CPU calculation required by asymmetric encryption.

You do not need the SSL session management functionality if you only maintain persistent connections with the peer such as persistent socket connections. You can disable (remove) the session management code by setting SHARKSSL_ENABLE_SESSION_CACHE to 0.

The size of the session cache must be set when you initialize a SharkSsl instance. PATCH fixme what is the server doing??

SSL session management is automatic when using SharkSSL in server mode i.e. for solutions that set parameter 'role' to SharkSsl_Server when calling the SharkSsl_constructor. Client SSL solutions require session management assistance from the application.

Implementing client session resumption

The application using SharkSSL in client mode has three functions it must use in order to aid the SharkSSL stack in using SSL resumption.

The sequence is as follows:

• For each server you plan on communicating with, keep one SharkSslSession object. A SharkSslSession object is allocated by calling SharkSslCon_acquireSession. You must call SharkSslCon_acquireSession just after that you have completed the initial full handshake.
• Subsequent sessions with the same server can be resumed by using the SharkSslSession object. You do this by calling SharkSslCon_resumeSession, just after that you have established the network connection and just before performing the SSL handshake.
• The SSL handshake will now be much faster since we are resuming the session.
• When you no longer need the session, terminate it by calling function SharkSslSession_release

The above sequence can easily be implemented when communicating with a fixed number of servers, however, it becomes complicated when your design requires that you connect to an arbitrary number of servers. The SharkSSL Session Cache Manager is an optional plugin that simplifies client sessions management when communicating with many servers.

Note: For security reasons, sessions should not be used for more than one hour.

Modules
	Client Session Cache Manager
	Simplifies SSL client session management when connectiong to an arbitrary number of servers.

Typedefs
typedef struct SharkSslSession	SharkSslSession
	SharkSslSession is an opaque handle returned by function SharkSslCon_acquireSession.

Functions
SHARKSSL_API U8	SharkSslCon_isResumed (SharkSslCon *o)
	Returns 1 if the current session is a resumed one.
SHARKSSL_API U8	SharkSslSession_release (SharkSslSession *o, SharkSsl *s)
	Release a session created by function SharkSslCon_acquireSession.
SHARKSSL_API U8	SharkSslCon_releaseSession (SharkSslCon *o)
	experimental
SHARKSSL_API SharkSslSession *	SharkSslCon_acquireSession (SharkSslCon *o)
	Request a SharkSslSession object from the client's session pool. More...
SHARKSSL_API U8	SharkSslCon_resumeSession (SharkSslCon *o, SharkSslSession *s)
	Resume an existing session. More...
SHARKSSL_API U32	SharkSslSession_getLatestAccessTime (SharkSslSession *o)
	Returns the last time the session was accessed. More...

Function Documentation

SharkSslCon_acquireSession()

SHARKSSL_API SharkSslSession * SharkSslCon_acquireSession

(

SharkSslCon *

o

)

Request a SharkSslSession object from the client's session pool.

Returns

a SharkSslSession object on success or NULL if the session cache pool is exhausted. See parameter 'cacheSize' in function SharkSsl_constructor for more information on the cache size.

SharkSslCon_resumeSession()

SHARKSSL_API U8 SharkSslCon_resumeSession	(	SharkSslCon *	o,
		SharkSslSession *	s
	)

Resume an existing session.

Parameters

o	the SharkSslCon object.
s	a session object created by function SharkSslCon_acquireSession.

Returns

TRUE on success or FALSE if the session cannot be resumed.

SharkSslSession_getLatestAccessTime()

SHARKSSL_API U32 SharkSslSession_getLatestAccessTime

(

SharkSslSession *

o

)

Returns the last time the session was accessed.

Delta time can be calculated as follows: baGetUnixTime() - SharkSslSession_getLatestAccessTime(ss);