Operation Functions

This section contains all the functions that manage public keys.

Functions
R_PKEY_CTX*	R_PKEY_get_PKEY_CTX (R_PKEY *pkey)
	Returns the R_PKEY_CTX for the R_PKEY structure pkey. More...
int	R_PKEY_get_type (R_PKEY *pkey)
	Returns the type for the asymmetric key pkey. More...
int	R_PKEY_new (R_PKEY_CTX ctx, R_PKEY_TYPE pkeytype, R_PKEY *pkey)
	Creates a new R_PKEY structure pkey. More...
int	R_PKEY_free (R_PKEY *pkey)
	Removes all allocated memory for the R_PKEY structure pkey. More...
int	R_PKEY_copy (R_PKEY new_pkey, R_PKEY pkey, int flag)
	Copies a public key. More...
int	R_PKEY_from_binary (R_PKEY_CTX pkey_ctx, int flag, R_PKEY_TYPE type, size_t max_buf_len, const unsigned char buf, size_t consumed_len, R_PKEY *pkey)
	Creates an R_PKEY structure from the specified binary data in ASN.1 format indicated by buf with a length of max_buf_len. More...
int	R_PKEY_to_binary (R_PKEY pkey, size_t max_buf_len, unsigned char buf, size_t *consumed_len)
	Creates binary Basic Encoding Rules (BER)/Distinguished Encoding Rules (DER) encoded data from the specified R_PKEY structure and places the binary output in buf. More...
int	R_PKEY_from_public_key_binary (R_PKEY_CTX pkey_ctx, int flag, R_PKEY_TYPE type, size_t max_buf_len, const unsigned char buf, size_t consumed_len, R_PKEY *pkey)
	Creates a new R_PKEY structure from the public key component of the binary data buf. More...
int	R_PKEY_to_public_key_binary (R_PKEY pkey, size_t max_buf_len, unsigned char buf, size_t *out_len)
	Creates the binary data of the public key component of an R_PKEY structure pkey. More...
int	R_PKEY_reference_inc (R_PKEY *pkey)
	Increments the reference count for the specified R_PKEY structure pkey. More...
int	R_PKEY_cmp (R_PKEY key1, R_PKEY key2)
	Compares two keys key1 and key2. More...
int	R_PKEY_public_cmp (R_PKEY key1, R_PKEY key2)
	Compares the public components of two keys key1 and key2. More...
int	R_PKEY_get_info (R_PKEY pkey, int id, void param)
	Returns identified data for the R_PKEY pkey. More...
int	R_PKEY_set_info (R_PKEY pkey, int type, void param)
	Sets data for the R_PKEY pkey. More...
int	R_PKEY_iterate_fields (R_PKEY pkey, R_PKEY_CB_T func, void *arg)
	Applies the callback function func with callback argument arg to each field in the key pkey. More...
int	R_PKEY_get_num_bits (R_PKEY *pkey)
	Returns the number of bits in an asymmetric key for the R_PKEY structure pkey. More...
int	R_PKEY_get_num_primes (R_PKEY *pkey)
	Returns the number of primes contained in the RSA private key for the R_PKEY structure pkey. More...
int	R_PKEY_generate_simple (R_PKEY_CTX pkey_ctx, R_PKEY rpkey, int type, int num_bits, int modifier, int flags, R_SURRENDER surrender)
	Generates a new public/private key pair pkey. More...
int	R_PKEY_from_file (R_PKEY_CTX pkey_ctx, R_PKEY pkey, char filename, int type, R_FORMAT format)
	Creates an R_PKEY structure from the specified private key binary data in ASN.1 format indicated by filename with a private key type type. More...
int	R_PKEY_TYPE_to_string (R_PKEY_TYPE type, size_t max_str_len, char *str)
	Returns the key type string for the key type type. More...
int	R_PKEY_TYPE_from_string (R_PKEY_TYPE type, char str)
	Returns the key type for the string str. More...
int	R_PKEY_to_bio (BIO bio, R_PKEY pkey, R_FORMAT format, char *cipher)
	Outputs the R_PKEY structure pkey to the bio in the format specified by format. More...
int	R_PKEY_print (BIO bio, R_PKEY pkey, R_FORMAT format, char *format_arg)
	Prints an R_PKEY structure from the specified binary data in ASN.1 format indicated by bio with a format of format and format arguments format_arg. More...
int	R_PKEY_from_bio (BIO bio, R_PKEY_CTX pkey_ctx, R_PKEY **pkey, int type, R_FORMAT format)
	Creates an R_PKEY structure from the specified private key binary data in ASN.1 format indicated by bio with a format of format. More...

