RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

Session Structure Functions

This section details the functions that facilitate the management of the session structure. SSL_SESSION contains state information for the encryption associated with a connection.

Functions

SSL_SESSION* R_CDECL SSL_SESSION_new (void)
 Creates a new SSL_SESSION structure. More...

unsigned long R_CDECL SSL_SESSION_hash (SSL_SESSION *sess)
 Generates a hash of the SSL_SESSION structure. More...

int R_CDECL SSL_SESSION_cmp (SSL_SESSION *sessa, SSL_SESSION *sessb)
 Compares the session identifiers of a pair of sessions. More...

void R_CDECL SSL_SESSION_free (SSL_SESSION *sess)
 Frees a reference to an SSL_SESSION structure. More...

void R_CDECL SSL_SESSION_reference_inc (SSL_SESSION *sess)
 Increments the reference count of the session. More...

int R_CDECL SSL_set_session (SSL *ssl, SSL_SESSION *sess)
 Copies the session identifier information from the SSL_SESSION structure session to the SSL structure ssl. More...

R_TIME_T* R_CDECL SSL_SESSION_get_time (SSL_SESSION *sess, R_TIME_T *stime)
 Returns the start time of the SSL session's lifetime. More...

R_TIME_T* R_CDECL SSL_SESSION_set_time (SSL_SESSION *sess, R_TIME_T *stime)
 Sets the beginning time of the SSL session's lifetime. More...

long R_CDECL SSL_SESSION_get_timeout (SSL_SESSION *sess)
 Returns the lifetime of the session in seconds. More...

long R_CDECL SSL_SESSION_set_timeout (SSL_SESSION *sess, long tmout)
 Sets a new lifetime for the session in seconds. More...

void R_CDECL SSL_copy_session (SSL *to, SSL *from)
 Copies the session identifier and other associated information from one SSL structure to another. More...

SSLCERT* R_CDECL SSL_SESSION_get_peer_certificate (SSL_SESSION *sess)
 Returns the peer certificate associated with session passed in at SSL_SESSION sess. More...

int R_CDECL SSL_SESSION_get_master_key_length (SSL_SESSION *sess)
 Returns the length of the master key associated with session passed in at sess. More...

unsigned char* R_CDECL SSL_SESSION_get_master_key (SSL_SESSION *sess)
 Returns the master key associated with the session passed in at sess. More...

unsigned int R_CDECL SSL_SESSION_get_session_id_length (SSL_SESSION *sess)
 Returns the length of the session identifier for the specified session. More...

unsigned char* R_CDECL SSL_SESSION_get_session_id (SSL_SESSION *sess)
 Returns the session identifier for the specified session. More...

int R_CDECL SSL_SESSION_set_not_reusable (SSL_SESSION *sess)
 Sets the status of an SSL_SESSION to prevent the session from being reused in new connections. More...

int R_CDECL SSL_SESSION_get_not_reusable (SSL_SESSION *sess)
 Retrieves a flag that indicates if the SSL session is not allowed to be reused. More...

int R_CDECL SSL_SESSION_print (BIO *bio, SSL_SESSION *sess)
 Prints information regarding the SSL_SESSION sess as ASCII text to the BIO bio. More...

int R_CDECL SSL_SESSION_print_fp (FILE *fp, SSL_SESSION *sess)
 Prints information regarding the SSL_SESSION structure sess as ASCII text to the file fp. More...

SSL_SESSION * SSL_get_session (SSL *ssl)
 Returns a reference to the SSL_SESSION structure by directly accessing the SSL structure. More...

Function Documentation

void R_CDECL SSL_copy_session (  SSL *    to,
SSL *    from
)  ;
 

