RSA BSAFE SSL-C

Security protocol components for C

Search

Session Cache Functions

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

Typedefs

typedef int 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 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* 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

long SSL_CTX_sess_set_cache_size (SSL_CTX *ctx, long csize)
 Sets the maximum size of the cache in entries for the SSL_CTX ctx. More...

long SSL_CTX_sess_get_cache_size (SSL_CTX *ctx)
 Returns the current cache size setting for the SSL_CTX ctx. More...

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 SSL_CTX_set_max_rsa_n_size (SSL_CTX *ssl_ctx, unsigned long size)
 Allows the server to set the maximum size of the client certificate public key modulus. More...

long SSL_CTX_set_max_rsa_e_size (SSL_CTX *ssl_ctx, unsigned long size)
 Allows the server to set the maximum size of the client certificate public key exponent. More...

void SSL_CTX_sess_set_new_cb (SSL_CTX *ctx, SSL_SESS_NEW_CB_T *new_session_cb)
 Sets a callback which is invoked when a session is added to the session identifier cache. More...

SSL_SESS_NEW_CB_T* SSL_CTX_sess_get_new_cb (SSL_CTX *ctx)
 Returns the callback which is invoked when a session is added to the session identifier cache. More...

void SSL_CTX_sess_set_remove_cb (SSL_CTX *ctx, SSL_SESS_REMOVE_CB_T *remove_session_cb)
 Sets a callback which is invoked when a session is removed from the session identifier cache. More...

SSL_SESS_REMOVE_CB_T* SSL_CTX_sess_get_remove_cb (SSL_CTX *ctx)
 Returns the callback which is invoked when a session is removed from the session identifier cache. More...

void SSL_CTX_sess_set_get_cb (SSL_CTX *ctx, SSL_SESS_GET_CB_T *get_session_cb)
 Sets a callback which is invoked when a session is looked up in the session identifier cache and is not found or if there is no internal caching. More...

SSL_SESS_GET_CB_T* SSL_CTX_sess_get_get_cb (SSL_CTX *ctx)
 Returns the callback invoked when a session is looked up in the session identifier cache and is not found. More...

int SSL_CTX_add_session (SSL_CTX *ctx, SSL_SESSION *sess)
 Adds the SSL session sess to the SSL_CTX structure ctx. More...

int SSL_CTX_remove_session (SSL_CTX *ctx, SSL_SESSION *sess)
 Removes the session sess from the session cache of the SSL_CTX structure ctx. More...

int SSL_CTX_flush_sessions (SSL_CTX *ctx, int timeout)
 Flushes out-of-date sessions from the session cache. More...

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

long 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 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...

Typedef Documentation