Function Documentation

int R_PKEY_cmp ( R_PKEY * key1,

R_PKEY * key2

) ;

Compares two keys key1 and key2.
Parameters:

key1 [In] The first key.

key2 [In] The second key.

Returns:
The comparison result. One of:

<0 indicates key1 is smaller than key2.
=0 indicates key1 is equal to key2.
>0 indicates key1 is greater than key2.
See also:
R_PKEY_public_cmp().

int R_PKEY_copy ( R_PKEY * pkey,

R_PKEY * new_pkey,

int flag

) ;

Copies a public key.
Parameters:

pkey [In] The public key to copy.

new_pkey [In, Out] The public key into which to copy.

flag [In] Reserved for future use.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_PKEY_new() and R_PKEY_free().

int R_PKEY_free ( R_PKEY * pkey ) ;

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

pkey [In] The key to destroy.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_PKEY_print() and R_PKEY_reference_inc().

int R_PKEY_from_binary ( R_PKEY_CTX * pkey_ctx,

int flag,

R_PKEY_TYPE type,

size_t max_buf_len,

const unsigned char * buf,

size_t * consumed_len,

R_PKEY ** pkey

) ;

Creates an R_PKEY structure from the specified binary data in ASN.1 format indicated by buf with a length of max_buf_len. If *pkey is NULL, an R_PKEY structure is allocated. This function is used when retrieving a private key from storage. R_PKEY holds private keys including RSA, Digital Signature Algorithm (DSA) and Diffie-Hellman keys.
Parameters:

pkey_ctx [In] The key context.

flag [In] The data flag. One of:

R_PKEY_FL_BY_REFERENCE.
R_PKEY_FL_DEFAULT.

type [In] The private key type. One of:

R_PKEY_TYPE_RSA.
R_PKEY_TYPE_DH.
R_PKEY_TYPE_DSA.

max_buf_len [In] The length of the input data buf.

buf [In] The input buffer containing ASN.1 key data.

consumed_len [Out] The amount of data from buf used to generate pkey.

pkey [Out] The created R_PKEY structure.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
Note:
If *pkey is NULL, R_PKEY_from_binary() allocates R_PKEY memory.
See also:
R_PKEY_from_public_key_binary() and R_PKEY_to_binary().

int R_PKEY_from_bio ( BIO * bio,

R_PKEY_CTX * pkey_ctx,

R_PKEY ** pkey,

int type,

R_FORMAT format

) ;

Creates an R_PKEY structure from the specified private key binary data in ASN.1 format indicated by bio with a format of format. If *pkey is NULL, an R_PKEY structure is allocated. R_PKEY holds private keys including RSA, Digital Signature Algorithm (DSA) and Diffie-Hellman keys.
Parameters:

bio [In] The BIO from which to read key data.

pkey_ctx [In] The key context.

pkey [Out] The created key.

type [In] The key type. One of:

R_PKEY_TYPE_DH.
R_PKEY_TYPE_RSA.
R_PKEY_TYPE_DSA.

format [In] The private key type. One of:

R_FORMAT_BINARY.
R_FORMAT_PEM.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_PKEY_to_bio().

int R_PKEY_from_file ( R_PKEY_CTX * pkey_ctx,

R_PKEY ** pkey,

char * filename,

int type,

R_FORMAT format

) ;

Creates an R_PKEY structure from the specified private key binary data in ASN.1 format indicated by filename with a private key type type. If *pkey is NULL, an R_PKEY structure is allocated. This is the general function used when loading private keys from files.
Parameters:

pkey_ctx [In] The key context.

pkey [Out] The created key.

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

type [In] The key type. One of:
R_PKEY_TYPE_DH.
R_PKEY_TYPE_RSA.
R_PKEY_TYPE_DSA.

format [In] The private key type. One of:
R_FORMAT_BINARY.
R_FORMAT_PEM.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
Note:
If the file is an encrypted Privacy Enhanced Mail (PEM) file, a password must be entered to enable decryption.
See also:
R_PKEY_to_bio().

int R_PKEY_from_public_key_binary ( R_PKEY_CTX * pkey_ctx,

int flag,

R_PKEY_TYPE type,

size_t max_buf_len,

const unsigned char * buf,

size_t * consumed_len,

R_PKEY ** pkey

) ;

Creates a new R_PKEY structure from the public key component of the binary data buf. R_PKEY is returned in pkey. type specifies the key type in binary. The data buffer buf should contain an ASN.1 format public key.
Parameters:

