RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

Session Cache Functions

This section describes the functions that provide support to SSL_SESSION cache manipulation.

Typedefs

typedef int R_CDECL SSL_SESS_NEW_CB_T (SSL *ssl, SSL_SESSION *session)
 A type of callback function that adds a new session into an external cache. More...

typedef void R_CDECL SSL_SESS_REMOVE_CB_T (SSL_CTX *ssl, SSL_SESSION *session)
 A type of callback function that removes a session from an external cache. More...

typedef SSL_SESSION* R_CDECL SSL_SESS_GET_CB_T (SSL *ssl, unsigned char *sess_id, int id_len, int *copyflag)
 A type of callback function that retrieves a session from an external cache based on an unique session identifier. More...


Functions

int SSL_CTX_set_session_cache_mode (SSL_CTX *ctx, int mode)
 Sets the session cache mode for the SSL_CTX ctx. More...

int SSL_CTX_get_session_cache_mode (SSL_CTX *ctx)
 Returns the session cache mode for the SSL_CTX ctx. More...

long R_CDECL SSL_CTX_set_timeout (SSL_CTX *ctx, long tmout)
 Sets the timeout period for the SSL_CTX ctx. More...

long R_CDECL SSL_CTX_get_timeout (SSL_CTX *ctx)
 Returns the session identifier timeout period inherited by the SSL structures created using the SSL_CTX ctx. More...

long R_CDECL SSL_get_default_timeout (SSL *ssl)
 Returns the default timeout period (in seconds) for SSL sessions created by a particular SSL version (that is, SSLv2, SSLv3 or TLSv1). More...

int R_CDECL SSL_CTX_set_session_cache_cb (SSL_CTX *ctx, SSL_SESSION_CACHE_CB_T *cb)
 Sets the callback which is invoked for all session cache requests. More...

SSL_SESSION_CACHE_CB_T* R_CDECL SSL_CTX_get_session_cache_cb (SSL_CTX *ctx)
 Returns the callback which is invoked for all session cache requests. More...

int R_CDECL SSL_CTX_set_session_cache_cb_arg (SSL_CTX *ctx, void *cb_arg)
 Sets a pointer argument that can be accessed by the session cache callback through its argument list. More...

void* R_CDECL SSL_CTX_get_session_cache_cb_arg (SSL_CTX *ctx)
 Returns the pointer argument that is passed to the session cache callback. More...

int R_CDECL SSL_CTX_simple_session_cb (SSL_CTX *ctx, int cmd, SSL_SESSION **sess_ptr, void *arg)
 Provides a minimal session cache. More...

int R_CDECL SSL_CTX_simple_session_init (SSL_SIMPLE_SESSION_CACHE **cache_ptr)
 Initializes the single session cache. More...

int R_CDECL SSL_CTX_simple_session_final (SSL_SIMPLE_SESSION_CACHE **cache_ptr)
 Finalizes the session cache by clearing all the fields of the session cache and freeing the cache memory. More...

Typedef Documentation

typedef SSL_SESSION* R_CDECL SSL_SESS_GET_CB_T(SSL *ssl, unsigned char *sess_id, int id_len, int *copyflag)
 

A type of callback function that retrieves a session from an external cache based on an unique session identifier.

