SharkSSL™ Embedded SSL/TLS Stack
SSL Session Management

SSL Session resumption can significantly speed up the SSL handshaking. More...

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 SharkSslSession_release (SharkSslSession *o, SharkSsl *s)
 Release a session created by function SharkSslCon_acquireSession.
 
SHARKSSL_API U8 SharkSslCon_releaseSession (SharkSslCon *o)
 experimental
 
SHARKSSL_API SharkSslSessionSharkSslCon_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...
 

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:

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.

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
othe SharkSslCon object.
sa 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);