	RSA BSAFE SSL-C	Security protocol components for C
		Search

SSL Context Functions

This section describes the functions used to support the SSL_CTX structure.

Typedefs
typedef int	SSL_CTX_INFO
	The type of information identifiers of SSL_CTX structure. More...
Functions
SSL_CTX*	SSL_CTX_new (SSL_METHOD *meth)
	Creates a new context structure using the SSL_METHOD reference and initializes the default values. More...
void	SSL_CTX_free (SSL_CTX *ctx)
	Deallocates the memory and frees the state information for the SSL_CTX structure passed in. More...
int	SSL_CTX_set_cipher_list (SSL_CTX ctx, char str)
	Specifies the cipher suites and order for the SSL_CTX ctx. More...
int	SSL_CTX_set_info (SSL_CTX ssl_ctx, SSL_CTX_INFO info_id, void value)
	Sets the information into an SSL_CTX structure. More...
int	SSL_CTX_get_info (SSL_CTX ssl_ctx, SSL_CTX_INFO info_id, void value)
	Retrieves the information from an SSL_CTX structure. More...
int	SSL_CTX_set_R_LIB_CTX (SSL_CTX ssl_ctx, R_LIB_CTX lib_ctx, int mode)
	Sets the library context against the SSL_CTX structure. More...
long	SSL_CTX_set_rsa_blinding_mode (SSL_CTX *ctx, int mode)
	Sets the blinding mode for all the loaded RSA keys. More...
void	SSL_CTX_set_default_passwd_cb (SSL_CTX ctx, PEM_PASSWORD_CB_T cb)
	Sets the callback used to specify the default password for reading data from Privacy Enhanced Mail (PEM) encoded files that are password protected. More...
int	SSL_CTX_set_ex_data (SSL_CTX ssl, int idx, char data)
	Allows additional information to be stored against the SSL. More...
char*	SSL_CTX_get_ex_data (SSL_CTX *ssl, int idx)
	Retrieves the extra data set against index idx from the SSL_CTX. More...
int	SSL_CTX_get_ex_new_index (long argl, char argp, SSL_EX_DATA_NEW_CB_T new_func, SSL_EX_DATA_DUP_CB_T dup_func, SSL_EX_DATA_FREE_CB_T free_func)
	Returns an index used to manage extra data. More...
long	SSL_CTX_set_options (SSL_CTX *ctx, long op)
	Specifies options related to the functioning of the SSL protocol. More...
long	SSL_CTX_get_options (SSL_CTX *ctx)
	Returns options related to the functioning of the SSL protocol. More...

Typedef Documentation

typedef int SSL_CTX_INFO

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

Function Documentation

void SSL_CTX_free ( SSL_CTX * ctx ) ;

Deallocates the memory and frees the state information for the SSL_CTX structure passed in.
Parameters:

ctx [In] The SSL_CTX structure to free.

The SSL_CTX structure uses reference counts to ensure the structure is only deallocated when there are no SSL structures referencing the structure. If SSL structures are using the SSL_CTX, it will not be freed by SSL_CTX_free(). It is only freed when the last SSL structure is freed.
Samples:
bio_client.c, bio_server.c, cache_server.c, fips_client.c, nbio_client.c, nbio_server.c, PKCS11Client.c, simple.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

char* SSL_CTX_get_ex_data ( SSL_CTX * ssl_ctx,

int idx

) ;

Retrieves the extra data set against index idx from the SSL_CTX.
Parameters:

ssl_ctx [In] The SSL_CTX reference from which to retrieve the data.

idx [In] An index of the extra data to be retrieved (multiple items can be stored against the SSL_CTX).

Returns:
A reference to the requested extra data.
NULL indicates error.
See also:
SSL_CTX_set_ex_data() and SSL_CTX_get_ex_new_index().

int SSL_CTX_get_ex_new_index ( long argl,

char * argp,

SSL_EX_DATA_NEW_CB_T * new_func,

SSL_EX_DATA_DUP_CB_T * dup_func,

SSL_EX_DATA_FREE_CB_T * free_func

) ;

Returns an index used to manage extra data. This function also allows user-defined callbacks to be specified that modify the default program behavior when adding, removing and duplicating extra data.
Parameters:

argl [In] A user-defined long argument that can be accessed from inside the callback functions. It may be zero.

argp [In] A user-defined pointer argument that can be accessed from inside the callback functions. It may be NULL.

new_func [In] A user-defined callback invoked when extra data container is created. It may be NULL.

dup_func [In] A user-defined callback invoked when extra data container is duplicated. It may be NULL.

free_func [In] A user-defined callback invoked when extra data container is freed. It may be NULL.

Returns:
An index that can be used for setting extra data against the SSL_CTX.
<= 0 indicates error.
See also:
SSL_CTX_get_ex_data() and SSL_CTX_set_ex_data().

int SSL_CTX_get_info ( SSL_CTX * ssl_ctx,

SSL_CTX_INFO info_id,

void * value

) ;

Retrieves the information from an SSL_CTX structure.
Parameters:

ssl_ctx [In] The SSL_CTX against which to retrieve the information.

info_id [In] The information identifier.
See SSL Context Information Types for valid values and the data type of the information specified in value.

value [Out] The information data to return.

Returns:
R_ERROR_NONE indicates success.
See Error Management Identifiers for valid values.

long SSL_CTX_get_options ( SSL_CTX * ctx ) ;

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

ctx [In] The SSL_CTX reference where the options have been set.
See Option Codes for valid values.

