	RSA BSAFE SSL-C	Security protocol components for C
		Search

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
unsigned long	SSL_SESSION_hash (SSL_SESSION *sess)
	Generates a hash of the SSL_SESSION structure. More...
void	SSL_SESSION_free (SSL_SESSION *sess)
	Frees a reference to an SSL_SESSION structure. More...
void	SSL_SESSION_reference_inc (SSL_SESSION *sess)
	Increments the reference count of the session. More...
int	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...
void	SSL_copy_session (SSL to, SSL from)
	Copies the session identifier and other associated information from one SSL structure to another. More...
unsigned int	SSL_SESSION_get_session_id_length (SSL_SESSION *sess)
	Returns the length of the session identifier for the specified session. More...
unsigned char*	SSL_SESSION_get_session_id (SSL_SESSION *sess)
	Returns the session identifier for the specified session. More...
int	SSL_SESSION_print (BIO bio, SSL_SESSION sess)
	Prints information regarding the SSL_SESSION sess as ASCII text to the BIO bio. More...
int	PEM_write_bio_SSL_SESSION (BIO bio, SSL_SESSION sess)
	Writes a Privacy Enhanced Mail (PEM)-encoded ASN.1 representation for the SSL_SESSION sess to the BIO bio. More...
SSL_SESSION*	PEM_read_bio_SSL_SESSION (BIO bio, SSL_SESSION sess, PEM_PASSWORD_CB_T callback)
	Reads a Privacy Enhanced Mail (PEM)-encoded ASN.1 representation of the SSL_SESSION sess from the BIO bio. More...
int	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*	PEM_read_SSL_SESSION (FILE fp, SSL_SESSION sess, PEM_PASSWORD_CB_T callback)
	Reads the Privacy Enhanced Mail (PEM) ASN.1 encoded representation of an SSL_SESSION sess from the file fp. More...
int	PEM_write_SSL_SESSION (FILE fp, SSL_SESSION sess)
	Writes a Privacy Enhanced Mail (PEM) encoded ASN.1 representation of the SSL_SESSION sess to the file fp. More...
SSL_SESSION*	SSL_get_session (SSL *ssl)
	Returns a reference to the SSL_SESSION structure of the ssl. More...

Function Documentation

SSL_SESSION* PEM_read_bio_SSL_SESSION ( BIO * bio,

SSL_SESSION ** sess,

PEM_PASSWORD_CB_T * callback

) ;

Reads a Privacy Enhanced Mail (PEM)-encoded ASN.1 representation of the SSL_SESSION sess from the BIO bio. This is used for sharing sessions between applications or reloading an SSL_SESSION.
Parameters:

bio [In] A BIO reference to the file where the SSL_SESSION details are stored.

sess [Out] A pointer to the SSL_SESSION reference where the session will be loaded (optional).

callback [In] The password callback function. If the data is encrypted and the callback is NULL, the default internal password callback will prompt the user for a password. callback can be used to override this behavior and supply a password via other means.

Returns:
An SSL_SESSION reference if successfully loaded.
NULL indicates error.

If sess refers to an existing SSL_SESSION structure, the session is placed in this structure. Otherwise memory for a SSL_SESSION is allocated. If memory is allocated it will be explicitly freed.

SSL_SESSION* PEM_read_SSL_SESSION ( FILE * fp,

SSL_SESSION ** sess,

PEM_PASSWORD_CB_T * callback

) ;

Reads the Privacy Enhanced Mail (PEM) ASN.1 encoded representation of an SSL_SESSION sess from the file fp. This is used for sharing sessions between applications or reloading an old SSL_SESSION.
Parameters:

fp [In] A reference to the file where the SSL_SESSION details are stored.

sess [Out] A pointer to the SSL_SESSION reference where the session will be loaded (optional).

callback [In] The password callback function. If the data is encrypted and the callback is NULL, the default internal password callback will prompt the user for a password. callback can be used to override this behavior and supply a password via other means.

Returns:
An SSL_SESSION reference indicates success.
NULL indicates error.

If sess refers to an existing SSL_SESSION structure, the session is placed in this structure. Otherwise memory for a SSL_SESSION is allocated. If memory is allocated it will be explicitly freed.

int PEM_write_bio_SSL_SESSION ( BIO * bio,

SSL_SESSION * sess

) ;

Writes a Privacy Enhanced Mail (PEM)-encoded ASN.1 representation for the SSL_SESSION sess to the BIO bio. This is used for sharing sessions between applications or for storage of an SSL_SESSION so that it can be reloaded at a later time.
Parameters:

bio [In] A BIO reference to the file where the session information is to be stored.

sess [In] A reference to the SSL_SESSION to write to the file.

Returns:
1 indicates success.
<= 0 indicates error.
See also:
PEM_read_bio_SSL_SESSION().

int PEM_write_SSL_SESSION ( FILE * fp,

SSL_SESSION * sess

) ;

Writes a Privacy Enhanced Mail (PEM) encoded ASN.1 representation of the SSL_SESSION sess to the file fp. This is used for sharing sessions between applications or for storage of an SSL_SESSION so that it can be reloaded at a later time.
Parameters:

fp [In] A reference to the file where the session information is to be stored.

sess [In] A reference to the SSL_SESSION to write to the file.

Returns:
1 indicates success.
<= 0 indicates error.
See also:
PEM_read_SSL_SESSION().

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

If there is an existing session set against to, the session is freed.
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 of the ssl. This structure holds information negotiated during the SSL handshake and can be reused in subsequent negotiations to reduce SSL connection times.
Parameters:

ssl [In] The SSL structure.

Returns:
A pointer to SSL_SESSION if a connection has been established.
NULL indicates otherwise.

void 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_new() and SSL_SESSION_reference_inc().
Samples:
app_cache.c.

unsigned char* 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 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.

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

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

The BIO used must have the puts method available (that is, it cannot be a socket BIO).
See also:
SSL_SESSION_print_fp().

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

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

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

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.