	RSA BSAFE SSL-C	Security protocol components for C
		Search

Private Key Functions

This section describes the functions which manage private keys.

Functions
int	SSL_CTX_use_RSAPrivateKey (SSL_CTX ctx, RSA rsa)
	Duplicates and loads the RSA private key rsa into the SSL_CTX ctx. More...
int	SSL_CTX_use_RSAPrivateKey_ASN1 (SSL_CTX ctx, unsigned char d, long len)
	Loads an RSA private key in ASN.1 format from a buffer into the SSL_CTX ctx. More...
int	SSL_CTX_use_PrivateKey (SSL_CTX ctx, EVP_PKEY pkey)
	Duplicates and loads the private key pkey for the SSL_CTX ctx. More...
int	SSL_CTX_use_PrivateKey_ASN1 (SSL_CTX ctx, unsigned char key, long len, int type)
	Loads a private key pkey (in ASN.1 format) for the SSL_CTX ctx. More...
int	SSL_CTX_check_private_key (SSL_CTX *ctx)
	Checks that the default certificate and private key of the SSL_CTX ctx match. More...
int	SSL_use_RSAPrivateKey (SSL ssl, RSA rsa)
	Loads the RSA private key rsa for the SSL connection ssl. More...
int	SSL_use_RSAPrivateKey_ASN1 (SSL ssl, unsigned char buffer, long len)
	Loads an RSA private key in ASN.1 format from a buffer into an SSL. More...
int	SSL_use_PrivateKey (SSL ssl, EVP_PKEY pkey)
	Sets the private key pkey to be used for the SSL connection ssl. More...
int	SSL_use_PrivateKey_ASN1 (SSL ssl, unsigned char data, long len, int type)
	Sets the private key data to use for the SSL connection ssl. More...
int	SSL_check_private_key (SSL *ctx)
	Ensures the identifying certificate and the private key of an SSL match. More...
EVP_PKEY*	PEM_read_bio_PrivateKey (BIO bio, EVP_PKEY x, PEM_PASSWORD_CB_T callback)
	Reads a Privacy Enhanced Mail (PEM)-formatted private key form the BIO bio and returns a private key reference pkey. More...
int	SSL_use_RSAPrivateKey_file (SSL ssl, char file, int type)
	Loads an RSA private key from the file file for the SSL connection ssl. More...
int	SSL_use_PrivateKey_file (SSL ssl, char file, int type)
	Loads the private key stored in the file file for use with the SSL connection ssl. More...
int	SSL_CTX_use_RSAPrivateKey_file (SSL_CTX ctx, char file, int type)
	Loads an RSA private key from the file file into the SSL_CTX ctx. More...
int	SSL_CTX_use_PrivateKey_file (SSL_CTX ctx, char file, int type)
	Loads a private key from the file file to into the SSL_CTX ctx. More...
EVP_PKEY*	SSLCERT_PKEY_new (void)
	Creates a new EVP_PKEY structure. More...
void	SSLCERT_PKEY_free (EVP_PKEY *pkey)
	Removes all allocated memory for the EVP_PKEY structure pkey. More...
EVP_PKEY*	SSLCERT_PKEY_from_binary (int type, EVP_PKEY ppkey, unsigned char pp, long length)
	Creates a new EVP_PKEY structure from the private key component of the binary data specified by ppkey. More...
EVP_PKEY*	SSLCERT_PKEY_from_PUBKEY_binary (int type, EVP_PKEY ppkey, unsigned char pp, long length)
	Creates a new EVP_PKEY structure from the public key component of the binary data specified by ppkey. More...
void	SSLCERT_PKEY_reference_inc (EVP_PKEY *pkey)
	Increments the reference count for the specified EVP_PKEY structure pkey. More...

Function Documentation

EVP_PKEY* PEM_read_bio_PrivateKey ( BIO * bio,

EVP_PKEY ** pkey,

PEM_PASSWORD_CB_T * callback

) ;

