Client Session Cache Manager

Detailed Description

Simplifies SSL client session management when connecting to an arbitrary number of servers.

The SharkSSL Session Cache Manager (SharkSslSCMgr) is an optional plugin that simplifies SSL resumption for clients that are designed to connect to an arbitrary number of servers. An instance of the SharkSslSCMgr class maintains a time limited database of servers that have previously been connected and automatically resumes the SSL session for new connections when the server address is found in the database.

Use the SessionCache.c example and the SharkSslSCMgr API reference for the current call sequence. Retain its error handling and trust checks when adapting it to your application.

SharkSslSCMgr requires that the following SharkSSL features are enabled: SHARKSSL_SSL_CLIENT_CODE and SHARKSSL_ENABLE_SESSION_CACHE

Data Structures
struct	SharkSslSCMgrNode
	The handle returned by SharkSslSCMgr_get. More...
struct	SharkSslSCMgr
	See SharkSslSCMgr_constructor for details. More...

Functions
SHARKSSL_API void	SharkSslSCMgr_constructor (SharkSslSCMgr *o, SharkSsl *ssl, U32 maxTime)
	SharkSslSCMgr simplifies using the session API for TLS clients; the constructor initializes a SharkSslSCMgr instance. More...
SHARKSSL_API SharkSslSCMgrNode *	SharkSslSCMgr_get (SharkSslSCMgr *o, SharkSslCon *scon, const char *host, U16 port)
	Resume a session before starting the handshake. More...
SHARKSSL_API int	SharkSslSCMgr_replace (SharkSslSCMgr *o, SharkSslSCMgrNode *n, SharkSslCon *scon)
	Replace the saved session after a resumed TLS 1.3 connection receives a fresh session ticket. More...
SHARKSSL_API int	SharkSslSCMgr_save (SharkSslSCMgr *o, SharkSslCon *scon, const char *host, U16 port)
	Save the session when SharkSslSCMgr_get returns NULL. More...

Function Documentation

SharkSslSCMgr_constructor()

SHARKSSL_API void SharkSslSCMgr_constructor	(	SharkSslSCMgr *	o,
		SharkSsl *	ssl,
		U32	maxTime
	)

SharkSslSCMgr simplifies using the session API for TLS clients; the constructor initializes a SharkSslSCMgr instance.

Parameters

o	an uninitialized static object or dynamically allocated object.
ssl	an initialized SharkSsl instance.
maxTime	the maximum time for stored sessions in seconds. A good value would be 60*60.

SharkSslSCMgr_get()

SHARKSSL_API SharkSslSCMgrNode * SharkSslSCMgr_get	(	SharkSslSCMgr *	o,
		SharkSslCon *	scon,
		const char *	host,
		U16	port
	)

Resume a session before starting the handshake.

The returned handle must not be modified by the caller; NULL means no session was found. The host key must identify the same server name supplied as SNI in the new ClientHello, when SNI is used. Store only sessions whose original server certificate was authenticated for that name; this manager does not verify certificates.

SharkSslSCMgr_replace()

SHARKSSL_API int SharkSslSCMgr_replace	(	SharkSslSCMgr *	o,
		SharkSslSCMgrNode *	n,
		SharkSslCon *	scon
	)

Replace the saved session after a resumed TLS 1.3 connection receives a fresh session ticket.

The saved session remains unchanged if the replacement cannot be acquired.

Parameters

o	an initialized SharkSslSCMgr object.
n	the non-NULL handle returned by SharkSslSCMgr_get.
scon	a valid SharkSslCon object.

Returns

0 if the session was replaced, otherwise -1 is returned.

SharkSslSCMgr_save()

SHARKSSL_API int SharkSslSCMgr_save	(	SharkSslSCMgr *	o,
		SharkSslCon *	scon,
		const char *	host,
		U16	port
	)

Save the session when SharkSslSCMgr_get returns NULL.

It is an error calling this method if SharkSslSCMgr_get returns a handle. The method should be called when closing the connection and just before terminating the SharkSslCon object. For TLS 1.3, save it only after authenticating the server certificate for host.

Parameters

o	an initialized SharkSslSCMgrNode object
scon	a valid SharkSslCon object.
host	the server's domain name
port	the server's port number e.g. 443

Returns

0 if session was saved, otherwise -1 is returned.