Copies the session identifier and other associated information from one SSL structure to another. The associated information includes:

  • SSL method functions.
  • Authentication data (such as local public key and authenticating certificate chain).
  • Session identifier context data.
    Parameters:
    to [In, Out] The recipient of the copied session.
    from [In, Out] The source of the session to copy.
    note.gif
    If there is an existing session set against to, the session is freed.
    The copied session has its reference count incremented and must be freed by both SSL structures.

    See also:
    SSL_set_session() and BIO_ssl_copy_session().

    • SSL_SESSION * SSL_get_session (  SSL *    ssl )  ;
     

    Returns a reference to the SSL_SESSION structure by directly accessing the SSL structure. This structure holds information negotiated during the SSL handshake and can be reused in subsequent negotiations to reduce ssl connection time.

    Parameters:
    ssl [In] The SSL connection reference from which to retrieve the session.
    Returns:
    A pointer to the SSL_SESSION for the ssl if a connection has been established.
    Otherwise NULL.
    See also:
    SSL_set_session().

    int R_CDECL SSL_SESSION_cmp (  SSL_SESSION *    sessa,
    SSL_SESSION *    sessb
    )  ;
     

    Compares the session identifiers of a pair of sessions. The session identifier is a random data string which means there is no guarantee of uniqueness but accidental clashes should be rare. The session identifier details depend upon the SSL protocol version so this is also used to compare sessions.

    Parameters:
    sessa [In] An SSL_SESSION reference.
    sessb [In] An SSL_SESSION reference.
    Returns:
    0 indicates the sessions have matching session identifier values.
    Other values indicate the session identifiers differ.
    note.gif
    Both sessions should be valid SSL_SESSION structures.
    Samples:
    app_cache.c.

    void R_CDECL SSL_SESSION_free (  SSL_SESSION *    sess )  ;
     

    Frees a reference to an SSL_SESSION structure. When a reference is freed it is no longer valid but the session structure may still exist in memory if other references remain. When the final reference is removed the structure memory is freed.

    Parameters:
    sess [In] The reference to a session structure.
    See also:
    SSL_SESSION_reference_inc().
    Samples:
    app_cache.c.

    unsigned char* R_CDECL SSL_SESSION_get_master_key (  SSL_SESSION *    sess )  ;
     

    Returns the master key associated with the session passed in at sess.

    Parameters:
    sess [In] The SSL_SESSION reference from which to retrieve the master key.
    Returns:
    The session master key as a character pointer.
    See also:
    SSL_SESSION_get_master_key_length().

    int R_CDECL SSL_SESSION_get_master_key_length (  SSL_SESSION *    sess )  ;
     

    Returns the length of the master key associated with session passed in at sess.

    Parameters:
    sess [In] The SSL_SESSION reference from which to retrieve the master key length.
    Returns:
    The length of the session master key.
    See also:
    SSL_SESSION_get_master_key().

    int R_CDECL SSL_SESSION_get_not_reusable (  SSL_SESSION *    sess )  ;
     

    Retrieves a flag that indicates if the SSL session is not allowed to be reused. Valid SSL sessions can be reused for multiple connections in a shortened handshake. If a session is marked as "not resumable" then sessions that are currently open can continue but no new SSL connections can be made with the same handshake parameters. Once a session is marked this way it cannot be changed again.

    Parameters:
    sess [In] A reference to an SSL session.
    Returns:
    A flag that indicates if the session will no longer be reused for an SSL connection. One of:
  • 1 indicates the session cannot be resumed.
  • 0 indicates the session is valid for new connections.
    • See also:
    SSL_SESSION_set_not_reusable().

    SSLCERT* R_CDECL SSL_SESSION_get_peer_certificate (  SSL_SESSION *    sess )  ;
     

    Returns the peer certificate associated with session passed in at SSL_SESSION sess.

    Parameters:
    sess [In] The SSL_SESSION reference from which to retrieve the peer certificate.
    Returns:
    The peer certificate associated with sess.

    unsigned char* R_CDECL SSL_SESSION_get_session_id (  SSL_SESSION *    sess )  ;
     

    Returns the session identifier for the specified session.

    Parameters:
    sess [In] The SSL_SESSION reference from which to retrieve the identifier.
    Returns:
    The session identifier.
    See also:
    SSL_SESSION_get_session_id_length().

    unsigned int R_CDECL SSL_SESSION_get_session_id_length (  SSL_SESSION *    sess )  ;
     

    Returns the length of the session identifier for the specified session.

    Parameters:
    sess [In] The SSL_SESSION reference from which to retrieve the identifier length.
    Returns:
    The length of the session identifier.
    See also:
    SSL_SESSION_get_session_id().
    Samples:
    app_cache.c.

    R_TIME_T* R_CDECL SSL_SESSION_get_time (  SSL_SESSION *    sess,
    R_TIME_T *    stime
    )  ;
     

    Returns the start time of the SSL session's lifetime. The start of the session lifetime is set by SSL_SESSION_new() to be the current machine time.

    Parameters:
    sess [In] A reference to an SSL session.
    stime [Out] A reference to a time structure. The session start time is copied to the structure.
    Returns:
    A reference to the time structure passed to the function indicates success.
    NULL indicates otherwise.
    See also:
    SSL_SESSION_new() and SSL_SESSION_set_time().
    Samples:
    app_cache.c.

    long R_CDECL SSL_SESSION_get_timeout (  SSL_SESSION *    sess )  ;
     

    Returns the lifetime of the session in seconds. The lifetime of an SSL session defines the time period from the session's creation that it may be used to establish a connection with a peer that shares the same session data.

    Parameters:
    sess [In] A reference to an SSL session.
    Returns:
    The session validity period in seconds.
    0 indicates the session is invalid.
    See also:
    SSL_SESSION_set_timeout().
    Samples:
    app_cache.c.

    unsigned long R_CDECL SSL_SESSION_hash (  SSL_SESSION *    sess )  ;
     

    Generates a hash of the SSL_SESSION structure.

    Parameters:
    sess [In] The SSL_SESSION reference from which to generate the hash.
    Returns:
    The session hash.

    SSL_SESSION* R_CDECL SSL_SESSION_new (    )  ;
     

    Creates a new SSL_SESSION structure. SSL_SESSION contains the data that defines a successful SSL connection that may be reused for subsequent connection attempts. Some of this data is secret to the connection parties and should not be broadcast.

    Returns:
    A reference to a session structure or NULL if there is an error condition. When a session reference is returned, memory has been allocated by the function and the structure should be freed by the caller.
    note.gif
    If this function returns on an error condition the error stack will contain an error message.
    See also:
    SSL_SESSION_free() and ERR_print_errors().

    int R_CDECL SSL_SESSION_print (  BIO *    bio,
    SSL_SESSION *    sess
    )  ;
     

    Prints information regarding the SSL_SESSION sess as ASCII text to the BIO bio. The information includes a start time value (in seconds since Jan 1, 1970).

    Parameters:
    bio [In] The BIO reference to which the session details are written.
    sess [In] The SSL_SESSION reference details which are written.
    Returns:
    1 indicates success.
    0 indicates an error or that SSL_SESSION is NULL.
    note.gif
    The BIO used must have the puts method available (that is, it cannot be a socket BIO).
    See also:
    SSL_SESSION_print_fp().

    int R_CDECL SSL_SESSION_print_fp (  FILE *    fp,
    SSL_SESSION *    sess
    )  ;
     

    Prints information regarding the SSL_SESSION structure sess as ASCII text to the file fp.

    Parameters:
    fp [In] The FILE reference to print session information to.
    sess [In] The SSL_SESSION reference from which to print session information.
    Returns:
    1 indicates success.
    0 indicates error.
    note.gif
    The file must be open for writing. The file pointer is not affected by the function (that is, the file is not closed).
    See also:
    SSL_SESSION_hash().
    Example:

    FILE *fp;