Reads a Privacy Enhanced Mail (PEM)-formatted private key form the BIO bio and returns a private key reference pkey.
Parameters:

bio [In] A reference to the BIO where the key is stored.

pkey [Out] The EVP_PKEY to overwrite/create or NULL to have the function create and return a new EVP_PKEY structure.

callback [In] A callback routine to provide a passphrase if the PEM data is encrypted.
If NULL and the data is encrypted the default internal callback will prompt the user to supply a password.

Returns:
The reference to the EVP_PKEY.
NULL indicates error.

If pkey refers to an existing EVP_PKEY structure, the key is placed in the structure. Otherwise memory for an EVP_PKEY structure is allocated.

See also:
SSL_CTX_use_PrivateKey() and SSL_check_private_key().
Example:

BIO *bio; EVP_PKEY *pkey; /* Load a non-encrypted private key */ pkey=PEM_read_bio_PrivateKey(bio, NULL, NULL); /* Load an encrypted private key with a fixed passphrase */ int passphrase_cb(buffer, len, flag) char *buffer; int len; int flag; { char *passphrase="test1234"; int passphrase_len; passphrase_len = strlen(passphrase); /* Check sufficient space exists for the passphrase including * the NULL terminator in the buffer, otherwise truncate */ if (passphrase_len > (len-1)) passphrase_len = (len-1); memcpy(buf, passphrase, passphrase_len+1); /* Return the passphrase length */ return(passphrase_len); } /* Load a private key from encrypted PEM file */ pkey = PEM_read_bio_PrivateKey(bio, NULL, passphrase_cb);

int SSL_check_private_key ( SSL * ssl ) ;

Ensures the identifying certificate and the private key of an SSL match. The SSL_CTX is checked if the SSL does not hold authentication details.
Parameters:

ssl [In] The SSL that holds the certificate and private key.

Returns:
1 indicates there is a matching private key and certificate on the SSL.
If the SSL has neither, 1 indicates that the SSL_CTX has a match for its default certificate and private key.
0 indicates otherwise.

int SSL_CTX_check_private_key ( SSL_CTX * ctx ) ;

Checks that the default certificate and private key of the SSL_CTX ctx match.
Parameters:

ctx [In] The SSL_CTX against which to check the key.

Returns:
1 indicates the certificate matches the private key.
0 indicates otherwise.

Samples:
bio_server.c, cache_server.c, nbio_server.c, sock_server.c, and ssl_server.c.

int SSL_CTX_use_PrivateKey ( SSL_CTX * ctx,

EVP_PKEY * pkey

) ;

Duplicates and loads the private key pkey for the SSL_CTX ctx.
Parameters:

ctx [In] The SSL_CTX reference against which to set the default private key.

pkey [In] The EVP_PKEY reference.

Returns:
1 indicates success.
0 indicates error.
See also:
SSL_CTX_use_PrivateKey_file() and SSL_CTX_use_PrivateKey_ASN1().
Samples:
bio_server.c, cache_server.c, nbio_server.c, PKCS11Client.c, sock_server.c, and ssl_server.c.

int SSL_CTX_use_PrivateKey_ASN1 ( SSL_CTX * ctx,

unsigned char * key,

long len,

int type

) ;

Loads a private key pkey (in ASN.1 format) for the SSL_CTX ctx.
Parameters:

ctx [In] The SSL_CTX reference against which to set the default private key.

key [In] The private key.

len [In] The private key length.

type [In] The private key type - EVP_PKEY_RSA.

Returns:
1 indicates success.
0 indicates error.
See also:
SSL_CTX_use_PrivateKey().

int SSL_CTX_use_PrivateKey_file ( SSL_CTX * ctx,

char * file,

int type

) ;

Loads a private key from the file file to into the SSL_CTX ctx.
Parameters:

ctx [In, Out] The SSL_CTX reference where the key is bound.

file [In] The name of the file where the key is stored.

type [In] The method of key storage in the file. One of:

SSL_FILETYPE_ASN1 (Distinguished Encoding Rules/Basic Encoding Rules encoding).
SSL_FILETYPE_PEM.

Returns:
1 indicates success.
0 indicates error.
See also:
SSL_CTX_use_PrivateKey().

int SSL_CTX_use_RSAPrivateKey ( SSL_CTX * ctx,

RSA * rsa

) ;

Duplicates and loads the RSA private key rsa into the SSL_CTX ctx. As some cipher suites require an RSA certificate and private key to be loaded, this function loads the private key and is automatically matched to the relevant certificate when/if the certificate is loaded.
Parameters:

ctx [In] The SSL_CTX reference.

rsa [In] The RSA private key reference.

Returns:
1 indicates success.
0 indicates error.
See also:
SSL_CTX_use_RSAPrivateKey_ASN1().

int SSL_CTX_use_RSAPrivateKey_ASN1 ( SSL_CTX * ctx,

unsigned char * key_buf,

long len

) ;

Loads an RSA private key in ASN.1 format from a buffer into the SSL_CTX ctx. Some cipher suites require an RSA certificate and private key to be loaded. This function loads a private key in ASN.1 format and is automatically paired with the relevant certificate when it is loaded.
This function reads an in-memory array of Bytes that are converted into an appropriate format before being bound against the SSL_CTX.
Parameters:

ctx [In, Out] The SSL_CTX connection reference where the key is bound.

key_buf [In] The buffer containing the key in ASN.1 format.

len [In] The length of the buffer key_buf.

Returns:
1 indicates success.
0 indicates error.

int SSL_CTX_use_RSAPrivateKey_file ( SSL_CTX * ctx,

char * file,

int type

) ;

Loads an RSA private key from the file file into the SSL_CTX ctx. The key is added to the SSL_CTX default certificate information and will be used as the default private key by all SSL structures created for this SSL_CTX unless explicitly overridden.
Parameters:

ctx [In, Out] The SSL_CTX reference where the private key is bound.

file [In] The name of the file where the key is stored.

type [In] The method of key storage in the file. One of:

SSL_FILETYPE_ASN1.
SSL_FILETYPE_PEM.

Returns:
1 indicates success.
0 indicates error.

The private key must match the public key of any existing certificate attached to the SSL_CTX otherwise an error is generated. The specific error type can be viewed from the stack.
See also:
SSL_CTX_use_certificate().

int SSL_use_PrivateKey ( SSL * ssl,

EVP_PKEY * pkey

) ;

Sets the private key pkey to be used for the SSL connection ssl.
Parameters:

ssl [In] The SSL connection reference against which to set the private key.

pkey [In] The private key reference.

Returns:
1 indicates success.
0 indicates error.

int SSL_use_PrivateKey_ASN1 ( SSL * ssl,

unsigned char * data,

long len,

int type

) ;

Sets the private key data to use for the SSL connection ssl. The private key is provided in ASN.1 format.
Parameters:

ssl [In] The SSL connection reference against which to set the private key against.

data [In] The key.

len [In] The key length.

type [In] The private key type - EVP_PKEY_RSA.

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

int SSL_use_PrivateKey_file ( SSL * ssl,

char * file,

int type

) ;

Loads the private key stored in the file file for use with the SSL connection ssl.
Parameters:

ssl [In, Out] The SSL connection reference where the key is bound.

file [In] The name of the file where the key is stored.

type [In] The file - SSL_FILETYPE_PEM.

Returns:
1 indicates success.
0 indicates error.

int SSL_use_RSAPrivateKey ( SSL * ssl,

RSA * rsa

) ;

Loads the RSA private key rsa for the SSL connection ssl. Some cipher suites require an RSA certificate and private key to be loaded. This function loads the private key and is automatically matched to the relevant certificate when/if the certificate is loaded.
Parameters:

ssl [In] The SSL connection reference.

rsa [In] The RSA private key reference.

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