Parameters:
ssl [In] The SSL reference against which the retrieved session will be stored.
sess_id [In] A session identifier that uniquely identifies the cache.
id_len [In] The length of the session identifier.
copy_flag [Out] A flag that indicates where the retrieved session is to be duplicated (and hence must be explicitly freed). One of:
  • 1 indicates to duplicate the session.
  • 0 indicates to not duplicate the session.
    • See also:
    SSL_CTX_sess_set_new_cb(), SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_set_remove_cb(), SSL_CTX_sess_get_remove_cb(), SSL_CTX_sess_set_get_cb() and SSL_CTX_sess_get_get_cb().

    typedef int R_CDECL SSL_SESS_NEW_CB_T(SSL *ssl, SSL_SESSION *session)
     

    A type of callback function that adds a new session into an external cache.

    Parameters:
    ssl [In] The SSL reference where the session was established.
    session [In] The SSL_SESSION to add to the cache.
    See also:
    SSL_CTX_sess_set_new_cb(), SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_set_remove_cb(), SSL_CTX_sess_get_remove_cb(), SSL_CTX_sess_set_get_cb() and SSL_CTX_sess_get_get_cb().

    typedef void R_CDECL SSL_SESS_REMOVE_CB_T(SSL_CTX *ssl, SSL_SESSION *session)
     

    A type of callback function that removes a session from an external cache.

    Parameters:
    ssl [In] The SSL_CTX reference with which the external cache is associated.
    session [In] The SSL_SESSION to remove from the cache.
    See also:
    SSL_CTX_sess_set_new_cb(), SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_set_remove_cb(), SSL_CTX_sess_get_remove_cb(), SSL_CTX_sess_set_get_cb() and SSL_CTX_sess_get_get_cb().

    Function Documentation

    SSL_SESSION_CACHE_CB_T* R_CDECL SSL_CTX_get_session_cache_cb (  SSL_CTX *    ctx )  ;
     

    Returns the callback which is invoked for all session cache requests.

    Parameters:
    ctx [In] A reference to an SSL_CTX.
    Returns:
    A function pointer to the current session caching callback.
    NULL indicates no session cache callback is set.

    void* R_CDECL SSL_CTX_get_session_cache_cb_arg (  SSL_CTX *    ctx )  ;
     

    Returns the pointer argument that is passed to the session cache callback.

    Parameters:
    ctx [In] A reference to a SSL_CTX.
    Returns:
    The argument for the session cache callback.
    NULL indicates no argument is set.

    int SSL_CTX_get_session_cache_mode (  SSL_CTX *    ctx )  ;
     

    Returns the session cache mode for the SSL_CTX ctx.

    Parameters:
    ctx [In] The SSL_CTX reference from which to retrieve the session cache mode.
    Returns:
    The session cache mode.
    See also:
    SSL_CTX_set_session_cache_mode().
    Example:

    SSL_CTX *ssl_ctx;
int mode;

/* ssl_ctx = SSL_CTX_new(...) */

mode = SSL_CTX_get_session_cache_mode(ssl_ctx);

if ((mode&SSL_SESS_CACHE_CLIENT) != 0)
{
        /* Ensure that session caching is not used by clients */
        mode = mode ^ SSL_SESS_CACHE_CLIENT;
        SSL_CTX_set_session_cache_mode(ssl_ctx,mode);
}
    Samples:
    app_cache.c.

    long R_CDECL SSL_CTX_get_timeout (  SSL_CTX *    ctx )  ;
     

    Returns the session identifier timeout period inherited by the SSL structures created using the SSL_CTX ctx.

    Parameters:
    ctx [In] The SSL_CTX reference from which to retrieve the session timeout.
    Returns:
    The session timeout period (in seconds).
    0 indicates SSL_CTX is NULL.
    See also:
    SSL_CTX_set_timeout().

    int R_CDECL SSL_CTX_set_session_cache_cb (  SSL_CTX *    ctx,
    SSL_SESSION_CACHE_CB_T *    cb
    )  ;
     

    Sets the callback which is invoked for all session cache requests.

    Parameters:
    ctx [In] A reference to an SSL_CTX.
    cb [In] A function pointer to the session cache callback.
    Returns:
    1 indicates the session cache callback is installed.
    note.gif
    This function always returns 1.
    Any existing session cache callback is replaced by the new callback. All session caching callbacks can be removed by setting a NULL callback.
    Samples:
    cache_server.c.

    int R_CDECL SSL_CTX_set_session_cache_cb_arg (  SSL_CTX *    ctx,
    void *    cb_arg
    )  ;
     

    Sets a pointer argument that can be accessed by the session cache callback through its argument list.

    Parameters:
    ctx [In] A reference to an SSL_CTX that will cache sessions.
    cb_arg [In] A pointer argument for the session cache callback.
    Returns:
    1 indicates the session cache callback argument was installed.
    note.gif
    This function always returns 1.
    The callback argument set by this function replaces any existing callback argument. A NULL argument may be set to clear the argument.
    Samples:
    cache_server.c.

    int SSL_CTX_set_session_cache_mode (  SSL_CTX *    ctx,
    int    mode
    )  ;
     

    Sets the session cache mode for the SSL_CTX ctx.

    Parameters:
    ctx [In] The SSL_CTX reference against which to set the mode.
    mode [In] The new session cache mode.
    Bit wise or see Session Cache Modes for valid modes.
    Returns:
    The previous session cache mode value.
    note.gif
    SSL_SESS_CACHE_SERVER is the default when the SSL_CTX is created.
    See also:
    SSL_CTX_get_session_cache_mode(), SSL_CTX_get_timeout() and SSL_CTX_set_timeout().
    Example:

    SSL_CTX *ssl_ctx;
int new_mode;
int old_mode;