/* Open file for writing */
fp = fopen("C:\output.sess", "w");

if (SSL_SESSION_print_fp(fp, sess)==0)
{
    /* Failed to output text - perform error processing */
}

/* Close the file */
fclose(fp);

    void R_CDECL SSL_SESSION_reference_inc (  SSL_SESSION *    sess )  ;
     

    Increments the reference count of the session. SSL sessions may be used by several program structures simultaneously and these references are tracked via the reference count. In multithreaded environments a locking function should be set to ensure that references are incremented safely. A reference to a session is removed via SSL_SESSION_free().

    Parameters:
    sess [In] The SSL_SESSION reference to the session where reference count is incremented.
    Must be a valid session reference.
    note.gif
    The SSL_SESSIONs should subsequently be destroyed via SSL_SESSION_free().
    See also:
    SSL_SESSION_free() and R_lock_set_cb().
    Samples:
    app_cache.c.

    int R_CDECL SSL_SESSION_set_not_reusable (  SSL_SESSION *    sess )  ;
     

    Sets the status of an SSL_SESSION to prevent the session from being reused in new connections. Valid SSL_SESSIONs can be reused for multiple connections in a shortened handshake. If a session is marked as 'not resumable' then sessions that are currently open can continue but no new SSL connections can be made with the same handshake parameters. Once a session is marked this way it cannot be changed again.

    Parameters:
    sess [In] A reference to an SSL session.
    Must be a valid SSL Session reference.
    Returns:
    1 indicates the flag setting was successful.
    note.gif
    This function always returns 1.
    See also:
    SSL_SESSION_get_not_reusable().
    Samples:
    app_cache.c.

    R_TIME_T* R_CDECL SSL_SESSION_set_time (  SSL_SESSION *    sess,
    R_TIME_T *    stime
    )  ;
     

    Sets the beginning time of the SSL session's lifetime. The start of the session lifetime is set by SSL_SESSION_new() to be the current machine time. This function can be used to reset that start time if the session is not established immediately.

    Parameters:
    sess [In] A reference to an SSL_SESSION.
    stime [In] A reference to a time structure that holds the new session start time.
    Returns:
    A reference to the time structure passed to the function indicates success.
    A NULL pointer indicates otherwise.
    note.gif
    The session's beginning time will be set to the time the session structure was created under the assumption that the session will be valid immediately.
    See also:
    SSL_SESSION_new() and SSL_SESSION_get_time().
    Example:

    SSL_SESSION *sess;