typedef SSL_SESSION* 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 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 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

    int SSL_CTX_add_session (  SSL_CTX *    ctx,
    SSL_SESSION *    sess
    )  ;
     

    Adds the SSL session sess to the SSL_CTX structure ctx.

    Parameters:
    ctx [In] The SSL_SESSION context reference into which to to add the session.
    sess [In] The SSL_SESSION reference to add.
    Returns:
    0 indicates the new session replaces an existing session in the cache (including itself). 1 indicates a new session is being added to the cache.
    note.gif
    Most applications do not use SSL_CTX_add_session() as the default SSL session handing is sufficient.
    The SSL_SESSION is added to the SSL_CTX regardless of the session caching mode of the SSL_CTX.
    See also:
    SSL_CTX_remove_session() and SSL_CTX_set_session_cache_mode().

    int SSL_CTX_flush_sessions (  SSL_CTX *    ctx,
    int    timeout
    )  ;
     

    Flushes out-of-date sessions from the session cache.

    Parameters:
    ctx [In] The SSL_CTX that holds the session cache.
    timeout [In] The mode used to flush sessions. One of:
    ModeDescription
    SSL_FLUSH_OLD Removes all sessions from the session cache that are due to timeout by the current time.
    SSL_FLUSH_ALL Remove all sessions regardless of their timeout periods.
    Returns:
    1 indicates success.
    0 indicates error.
    note.gif
    A successful flush operation will not remove any sessions from the cache if there are no out-of-date sessions. If the cache does not exist or if the data used to flush sessions cannot be set up then the cache will not be flushed. If the mode is not one of the allowed values the cache will not be flushed.

    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 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 SSL_CTX_remove_session (  SSL_CTX *    ctx,
    SSL_SESSION *    sess
    )  ;
     

    Removes the session sess from the session cache of the SSL_CTX structure ctx.

    Parameters:
    ctx [In] The SSL_CTX reference from which to remove the session.
    sess [In] The SSL_SESSION reference to remove.
    Returns:
    1 indicates success.
    0 indicates error or that the session was not in the cache.
    note.gif
    Most applications do not use this function as the default SSL session handling is sufficient. By default only the server side keeps sessions from the connections made.
    Sessions removed from the cache remain valid for any connections that currently use them, but are not available for future connections.
    See also:
    SSL_CTX_add_session(), SSL_CTX_flush_sessions() and SSL_CTX_set_session_cache_mode().

    long SSL_CTX_sess_get_cache_size (  SSL_CTX *    ctx )  ;
     

    Returns the current cache size setting for the SSL_CTX ctx. The current cache size is the maximum number of entries that will be held in the session cache. Note that this is not the current occupancy.

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

    SSL_SESS_GET_CB_T* SSL_CTX_sess_get_get_cb (  SSL_CTX *    ctx )  ;
     

    Returns the callback invoked when a session is looked up in the session identifier cache and is not found. Can also be returned if there is no internal caching.

    Parameters:
    ctx [In] The SSL_CTX reference from which to retrieve the session callback reference.
    Returns:
    A pointer to the current get_session_cb.
    NULL indicates no user-defined session was found.
    See also:
    SSL_CTX_sess_set_get_cb().

    SSL_SESS_NEW_CB_T* SSL_CTX_sess_get_new_cb (  SSL_CTX *    ctx )  ;
     

    Returns the callback which is invoked when a session is added to the session identifier cache.

    Parameters:
    ctx [In] The SSL_CTX reference from which to retrieve the new session callback reference.
    Returns:
    A pointer to the current new_session_cb. This may be NULL.
    See also:
    SSL_CTX_sess_set_new_cb().

    SSL_SESS_REMOVE_CB_T* SSL_CTX_sess_get_remove_cb (  SSL_CTX *    ctx )  ;
     

    Returns the callback which is invoked when a session is removed from the session identifier cache.

    Parameters:
    ctx [In] The SSL_CTX reference from which to remove the session callback.
    Returns:
    A pointer to the current remove_session_cb.
    NULL indicates no user-defined callback was found.
    See also:
    SSL_CTX_sess_set_remove_cb().

    long SSL_CTX_sess_set_cache_size (  SSL_CTX *    ctx,
    long    csize
    )  ;
     

    Sets the maximum size of the cache in entries for the SSL_CTX ctx. For example, users may only want to store 200 session identifiers.

    Parameters:
    ctx [In, Out] The SSL_CTX reference against which to set the session cache size.
    csize [In] The new session cache size.
    Returns:
    The pre-existing session cache size.
    note.gif
    The default cache size is 20480 entries.
    Setting the cache size to 0 indicates no entries will be stored in the cache.
    See also:
    SSL_CTX_sess_get_cache_size().

    void SSL_CTX_sess_set_get_cb (  SSL_CTX *    ctx,
    SSL_SESS_GET_CB_T *    get_session_cb
    )  ;
     

    Sets a callback which is invoked when a session is looked up in the session identifier cache and is not found or if there is no internal caching.

    Parameters:
    ctx [In] The SSL_CTX reference against which to set the session callback against.
    get_session_cb [In] A pointer to the external cache get-action callback function.
    See also:
    SSL_CTX_sess_get_get_cb().

    void SSL_CTX_sess_set_new_cb (  SSL_CTX *    ctx,
    SSL_SESS_NEW_CB_T *    new_session_cb
    )  ;
     

    Sets a callback which is invoked when a session is added to the session identifier cache. The callback can be used to check whether the session exists in a user-defined/external session cache.

    Parameters:
    ctx [In] The SSL_CTX reference.
    new_session_cb [In] A pointer to the callback function.
    note.gif
    No callback is set by default.
    See also:
    SSL_CTX_sess_get_new_cb().

    void SSL_CTX_sess_set_remove_cb (  SSL_CTX *    ctx,
    SSL_SESS_REMOVE_CB_T *    remove_session_cb
    )  ;
     

    Sets a callback which is invoked when a session is removed from the session identifier cache.

    Parameters:
    ctx [In] The SSL_CTX reference.
    remove_session_cb [In] A pointer to external cache callback function for the remove action.
    See also:
    SSL_CTX_sess_get_remove_cb().

    long SSL_CTX_set_max_rsa_e_size (  SSL_CTX *    ssl_ctx,
    unsigned long    size
    )  ;
     

    Allows the server to set the maximum size of the client certificate public key exponent. The length is specified in numbers of bits.

    Parameters:
    ssl_ctx [In, Out] The SSL_CTX reference.
    size [In] The maximum size of the RSA public key exponent.
    Returns:
    1 indicates success.
    0 indicates error.
    note.gif
    This function enables the server to prevent denial of service as a result of the client passing very large keys.
    See also:
    SSL_CTX_set_max_rsa_n_size().

    long SSL_CTX_set_max_rsa_n_size (  SSL_CTX *    ssl_ctx,
    unsigned long    size
    )  ;
     

    Allows the server to set the maximum size of the client certificate public key modulus. The length is specified in numbers of bits.

    Parameters:
    ssl_ctx [In, Out] The SSL_CTX reference.
    size [In] The maximum size of the RSA public key modulus.
    Returns:
    1 indicates success.
    0 indicates error.
    note.gif
    This function enables the server to prevent denial of service as a result of the client passing very large keys.
    See also:
    SSL_CTX_set_max_rsa_e_size().

    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 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.

    long 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-2004 RSA Security Inc. All rights reserved. 050-001001-2600-000-000 - 2.6