/* ssl_ctx = SSL_CTX_new(...) */

/* Cache session id's only on the server side and
 * don't automatically clear the cache
 */
new_mode = SSL_SESS_CACHE_SERVER | SSL_SESS_NO_AUTO_CLEAR;
old_mode = SSL_CTX_set_session_cache_mode(ssl_ctx,new_mode);
    Samples:
    cache_server.c.

    long R_CDECL SSL_CTX_set_timeout (  SSL_CTX *    ctx,
    long    tmout
    )  ;
     

    Sets the timeout period for the SSL_CTX ctx. Session identifiers are only valid for certain periods. The timeout period is set on a per session identifier basis, so changing the timeout will not affect the timeout on existing session identifiers. The timeout is in effect inherited from the SSL_CTX by an SSL structure that is created against it.

    Parameters:
    ctx [In] The SSL_CTX reference against which to set the session timeout.
    tmout [In] The timeout value (in seconds).
    Returns:
    >0 indicates a pre-existing timeout value.
    0 indicates the SSL_CTX passed is NULL.
    note.gif
    A default value is used if the timeout is 0. The default is 2 hours for SSLv3 and TLSv1, and 300 seconds for SSLv2 and SSLv23.
    See also:
    SSL_CTX_get_timeout().
    Samples:
    cache_server.c.

    int R_CDECL SSL_CTX_simple_session_cb (  SSL_CTX *    ctx,
    int    cmd,
    SSL_SESSION **    sess_ptr,
    void *    arg
    )  ;
     

    Provides a minimal session cache. The minimal session cache holds a single session in the cache. This is useful for a single peer making multiple simultaneous or consecutive connections. The implementation is thread-safe if a locking callback is available. This callback must be installed by the application before it will be used and the cache structure must be installed as the argument for this callback.

    Parameters:
    ctx [In] A reference to an SSL_CTX.
    cmd [In] A caching operation command. See External Session Cache Command Codes for valid values.
    sess_ptr [In, Out] The address of a reference to an SSL_SESSION. On input, the reference will contain a session template which will have enough session data to locate a matching session stored in the cache via a call to SSL_SESSION_cmp(). The result of a successful find operation will be returned through this argument.
    arg [In] A reference to the session cache.
    Returns:
    1 indicates the caching operation succeeds.
    0 indicates the caching operation does not succeed or if an unknown operation is attempted.
    note.gif
    All calls to this callback are made by the SSL library.
    See also:
    SSL_CTX_set_session_cache_cb() and SSL_CTX_set_session_cache_cb_arg().

    int R_CDECL SSL_CTX_simple_session_final (  SSL_SIMPLE_SESSION_CACHE **    cache_ptr )  ;
     

    Finalizes the session cache by clearing all the fields of the session cache and freeing the cache memory.

    Parameters:
    cache_ptr [In, Out] The address to a reference to a session cache. The memory referred to will be freed and the reference returned as NULL.
    Returns:
    1 indicates the cache was finalized successfully.
    0 indicates the cache is not valid.
    The session cache pointer will be set to NULL if the function is successful.
    note.gif
    Cache finalization is performed outside the multi-threading part of the program. This function is not thread-safe.

    int R_CDECL SSL_CTX_simple_session_init (  SSL_SIMPLE_SESSION_CACHE **    cache_ptr )  ;
     

    Initializes the single session cache. The session cache has memory allocated and the fields are set to initial values. The session cache should be set to be the argument for the session cache callback.

    Parameters:
    cache_ptr [Out] The address of a reference for a new session cache.
    Returns:
    1 indicates the cache was initialized successfully.
    0 if the cache could not be allocated. The cache reference will be set to NULL.
    note.gif
    Cache initialization must be performed before any multi-threading as no locking is performed by this function.
    See also:
    SSL_CTX_set_session_cache_cb_arg().

    long R_CDECL SSL_get_default_timeout (  SSL *    ssl )  ;
     

    Returns the default timeout period (in seconds) for SSL sessions created by a particular SSL version (that is, SSLv2, SSLv3 or TLSv1). When an SSL_CTX is created, its session identifier timeout is the default value for the SSL version.

    Parameters:
    ssl [In] The SSL connection reference from which to retrieve the session timeout.
    Returns:
    The timeout period in seconds.
    See also:
    SSL_CTX_set_timeout() and SSL_CTX_get_timeout().

    Copyright (c) 1999-2005 RSA Security Inc. All rights reserved. 072-001001-2100-001-000 - 2.1