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.

Set the session cache size when you initialize a SharkSsl instance. Follow the constructor documentation for the size parameter and the protocol-specific session APIs for acquisition and reuse.

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 after a successful, authenticated connection. Check for NULL, which indicates that the session pool is exhausted. For TLS 1.3, follow the API requirements for receiving a session ticket before expecting usable resumption state.
• 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 peer may accept resumption or require a full handshake. Handle both outcomes and check the connection result before exchanging data.
• Reuse sessions only for the intended authenticated service. Keep the original Server Name Indication (SNI) name when reconnecting. Check SharkSslCon_resumeSession and handle a full-handshake fallback.
• When you no longer need the session, release it with 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.

Use a bounded session lifetime appropriate to your service. Check the API documentation for ticket expiry and cache lifetime behavior.

Modules
	Client Session Cache Manager
	Simplifies SSL client session management when connecting 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.

For TLS 1.3, if SNI is set before the handshake, SharkSSL offers the PSK only when the new name matches a dNSName in the original server certificate. Otherwise it falls back to a full handshake. The caller should normally reuse the original SNI name and must save only sessions whose original peer certificate was authenticated. This function selects the session; the SNI check occurs when the ClientHello is built, regardless of whether setSNI was called before or after resumeSession.

Parameters

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

Returns

TRUE if the session was selected for a resumption attempt, or FALSE if it could not be selected. A later full handshake may still be required.

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);