R_TIME_T t, *t1;

/* Create the session - creation time set */
sess = SSL_SESSION_new();

/* Processing ... */

/* Get the current time - must be important */
if (R_time(&t) == NULL) 
{
        /* Error condition */
        exit(0);
}

/* Reset the SSL SESSION creation time to the important time */
t1 = SSL_SESSION_set_time(sess, &t);
if (t1 == NULL)
{
        /* Failed to reset the session's creation time */
        exit (0);
}

    long R_CDECL SSL_SESSION_set_timeout (  SSL_SESSION *    sess,
    long    tmout
    )  ;
     

    Sets a new lifetime for the session in seconds. The lifetime of an SSL_SESSION defines the time period from the session's creation that it may be used to establish a connection with a peer that shares the same session data. Setting a new lifetime does not affect the creation time of the session.

    Parameters:
    sess [In] A reference to an SSL_SESSION.
    tmout [In] The new timeout period. Must be a positive value.
    Returns:
    1 indicates the new timeout period is set.
    0 indicates the session is invalid.
    note.gif
    The recommended timeout periods for session data by the different protocol specifications, and this library's default settings are shown here.
    Protocol Recommended timeout periods Default Library Settings
    SSLv2 100 seconds 300 seconds
    SSLv3 and TLSv1 <= 86400 seconds 7200 seconds
    See also:
    SSL_SESSION_get_timeout().

    int R_CDECL SSL_set_session (  SSL *    ssl,
    SSL_SESSION *    session
    )  ;
     

    Copies the session identifier information from the SSL_SESSION structure session to the SSL structure ssl.

    Parameters:
    ssl [In] The SSL connection reference against which to set the session.
    session [In] The SSL_SESSION reference to set (or NULL to clear the session).
    Returns:
    1 indicates success.
    0 indicates error.
    note.gif
    Any existing sessions set against the SSL structure are freed. The reference count on the session is incremented.
    See also:
    SSL_get_session() and SSL_copy_session().
    Samples:
    cache_server.c.

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