Returns:
The current options set against the SSL_CTX.
See also:
SSL_CTX_set_options().

SSL_CTX* SSL_CTX_new ( SSL_METHOD * meth ) ;

Creates a new context structure using the SSL_METHOD reference and initializes the default values. The default values may be overridden for the individual SSL structures set against the SSL_CTX structure. An SSL_CTX is needed to create SSL structures.
Parameters:

meth [In] The SSL protocol method used to initialize the SSL_CTX reference.

Returns:
A new SSL_CTX structure used to initialize the default values for the SSL connection.
NULL indicates error.

Memory is allocated for the SSL_CTX. Errors may be on the error stack if the function fails.
See also:
SSL_CTX_free().
Samples:
bio_client.c, bio_server.c, cache_server.c, fips_client.c, nbio_client.c, nbio_server.c, PKCS11Client.c, simple.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

int SSL_CTX_set_cipher_list ( SSL_CTX * ctx,

char * str

) ;

Specifies the cipher suites and order for the SSL_CTX ctx. The list of ciphers is passed in str.
Parameters:

ctx [In, Out] The SSL_CTX reference against which the default cipher list is set.

str [In] The list of cipher names to load.

Returns:
1 indicates success.
0 indicates error.

This function ignores any unrecognized cipher names. No error is displayed indicating the cipher was ignored. Any SSL cipher suites that are dependent on ciphers/digests not loaded via SSLC_library_new() are not be available.
The most common settings are:

Setting Description

EXP Only supports export ciphers. Export ciphers have up to 56-bit symmetric ciphers and 1024-bit public keys.

ALL:!EXP Only supports strong (non-export) ciphers. Export ciphers have up to 56-bit symmetric ciphers and 1024-bit public keys.

A full list of cipher suites is available via the sslc ciphers utility.
Refer to Cipher List Formatting Rules in the Utilities Guide for further information.

When operating in FIPS 140-enabled mode, no error is displayed while setting a non-FIPS 140 cipher suite. However, non-FIPS cipher suites are ignored during the handshake and an error displayed indicating there are no ciphers shared with the peer.

See also:
SSL_set_cipher_list().
Samples:
bio_client.c, bio_server.c, cache_server.c, fips_client.c, nbio_client.c, nbio_server.c, PKCS11Client.c, simple.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

void SSL_CTX_set_default_passwd_cb ( SSL_CTX * ctx,

PEM_PASSWORD_CB_T * cb

) ;

Sets the callback used to specify the default password for reading data from Privacy Enhanced Mail (PEM) encoded files that are password protected.
Parameters:

ctx [In] The SSL_CTX reference.

cb [In] The callback function.

The PEM code will use a default password function if one is not specified.
See also:
PEM_PASSWORD_CB_T.

int SSL_CTX_set_ex_data ( SSL_CTX * ssl_ctx,

int idx,

char * arg

) ;

Allows additional information to be stored against the SSL.
Parameters:

ssl_ctx [In, Out] The SSL_CTX against which to store extra data.

idx [In] The index used to access extra data (multiple items can be stored against the SSL_CTX).

arg [In] The data to be stored against the SSL_CTX at index idx.

Returns:
1 indicates success.
0 indicates error.
See also:
SSL_CTX_get_ex_data() and SSL_CTX_get_ex_new_index().

int SSL_CTX_set_info ( SSL_CTX * ssl_ctx,

SSL_CTX_INFO info_id,

void * value

) ;

Sets the information into an SSL_CTX structure.
Parameters:

ssl_ctx [In] The SSL_CTX against which to set the information.

info_id [In] The information identifier.
See SSL Context Information Types for valid values and the data type of the information specified in value.

value [In] The information data to set.

Returns:
R_ERROR_NONE indicates success.
See Error Management Identifiers for valid values.

long SSL_CTX_set_options ( SSL_CTX * ctx,

long op

) ;

Specifies options related to the functioning of the SSL protocol. This function is used to enable bug compatibility with other SSL implementations.
Parameters:

ctx [In] The SSL_CTX reference against which the options are set.

op [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_CTX_get_options() and SSL_set_options().
Samples:
bio_client.c, bio_server.c, cache_server.c, fips_client.c, nbio_client.c, nbio_server.c, PKCS11Client.c, simple.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

int SSL_CTX_set_R_LIB_CTX ( SSL_CTX * ssl_ctx,

R_LIB_CTX * lib_ctx,

int mode

) ;

Sets the library context against the SSL_CTX structure.
Parameters:

ssl_ctx [In] The SSL_CTX against which the library context is to be set.

lib_ctx [In] The library context to be set against the SSL_CTX.

mode [In] The FIPS 140 mode of library usage.
See Library FIPS 140 Mode Identifiers for valid values.

Returns:
R_ERROR_NONE indicates success.
See Error Management Identifiers for valid values.
Samples:
bio_client.c, bio_server.c, cache_server.c, fips_client.c, nbio_client.c, nbio_server.c, simple.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

long SSL_CTX_set_rsa_blinding_mode ( SSL_CTX * ctx,

int mode

) ;

Sets the blinding mode for all the loaded RSA keys. The default mode is on.
Parameters:

ctx [In, Out] The SSL_CTX reference that binds the temporary key.

mode [In] The blinding mode.
See SSL Context Blinding Modes for valid values.

Returns:
1 indicates success.
<= 0 indicates error.

SSL Context Functions

Typedefs

Functions

Typedef Documentation

Function Documentation