pkey_ctx [In] The public key context.

flag [In] The data flag. One of:

R_PKEY_FL_BY_REFERENCE.
R_PKEY_FL_DEFAULT.

type [In] The public key type. One of:

R_PKEY_TYPE_RSA.
R_PKEY_TYPE_DH.
R_PKEY_TYPE_DSA.

max_buf_len [In] The length of the input buffer buf.

buf [In] The input buffer containing key data.

consumed_len [In] The length of the input data used in the key.

pkey [Out] The created R_PKEY structure.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
Note:
If *pkey is NULL, R_PKEY_from_public_key_binary() allocates a new R_PKEY structure.
See also:
R_PKEY_from_binary().

int R_PKEY_generate_simple ( R_PKEY_CTX * pkey_ctx,

R_PKEY ** rpkey,

int type,

int num_bits,

int modifier,

int flags,

R_SURRENDER * surrender

) ;

Generates a new public/private key pair pkey.
Parameters:

pkey_ctx [In] The public key context.

rpkey [Out] The created public key.

type [In] The key type. One of:

R_PKEY_TYPE_RSA.
R_PKEY_TYPE_DH.
R_PKEY_TYPE_DSA.

num_bits [In] The key size in bits.

modifier [In] The number of primes to use when generating the key for RSA, or the generator value for Diffie-Hellman.

flags [In] The flag.
Reserved for future use.

surrender [In] The surrender structure.
Reserved for future use.

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

int R_PKEY_get_info ( R_PKEY * pkey,

int id,

void * param

) ;

Returns identified data for the R_PKEY pkey.
Parameters:

pkey [In] The asymmetric key.

id [In] The data identifier.
See Information Identifiers for valid values.

param [Out] The retrieved data item.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_PKEY_set_info().

int R_PKEY_get_num_bits ( R_PKEY * pkey ) ;

Returns the number of bits in an asymmetric key for the R_PKEY structure pkey.
Parameters:

pkey [In] The key.

Returns:
The number of bits in the key.
Zero or less indicates error.

int R_PKEY_get_num_primes ( R_PKEY * pkey ) ;

Returns the number of primes contained in the RSA private key for the R_PKEY structure pkey. This function is used when determining whether the key is a MultiPrime key.
Parameters:

pkey [In] The key.

Returns:
The number of primes.
Zero or less indicates error.
Note:
This function is only for use with MultiPrime RSA keys. There will always be at least two primes.

R_PKEY_CTX* R_PKEY_get_PKEY_CTX ( R_PKEY * pkey ) ;

Returns the R_PKEY_CTX for the R_PKEY structure pkey.
Parameters:

pkey [In] The asymmetric key for which to retrieve the key context.

Returns:
The key context.
NULL indicates error.

int R_PKEY_get_type ( R_PKEY * pkey ) ;

Returns the type for the asymmetric key pkey.
Parameters:

pkey [In] The asymmetric key.

Returns:
The key type. One of:

R_PKEY_TYPE_RSA.
R_PKEY_TYPE_DH.
R_PKEY_TYPE_DSA.
R_PKEY_TYPE_UNKNOWN.
See also:
R_PKEY_get_info().

int R_PKEY_iterate_fields ( R_PKEY * pkey,

R_PKEY_CB_T * func,

void * arg

) ;

Applies the callback function func with callback argument arg to each field in the key pkey.
Parameters:

pkey [In] The asymmetric key.

func [In] The callback function.

arg [In] The callback argument.

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

int R_PKEY_new ( R_PKEY_CTX * ctx,

R_PKEY_TYPE pkeytype,

R_PKEY ** pkey

) ;

Creates a new R_PKEY structure pkey.
Parameters:

ctx [In] The asymmetric key context.

pkey [Out] The created asymmetric key.

pkeytype [In] The asymmetric key type. One of:
R_PKEY_TYPE_RSA.
R_PKEY_TYPE_DH.
R_PKEY_TYPE_DSA.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_PKEY_free() and R_PKEY_reference_inc().

int R_PKEY_print ( BIO * bio,

R_PKEY * pkey,

R_FORMAT format,

char * format_arg

) ;

Prints an R_PKEY structure from the specified binary data in ASN.1 format indicated by bio with a format of format and format arguments format_arg. This function enables a key to be viewed in both human readable format and code representation.
Parameters:

bio [In] The BIO to print key data to.

pkey [In] The key to print.

