	RSA BSAFE Micro Edition Suite	Streamlined security for mobile and embedded devices

Management Functions

This section details the functions used to manipulate the SSL structure.

Typedefs
typedef int	SSL_INFO
	The type of information identifiers of an SSL_CTX structure. More...
Functions
SSL* R_CDECL	SSL_new (SSL_CTX *ctx)
	Creates a new SSL structure and initializes the state engine to request a handshake for the SSL_CTX ctx. More...
int R_CDECL	SSL_clear (SSL *ssl)
	Resets all parameters of the SSL structure ssl to their initial state (that is, returns to state 0). More...
void R_CDECL	SSL_free (SSL *ssl)
	Removes all allocated states for the SSL connection ssl. More...
SSL* R_CDECL	SSL_dup (SSL *ssl)
	Duplicates an SSL structure and its associated data. More...
int	SSL_feature_set (long feature)
	Sets a feature for the library. More...
int	SSL_feature_clear (long feature)
	Clears the library feature which disables functionality at run time. More...
int	SSL_feature_test (long feature)
	Tests for the specified library feature in the current library setup. More...
int	SSL_feature_reset ()
	Clears all library feature settings for the library (that is, functionality that is controlled by feature settings will be available). More...
SSL_CTX *	SSL_get_SSL_CTX (SSL *ssl)
	Returns a reference to the SSL_CTX structure by directly accessing the SSL structure. More...
long R_CDECL	SSL_set_options (SSL *ssl, long op)
	Specifies various options related to the functioning of the SSL protocol. More...
long R_CDECL	SSL_get_options (SSL *ssl)
	Returns various options related to the functioning of the SSL protocol. More...

Typedef Documentation

typedef int SSL_INFO

The type of information identifiers of an SSL_CTX structure. See SSL Context Information Types for more information.

Function Documentation

int R_CDECL SSL_clear ( SSL * ssl ) ;

Resets all parameters of the SSL structure ssl to their initial state (that is, returns to state 0).
Parameters:

ssl [In] The SSL connection reference to clear.
Must be a valid reference.

Returns:
1 indicates success.
0 indicates failure.

After the structure is cleared, it may be re-used. This avoids the overheads for creating a new SSL structure for each new connection.
This function does not perform a shutdown operation. The shutdown must be explicitly called via SSL_shutdown().

There may be an error message on the error stack if the function fails.

See also:
SSL_free().
Samples:
cache_server.c, p7ssl_server.c, sock_server.c, and ssl_server.c.

SSL* R_CDECL SSL_dup ( SSL * ssl ) ;

Duplicates an SSL structure and its associated data. The BIOs of ssl are not duplicated and new BIOs must be set against the newly created SSL. The duplicate must perform a handshake before it is able to read data since the encryption/decryption fields are empty.
It will not have enough data to continue a partly completed handshake so duplication of an SSL that is part-way through a handshake should not be attempted as it will leave the new SSL in a handshake state that cannot be resumed.
If ssl has valid session data then the session data will be copied and this will allow a client-side duplicate to attempt session reuse. It will not affect a server-side connection since session data will be removed during the handshake.
Parameters:

ssl [In] The SSL structure to duplicate.

Returns:
The duplicate SSL structure.
See also:
SSL_new() and SSL_set_bio().

int SSL_feature_clear ( long feature ) ;

Clears the library feature which disables functionality at run time.
Parameters:

feature [In] The feature to disable.
See Run Time Controlled Features for a list of valid values.

Returns:
1 indicates success.
<= 0 indicates error.
See also:
SSL_feature_set(), SSL_feature_reset() and SSL_feature_test().

int SSL_feature_reset ( ) ;

Clears all library feature settings for the library (that is, functionality that is controlled by feature settings will be available).
Returns:
1 indicates success.

Library initialization will set some features.
See also:
SSL_feature_set(), SSL_feature_clear() and SSL_feature_test().

int SSL_feature_set ( long feature ) ;

Sets a feature for the library. A feature is an underlying piece of functionality of the library. Access to features is controlled at run time, with some features set by default during library initialization.
Parameters:

feature [In] The feature to enable.
See Run Time Controlled Features for a list of valid values.

Returns:
1 indicates success.
<= 0 indicates error.
See also:
SSL_feature_clear(), SSL_feature_reset() and SSL_feature_test().

int SSL_feature_test ( long feature ) ;

Tests for the specified library feature in the current library setup.
Parameters:

feature [In] The feature to test.
See Run Time Controlled Features for a list of valid values.

Returns:
0 indicates the feature is disabled (that is, unavailable).
Otherwise, indicates the feature is enabled.
See also:
SSL_feature_set(), SSL_feature_clear() and SSL_feature_reset().

void R_CDECL SSL_free ( SSL * ssl ) ;

Removes all allocated states for the SSL connection ssl. This function also calls SSL_shutdown() if it has not already been called, thereby closing the socket.
Parameters:

ssl [In] The SSL connection reference to free.

For each SSL_new(), a matching SSL_free() should be performed. If SSL_free() is not called, memory leaks may occur.
See also:
SSL_new().
Samples:
cache_server.c, p7ssl_client.c, p7ssl_server.c, simple.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

long R_CDECL SSL_get_options ( SSL * ssl ) ;

Returns various options related to the functioning of the SSL protocol. It is mostly used to enable bug compatibility with other SSL implementations.
Parameters:

ssl [In] The SSL reference.
See Option Codes for valid values.

Returns:
The current options set against the SSL.
See also:
SSL_set_options().

SSL_CTX * SSL_get_SSL_CTX ( SSL * ssl ) ;

Returns a reference to the SSL_CTX structure by directly accessing the SSL structure. The SSL structure inherits default values from the SSL_CTX during initialization.
Parameters:

ssl [In] The SSL connection reference from which to retrieve the context reference.

Returns:
A pointer to the SSL_CTX structure, containing the default settings used to initialize the ssl.
See also:
SSL_new().

SSL* R_CDECL SSL_new ( SSL_CTX * ctx ) ;

Creates a new SSL structure and initializes the state engine to request a handshake for the SSL_CTX ctx.
Parameters:

ctx [In] The SSL_CTX that holds the SSL definitions.
Must be a valid SSL_CTX reference that has an SSL method.

Returns:
A new SSL structure.
NULL indicates error.

A context data structure must be created and initialized before an SSL connection can be used.

In most cases when the function fails an error will be written to the error stack.

See also:
SSL_CTX_new() for further information on creating an SSL_CTX.
Samples:
cache_server.c, p7ssl_client.c, p7ssl_server.c, simple.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

long R_CDECL SSL_set_options ( SSL * ssl,

long larg

) ;

Specifies various options related to the functioning of the SSL protocol. Enables bug compatibility with other SSL implementations.
Parameters:

ssl [In] The SSL reference against which to set the options.

larg [In] The bitmask of options to enable.
See Option Codes for valid values.

Returns:
The current options (including the options just set).
See also:
SSL_get_options().
Samples:
p7ssl_server.c, sock_server.c, and ssl_server.c.

Management Functions

Typedefs

Functions

Typedef Documentation

Function Documentation