	RSA BSAFE SSL-C	Security protocol components for C
		Search

Temporary Key Functions

This section describes the functions which generate temporary keys.

Typedefs
typedef RSA*	SSL_TMP_RSA_CB_T (SSL *ssl, int export_type)
	A type of callback function that helps delay temporary RSA key creation. More...
typedef DH*	SSL_TMP_DH_CB_T (SSL *ssl, int export_type)
	A callback function that can be used to replace the temporary Diffie-Hellman (DH) key generation. More...
Functions
long	SSL_CTX_set_tmp_rsa (SSL_CTX ctx, RSA rsa)
	Sets an RSA key for the default key for the SSL_CTX ctx. More...
long	SSL_CTX_set_tmp_dh (SSL_CTX ctx, DH dh)
	Indicates that Diffie-Hellman (DH) parameters and ciphers should be used when creating a temporary key for the SSL_CTX ctx. More...
long	SSL_CTX_set_tmp_rsa_cb (SSL_CTX ctx, SSL_TMP_RSA_CB_T cb)
	Sets an RSA key generation callback for ctx. More...
SSL_TMP_RSA_CB_T*	SSL_CTX_get_tmp_rsa_cb (SSL_CTX *ctx)
	Returns the temporary RSA callback routine set against the SSL_CTX certificate. More...
long	SSL_CTX_set_tmp_dh_cb (SSL_CTX ctx, SSL_TMP_DH_CB_T cb)
	Delays the creation of the Diffie-Hellman (DH) key until such time as it is required by a cipher suite. More...
SSL_TMP_DH_CB_T*	SSL_CTX_get_tmp_dh_cb (SSL_CTX *ctx)
	Returns the temporary Diffie-Hellman callback routine set against the SSL_CTX certificate. More...
long	SSL_set_tmp_rsa_cb (SSL ssl, SSL_TMP_RSA_CB_T callback)
	Creates a temporary RSA key. More...
SSL_TMP_RSA_CB_T*	SSL_get_tmp_rsa_cb (SSL *ssl)
	Returns the temporary RSA callback routine set against the SSL certificate. More...
long	SSL_set_tmp_dh_cb (SSL ssl, SSL_TMP_DH_CB_T callback)
	Delays the creation of the Diffie-Hellman (DH) key until such time as it is required by a cipher suite. More...
SSL_TMP_DH_CB_T*	SSL_get_tmp_dh_cb (SSL *ssl)
	Returns the temporary Diffie-Hellman callback routine set against the SSL certificate. More...
int	SSL_CTX_set_tmp_key_mode (SSL_CTX *ctx, int type, int mode)
	This function is used to preset temporary keys or to set the builtin callbacks. More...

Typedef Documentation

typedef DH* SSL_TMP_DH_CB_T(SSL *ssl, int export_type)

A callback function that can be used to replace the temporary Diffie-Hellman (DH) key generation. This DH temporary key callback is called in the server key exchange for an EDH cipher suite when there is no existing temporary DH key already available. Unlike the SSL_TMP_RSA_CB_T callback it does not get assigned as the value to use for all future handshakes and so will generate for each handshake that requires an EDH key. The generated key must be in a DH structure.
Parameters:

ssl [In, Out] A reference to the SSL connection.

export_type [In] Informs the callback that an export size key is required.

Returns:
A reference to a new DH key.
See also:
SSL_CTX_set_tmp_dh_cb() and SSL_CTX_set_tmp_dh().

typedef RSA* SSL_TMP_RSA_CB_T(SSL *ssl, int export_type)

A type of callback function that helps delay temporary RSA key creation. This RSA callback is used by the server before a server key exchange message to generate a temporary RSA key in the case where the original server key cannot be used to encrypt the pre-master secret (export restrictions do not allow it, key was for signing only, etc). The generated key must be in the RSA key structure The callback is only run to generate the key if the handshake requires it. The server key exchange code checks for an existing temporary RSA key of the correct size before attempting to generate a new key. Once the callback runs successfully the result is assigned as the key to be used for all future handshakes of that SSL that require it. It does mean that the first handshake that requires a temporary key will take the extra time to generate the key which can be a bit of a distraction.
Parameters:

ssl [In, Out] A reference to the SSL connection.

export_type [In] Can be set to inform the callback that an export size key is required. If the flag is "1" then a 512-bit RSA must be generated. Otherwise (flag is "2"), 1024-biti RSA key must be generated.

Returns:
A reference to a new RSA key.
See also:
SSL_CTX_set_tmp_rsa_cb() and SSL_CTX_set_tmp_rsa().

Function Documentation

SSL_TMP_DH_CB_T* SSL_CTX_get_tmp_dh_cb ( SSL_CTX * ctx ) ;

Returns the temporary Diffie-Hellman callback routine set against the SSL_CTX certificate.
Parameters:

ctx [In] A reference to the SSL_CTX where the certificate is stored.

Returns:
A reference to the callback function.
NULL indicates no callback has been set.
See also:
SSL_CTX_set_tmp_dh_cb() and SSL_TMP_DH_CB_T.

SSL_TMP_RSA_CB_T* SSL_CTX_get_tmp_rsa_cb ( SSL_CTX * ctx ) ;

Returns the temporary RSA callback routine set against the SSL_CTX certificate.
Parameters:

ctx [In] A reference to the SSL_CTX where the certificate is stored.

Returns:
A reference to the callback function.
NULL indicates no callback has been set.
See also:
SSL_CTX_set_tmp_rsa_cb() and SSL_TMP_RSA_CB_T.

long SSL_CTX_set_tmp_dh ( SSL_CTX * ctx,

DH * dh

) ;