format [In] The field identifier. One of:
R_FORMAT_TEXT.
R_FORMAT_CODE_BINARY.
R_FORMAT_CODE_FIELDS.
R_FORMAT_CODE_HEX.
R_FORMAT_HEX.

format_arg [In] The format argument.

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

int R_PKEY_public_cmp ( R_PKEY * key1,

R_PKEY * key2

) ;

Compares the public components of two keys key1 and key2.
Parameters:

key1 [In] The first key.

key2 [In] The second key.

Returns:
The comparison result. One of:

<0 indicates key1 is smaller than key2.
=0 indicates key1 is equal to key2.
>0 indicates key1 is greater than key2.
See also:
R_PKEY_cmp().

int R_PKEY_reference_inc ( R_PKEY * pkey ) ;

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

pkey [In] The key being referenced.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
Note:
The reference count is decremented by R_PKEY_free() so the actual memory allocation for the R_PKEY structure will remain until the last reference is removed.
See also:
R_PKEY_new() and R_PKEY_free().

int R_PKEY_set_info ( R_PKEY * pkey,

int id,

void * param

) ;

Sets data for the R_PKEY pkey.
Parameters:

pkey [In] The key.

id [In] The field identifier.
See Information Identifiers for valid values.

param [In] The data item.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_PKEY_get_info().

int R_PKEY_to_binary ( R_PKEY * pkey,

size_t max_buf_len,

unsigned char * buf,

size_t * consumed_len

) ;

Creates binary Basic Encoding Rules (BER)/Distinguished Encoding Rules (DER) encoded data from the specified R_PKEY structure and places the binary output in buf. This function is used when the pkey is to be shared. R_PKEY holds private keys including RSA, Digital Signature Algorithm (DSA) and Diffie-Hellman keys.
Parameters:

pkey [In] The private key.

max_buf_len [In] The size of memory allocated for buf.

buf [Out] The generated binary data.

consumed_len [Out] The length of the generated binary data.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_PKEY_from_binary(), R_PKEY_from_public_key_binary() and R_PKEY_to_public_key_binary().

int R_PKEY_to_bio ( BIO * bio,

R_PKEY * rpkey,

R_FORMAT format,

char * cipher

) ;

Outputs the R_PKEY structure pkey to the bio in the format specified by format.
Parameters:

bio [In] The BIO for output data.

rpkey [Out] The private key to output.

format [In] The key format of output data. One of:

R_FORMAT_BINARY.
R_FORMAT_PEM.

cipher [In] The encryption cipher of the key. One of:

"DES-CBC" indicating Data Encryption Standard (DES) encryption.
"DES-EDE3-CBC" indicating Triple DES encryption.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
Note:
For an encrypted pkey, specify the cipher or NULL. Where format is R_FORMAT_PEM cipher may be supplied. cipher is not required when format is R_FORMAT_BINARY.
See also:
R_PKEY_from_bio().

int R_PKEY_to_public_key_binary ( R_PKEY * pkey,

size_t max_buf_len,

unsigned char * buf,

size_t * out_len

) ;

Creates the binary data of the public key component of an R_PKEY structure pkey. The public key binary data is returned in data.
Parameters:

pkey [In] The R_PKEY structure.

max_buf_len [In] The size of memory allocated for buf.

buf [Out] The buffer for the created public key data.

out_len [Out] The length of the public key data.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_PKEY_to_binary(), R_PKEY_from_binary() and R_PKEY_from_public_key_binary().

int R_PKEY_TYPE_from_string ( R_PKEY_TYPE * type,

char * str

) ;

Returns the key type for the string str.
Parameters:

type [Out] The key type. One of:

R_PKEY_TYPE_RSA.
R_PKEY_TYPE_DSA.
R_PKEY_TYPE_DH.
R_PKEY_TYPE_UNKNOWN.

str [In] The key type string. One of:

"RSA"/"rsa".
"DSA"/"dsa".
"DH"/"dh".

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_PKEY_TYPE_to_string().

int R_PKEY_TYPE_to_string ( R_PKEY_TYPE type,

size_t max_str_len,

char * str

) ;

Returns the key type string for the key type type.
Parameters:

type [In] The key type. One of:

R_PKEY_TYPE_RSA.
R_PKEY_TYPE_DSA.
R_PKEY_TYPE_DH.

max_str_len [In] The size of the buffer allocated to str.

str [Out] The key type string. One of:

"RSA".
"DSA".
"DH".
"UNKNOWN" indicates invalid type.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_PKEY_TYPE_from_string().