int SSL_use_RSAPrivateKey_ASN1 ( SSL * ssl,

unsigned char * d,

long len

) ;

Loads an RSA private key in ASN.1 format from a buffer into an SSL. Some cipher suites require an RSA certificate and private key to be loaded. This function loads a private key in ASN.1 format and is automatically paired with the relevant certificate when it is loaded.
This function reads an in-memory array of Bytes that are converted into an appropriate format before being bound against the SSL.
Parameters:

ssl [In, Out] The SSL connection reference where the key is bound.

d [In] The buffer containing the key in ASN.1 format.

len [In] The length of the buffer d.

Returns:
1 indicates success.
0 indicates error.

int SSL_use_RSAPrivateKey_file ( SSL * ssl,

char * file,

int type

) ;

Loads an RSA private key from the file file for the SSL connection ssl. Some cipher suites require an RSA certificate and private key to be loaded. This function loads the private key and is automatically matched to the relevant certificate when/if the certificate is loaded.
Parameters:

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

file [In] The name of file containing the key.

type [In] The file type. One of:

SSL_FILETYPE_ASN1.
SSL_FILETYPE_PEM.

Returns:
1 indicates success.
0 indicates error.

void SSLCERT_PKEY_free ( EVP_PKEY * pkey ) ;

Removes all allocated memory for the EVP_PKEY structure pkey.
Parameters:

pkey [In] The EVP_PKEY reference.

See also:
SSLCERT_PKEY_new() and SSLCERT_PKEY_reference_inc().
Samples:
bio_server.c, cache_server.c, nbio_server.c, sock_server.c, ssl_server.c, and verify_cb.c.

EVP_PKEY* SSLCERT_PKEY_from_binary ( int type,

EVP_PKEY ** ppkey,

unsigned char ** pp,

long length

) ;

Creates a new EVP_PKEY structure from the private key component of the binary data specified by ppkey.
Parameters:

type [In] The key type. One of:

EVP_PKEY_DSA.
EVP_PKEY_RSA.

ppkey [Out] The address of the EVP_PKEY pointer.

pp [In] The address of the binary ASN.1 data buffer.

length [In] The length of the data.

Returns:
The EVP_PKEY reference to the existing or new EVP_PKEY structure.
NULL indicates error.

If ppkey is NULL, SSLCERT_PKEY_from_binary() allocates memory for the EVP_PKEY structure.
See also:
SSLCERT_PKEY_from_PUBKEY_binary().

EVP_PKEY* SSLCERT_PKEY_from_PUBKEY_binary ( int type,

EVP_PKEY ** ppkey,

unsigned char ** pp,

long length

) ;

Creates a new EVP_PKEY structure from the public key component of the binary data specified by ppkey.
Parameters:

type [In] The key type. One of:

EVP_PKEY_DSA.
EVP_PKEY_RSA.

ppkey [Out] The address of the EVP_PKEY pointer.

pp [In] The address of the binary ASN.1 data buffer.

length [In] The length of the data.

Returns:
The EVP_PKEY reference to an existing or new EVP_PKEY structure.
NULL indicates error.

If ppkey is NULL, this function allocates memory for the EVP_PKEY structure.
See also:
SSLCERT_PKEY_from_binary().
Samples:
verify_cb.c.

EVP_PKEY* SSLCERT_PKEY_new ( void ) ;

Creates a new EVP_PKEY structure.
Returns:
The EVP_PKEY reference.
NULL indicates error.
See also:
SSLCERT_PKEY_free() and SSLCERT_PKEY_reference_inc().

void SSLCERT_PKEY_reference_inc ( EVP_PKEY * pkey ) ;

Increments the reference count for the specified EVP_PKEY structure pkey.
Parameters:

pkey [In] The EVP_PKEY reference.

The reference count is decremented by SSLCERT_PKEY_free() so the actual memory allocation for the EVP_PKEY structure will remain until the last reference is removed.
See also:
SSLCERT_PKEY_new() and SSLCERT_PKEY_free().