Indicates that Diffie-Hellman (DH) parameters and ciphers should be used when creating a temporary key for the SSL_CTX ctx. If SSL_CTX_set_tmp_dh() is not called, the ephemeral DH ciphers will not be available. The DH structure stores DH parameters and the public and private key.
Parameters:

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

dh [In] The DH structure reference where the temporary DH key is stored.

Returns:
1 indicates success.
<= 0 indicates error.
See also:
SSL_CTX_set_tmp_dh_cb() and SSL_CTX_set_tmp_key_mode().

long SSL_CTX_set_tmp_dh_cb ( SSL_CTX * ctx,

SSL_TMP_DH_CB_T * cb

) ;

Delays the creation of the Diffie-Hellman (DH) key until such time as it is required by a cipher suite.
Parameters:

ctx [In, Out] The SSL_CTX reference where the temporary key callback is loaded.

cb [In] A reference to the temporary DH callback function.

Returns:
1 indicates success.
<= 0 indicates error.
See also:
SSL_CTX_set_tmp_dh() and SSL_TMP_DH_CB_T.

int SSL_CTX_set_tmp_key_mode ( SSL_CTX * ctx,

int type,

int mode

) ;

This function is used to preset temporary keys or to set the builtin callbacks.
Parameters:

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

type [In] The key type. One of:

SSL_TMP_512_DH Used for export mode or normal Diffie-Hellman.

SSL_TMP_512_RSA May require generation of a temporary RSA key. As this is an expensive operation a key mode of SSL_TMP_GENERATE_NOW or SSL_TMP_GENERATE_LATER may be specified.

SSL_TMP_1024_DH or SSL_TMP_2048_DH Used for non-export Diffie-Hellman. Select only one of these options.

SSL_TMP_1024_RSA May require generation of a temporary RSA key. As this is an expensive operation a key mode of SSL_TMP_GENERATE_NOW or SSL_TMP_GENERATE_LATER may be specified.

Parameters:

mode [In] The RSA key generation mode. One of:

SSL_TMP_GENERATE_LATER Generates the key the first time it is required.

SSL_TMP_GENERATE_NOW Generates the temporary RSA key immediately.

Returns:
1 indicates success.
0 indicates error.

Subsequent calls to this function will incur the RSA key generation overhead.
Samples:
bio_server.c, nbio_server.c, sock_server.c, and ssl_server.c.

long SSL_CTX_set_tmp_rsa ( SSL_CTX * ctx,

RSA * rsa

) ;

Sets an RSA key for the default key for the SSL_CTX ctx. The standard requires the creation of a temporary 512-bit RSA key when using export ciphers and the certificate's private key is greater than 512 bits.
Parameters:

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

rsa [In] The RSA reference where the temporary RSA key is stored.

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

This function is only required on the server side of the SSL protocol.
See also:
SSL_CTX_set_tmp_rsa_cb() and SSL_CTX_set_tmp_key_mode().

long SSL_CTX_set_tmp_rsa_cb ( SSL_CTX * ctx,

SSL_TMP_RSA_CB_T * cb

) ;

Sets an RSA key generation callback for ctx. The standard requires the creation of a temporary 512-bit RSA key when using export ciphers and where the certificate's private key is greater than 512-bits. Creating a temporary RSA key is an expensive CPU operation and is not required by certain cipher suites. The callback delays the creation of the RSA key until such time as it is actually required.
Parameters:

ctx [In] The SSL_CTX against which to set the temporary key generation callback.

cb [In] The callback function.

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

This function is only required on the server side of the SSL protocol.
See also:
SSL_CTX_set_tmp_rsa() and SSL_TMP_RSA_CB_T.

SSL_TMP_DH_CB_T* SSL_get_tmp_dh_cb ( SSL * ssl ) ;

Returns the temporary Diffie-Hellman callback routine set against the SSL certificate.
Parameters:

ssl [In] A reference to the SSL where the certificate is stored.

Returns:
A reference to the callback function.
NULL indicates no callback has been set.
See also:
SSL_set_tmp_dh_cb(), SSL_TMP_DH_CB_T and SSL_use_certificate().

SSL_TMP_RSA_CB_T* SSL_get_tmp_rsa_cb ( SSL * ssl ) ;

Returns the temporary RSA callback routine set against the SSL certificate.
Parameters:

ssl [In] A reference to the SSL where the certificate is stored.

Returns:
A reference to the callback function.
NULL indicates no callback has been set.
See also:
SSL_set_tmp_rsa_cb(), SSL_TMP_RSA_CB_T and SSL_use_certificate().

long SSL_set_tmp_dh_cb ( SSL * ssl,

SSL_TMP_DH_CB_T * callback

) ;

Delays the creation of the Diffie-Hellman (DH) key until such time as it is required by a cipher suite.
Parameters:

ssl [In, Out] The SSL reference where the temporary key callback is loaded.

callback [In] A reference to a temporary DH callback function.

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

This function only succeeds if the SSL has its own certificate and is not using the default SSL_CTX certificate.
See also:
SSL_CTX_set_tmp_dh() and SSL_TMP_DH_CB_T.

long SSL_set_tmp_rsa_cb ( SSL * ssl,

SSL_TMP_RSA_CB_T * callback

) ;

Creates a temporary RSA key. Creating a temporary RSA key is an expensive CPU operation and is not required by certain cipher suites. The callback is used to delay the creation of the RSA key until such time as it is actually required. Therefore the program has a faster startup time and the creation operation is not used unless required.
Parameters:

ssl [In, Out] The SSL connection reference where the temporary key callback is loaded.

callback [In] A reference to the temporary RSA callback function.

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

This function only succeeds if the SSL has its own certificate and is not using the default SSL_CTX certificate.
See also:
SSL_set_tmp_dh_cb() and SSL_TMP_RSA_CB_T.

Temporary Key Functions

Typedefs

Functions

Typedef Documentation

Function Documentation