Operation Functions

This section details the functions that facilitate the management of R_CR_CTX reference and R_CR objects.

Functions
int	R_CR_CTX_new (R_LIB_CTX lib_ctx, R_RES_FLAG flag, R_CR_CTX *crypto_ctx)
	Creates a cryptographic context by requesting the `CRYPTO` resource from the library module and initializing the context. More...
int	R_CR_CTX_free (R_CR_CTX *ctx)
	Frees all resources allocated to the cryptographic context. More...
int	R_CR_new (R_CR_CTX ctx, R_CR_ALG_TYPE alg_type, R_CR_ALG_ID alg_id, R_CR_ALG_SUB alg_sub, R_CR *crypto)
	Creates a cryptographic object that provides access to a specific cryptographic algorithm identified by the algorithm type, identifier, and sub-identifier. More...
int	R_CR_dup (R_CR crypto, R_CR *new_crypto)
	Duplicates a cryptographic object by allocating resources for the new object and copying values from the old. More...
int	R_CR_free (R_CR *crypto)
	Frees all resources allocated to the cryptographic object. More...
int	R_CR_get_info (R_CR crypto, int id, void param)
	Retrieves information about a cryptographic object by providing read access to algorithm-specific attributes such as key or block size. More...
int	R_CR_set_info (R_CR crypto, int id, void param)
	Sets information about a cryptographic object by providing write access to algorithm-specific attributes like key or block size. More...
int	R_CR_CTX_get_info (R_CR_CTX ctx, int id, void param)
	Uses the identifier to retrieve information from a cryptographic object context. More...
int	R_CR_CTX_set_info (R_CR_CTX ctx, int id, void param)
	Uses the identifier to set information into a cryptographic object context. More...
int	R_CR_CTX_alg_supported (R_CR_CTX ctx, int alg_type, int alg_id, int alg_sub, int is_supported)
	Determines if the method for a selected algorithm and operation is available. More...
int	R_CR_CTX_ids_to_sig_id (R_CR_CTX ctx, int dig_id, int pkey_id, int sig_id)
	Retrieves the sign/verify identifier for a given digest and asymmetric identifier pair. More...
int	R_CR_CTX_ids_from_sig_id (R_CR_CTX ctx, int sig_id, int dig_id, int *pkey_id)
	Retrieves the digest and asymmetric identifier pair for a given sign/verify identifier. More...
int	R_CR_ID_from_string (char str, R_CR_ALG_ID type)
	Returns the algorithm identifier for the string str. More...
int	R_CR_ID_to_string (R_CR_ALG_ID type, size_t max_str_len, char *str)
	Returns the string str for an algorithm identifier type. More...
int	R_CR_TYPE_from_string (char str, R_CR_ALG_TYPE type)
	Returns the algorithm type for the string str. More...
int	R_CR_TYPE_to_string (R_CR_ALG_TYPE type, size_t max_str_len, char *str)
	Returns the string str for an algorithm type identifier type. More...
int	R_CR_SUB_from_string (char str, R_CR_ALG_SUB type)
	Returns the algorithm subtype identifier for the string str. More...
int	R_CR_SUB_to_string (R_CR_ALG_SUB type, size_t max_str_len, char *str)
	Returns the string str for an algorithm subtype identifier type. More...
R_CR_METHOD*	R_CR_get_default_method (void *imp_data)
	Retrieves the default method table. More...
void	R_CR_RES_CRYPTO_CUSTOM_METHOD (R_CR_METHOD (meth_fn)(void), R_CR_IMP_METHOD (alg_fn)(void))
	Binds a custom algorithm list and method table to the cryptographic module. More...
R_CR_IMP_METHOD *	R_CR_DEFINE_CUSTOM_CIPHER_LIST (R_CR_IMP_METHOD list, void fn)
	Creates a function to return the custom algorithms. More...
R_CR_METHOD *	R_CR_DEFINE_CUSTOM_METHOD_TABLE (R_CR_METHOD list, void fn)
	Creates a function to return the custom methods. More...

Function Documentation

int R_CR_CTX_alg_supported ( R_CR_CTX * ctx,

int alg_type,

int alg_id,

int alg_sub,

int * is_supported

) ;

Determines if the method for a selected algorithm and operation is available.
Parameters:

ctx [In] The cryptographic object context, allocated by R_CR_CTX_new().

alg_type [In] The algorithm type.
See Operation Types for valid values.

alg_id [In] The algorithm identifier.
See Algorithm Identifiers for valid values.

alg_sub [In] The algorithm sub-identifier.
See Operation Subtypes for valid values.

is_supported [Out] The supported result. One of:

R_CR_SUPPORTED Indicates the algorithm and operation are supported.

R_CR_NOT_SUPPORTED Indicates the algorithm or operation is not supported.

Returns:
R_ERROR_NONE indicates success.
R_ERROR_NULL_ARG indicates that ctx is NULL.

int R_CR_CTX_free ( R_CR_CTX * ctx ) ;

Frees all resources allocated to the cryptographic context.
Parameters:

ctx [In] A pointer to the cryptographic context to free, previously created via R_CR_CTX_new().

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

int R_CR_CTX_get_info ( R_CR_CTX * ctx,

int id,

void * param

) ;

Uses the identifier to retrieve information from a cryptographic object context.
Parameters:

ctx [In] The cryptographic object context, allocated by R_CR_CTX_new().

id [In] The requested data identifier. One of:

R_CR_CTX_INFO_ID_RANDOM.
R_CR_CTX_INFO_ID_SURRENDER.

param [Out] The retrieved data.

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

int R_CR_CTX_ids_from_sig_id ( R_CR_CTX * ctx,

int sig_id,

int * dig_id,

int * pkey_id

) ;

Retrieves the digest and asymmetric identifier pair for a given sign/verify identifier.
Parameters:

ctx [In] The resouce context.

sig_id [In] The sign/verify identifier.

dig_id [Out] The digest algorithm identifier.

pkey_id [Out] The asymmetric algorithm identifier.

Returns:
The method result. One of:

R_ERROR_NONE Indicates success.

R_ERROR_NOT_FOUND Indicates that the table retrieval function or sign mapping table was not found.

R_ERROR_NOT_SUPPORTED Indicates that the requested identifier was not found in the mapping table.

See also:
R_CR_CTX_ids_to_sig_id().

int R_CR_CTX_ids_to_sig_id ( R_CR_CTX * ctx,

int dig_id,

int pkey_id,

int * sig_id

) ;

Retrieves the sign/verify identifier for a given digest and asymmetric identifier pair.
Parameters:

ctx [In] The resouce context.

dig_id [In] The digest algorithm identifier.

pkey_id [In] The asymmetric algorithm identifier.

sig_id [Out] The returned sign/verify identifier.

Returns:
The method result. One of:

R_ERROR_NONE Indicates success.

R_ERROR_NOT_FOUND Indicates the table retrieval function or sign mapping was not table found.

R_ERROR_NOT_SUPPORTED Indicates the requested identifier was not found in the mapping table.

See also:
R_CR_CTX_ids_from_sig_id().

int R_CR_CTX_new ( R_LIB_CTX * lib_ctx,

R_RES_FLAG flag,

R_CR_CTX ** crypto_ctx

) ;

Creates a cryptographic context by requesting the CRYPTO resource from the library module and initializing the context.
Parameters:

lib_ctx [In] A pointer to the current library context.
Must reference a library context structure.

flag [In] Creates a new cryptographic context.
Only R_RES_FLAG_DEF is supported.

crypto_ctx [Out] The address of a pointer to a cryptographic context.

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

int R_CR_CTX_set_info ( R_CR_CTX * ctx,

int id,

void * param

) ;

Uses the identifier to set information into a cryptographic object context.
Parameters:

ctx [In] The cryptographic object context, allocated by R_CR_CTX_new().

id [In] The requested data identifier.
See Cryptographic Context Information Defines for valid values.

param [In] The data to set.

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

R_CR_IMP_METHOD * R_CR_DEFINE_CUSTOM_CIPHER_LIST ( R_CR_IMP_METHOD list,

void fn

) ;

Creates a function to return the custom algorithms. The custom algorithm list is an array of type R_CR_IMP_METHOD.
Parameters:

list [In] The custom algorithm list.

fn [In] The name of the function to create.

Returns:
A cryptographic implementation method table.
See also:
R_CR_RES_CRYPTO_CUSTOM_METHOD.

R_CR_METHOD * R_CR_DEFINE_CUSTOM_METHOD_TABLE ( R_CR_METHOD list,

void fn

) ;

Creates a function to return the custom methods. The custom methods list is a structure of R_CR_METHOD.
Parameters:

list [In] The custom methods list.

fn [In] The name of the function to create.

Returns:
A cryptographic method table.
See also:
R_CR_RES_CRYPTO_CUSTOM_METHOD.

int R_CR_dup ( R_CR * crypto,

R_CR ** new_crypto

) ;

Duplicates a cryptographic object by allocating resources for the new object and copying values from the old.
Parameters:

crypto [In] A pointer to the cryptographic object.
Must reference a cryptographic object structure.

new_crypto [Out] The address of a pointer to a cryptographic object.

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

int R_CR_free ( R_CR * crypto ) ;

Frees all resources allocated to the cryptographic object.
Parameters:

crypto [In] A pointer to the cryptographic object to free, previously created via R_CR_new().

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
Note:
It is the calling function's responsibility to set crypto to NULL after the R_CR object has been freed.
See also:
R_CR_dup() and R_CR_new().

R_CR_METHOD* R_CR_get_default_method ( void * imp_data ) ;

Retrieves the default method table.
Parameters:

imp_data [In] The resource data.
Reserved for future use.

Returns:
A pointer to the static table.

int R_CR_get_info ( R_CR * crypto,

int id,

void * param

) ;

Retrieves information about a cryptographic object by providing read access to algorithm-specific attributes such as key or block size.
Parameters:

crypto [In] A pointer to the cryptographic object.

id [In] The identifier for the requested attribute.
See Cryptographic Operation Property Identifiers for valid values.

param [Out] A void pointer that takes the returned value.

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

int R_CR_ID_from_string ( char * str,

R_CR_ALG_ID * type

) ;

Returns the algorithm identifier for the string str. This function is used for interpreting user input.
Parameters:

str [In] The format identifier string.
See Algorithm Identifiers for valid values.

type [Out] The certificate type identifier.
See Algorithm Identifiers for valid values.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_CR_TYPE_to_string(), R_CR_TYPE_from_string(), R_CR_SUB_to_string() and R_CR_SUB_from_string().

int R_CR_ID_to_string ( R_CR_ALG_ID type,

size_t max_str_len,

char * str

) ;

Returns the string str for an algorithm identifier type. This function is used for test output reasons.
Parameters:

type [In] The algorithm identifier.
See Algorithm Identifiers for valid values.

max_str_len [In] The maximum length of the string.

str [Out] The string representing the algorithm identifier.
See Algorithm Identifiers for valid values.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_CR_TYPE_to_string(), R_CR_TYPE_from_string(), R_CR_SUB_to_string() and R_CR_SUB_from_string().

int R_CR_new ( R_CR_CTX * ctx,

R_CR_ALG_TYPE alg_type,

R_CR_ALG_ID alg_id,

R_CR_ALG_SUB alg_sub,

R_CR ** crypto

) ;

Creates a cryptographic object that provides access to a specific cryptographic algorithm identified by the algorithm type, identifier, and sub-identifier. It calls context initialization functions as specified in the algorithm interface.
Parameters:

ctx [In] A pointer to the cryptographic context.
Must reference a cryptographic context structure.

alg_type [In] The algorithm type.
See Operation Types for valid values.

alg_id [In] The algorithm identifier.
See Algorithm Identifiers for valid values.

alg_sub [In] The algorithm sub-identifier.
See Operation Subtypes for valid values.

crypto [Out] The address of a pointer to a cryptographic object.

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

void R_CR_RES_CRYPTO_CUSTOM_METHOD ( R_CR_METHOD *(* meth_fn)(void),

R_CR_IMP_METHOD *(* alg_fn)(void)

) ;

Binds a custom algorithm list and method table to the cryptographic module. The custom method list must be specified with the R_CR_DEFINE_CUSTOM_METHOD_TABLE macro. The custom algorithm list must be specified with the R_CR_DEFINE_CUSTOM_CIPHER_LIST macro.
Parameters:

meth_fn [In] The function returning the custom method list.

alg_fn [In] The function returning the custom algorithm list.

int R_CR_set_info ( R_CR * crypto,

int id,

void * param

) ;

Sets information about a cryptographic object by providing write access to algorithm-specific attributes like key or block size.
Parameters:

crypto [In] A pointer to the cryptographic object.

id [In] The identifier for the requested attribute. Valid values include:
R_CR_INFO_ID_SURRENDER.
R_CR_INFO_ID_FLAGS.
See Cryptographic Operation Property Identifiers for valid values.

param [In] A void pointer that takes the returned value.

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

int R_CR_SUB_from_string ( char * str,

R_CR_ALG_SUB * type

) ;

Returns the algorithm subtype identifier for the string str. This function is used for interpreting user input.
Parameters:

str [In] The subtype identifier string.
See Operation Subtypes for valid values.

type [Out] The subtype type identifier.
See Operation Subtypes for valid values.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_CR_TYPE_to_string(), R_CR_TYPE_from_string(), R_CR_ID_to_string() and R_CR_ID_from_string().

int R_CR_SUB_to_string ( R_CR_ALG_SUB type,

size_t max_str_len,

char * str

) ;

Returns the string str for an algorithm subtype identifier type. This function is used for test output reasons.
Parameters:

type [In] The algorithm subtype identifier.
See Algorithm Identifiers for valid values.

max_str_len [In] The maximum length of the string.

str [Out] The string representing the subtype.
See Operation Subtypes for valid values.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_CR_TYPE_to_string(), R_CR_TYPE_from_string(), R_CR_ID_to_string() and R_CR_ID_from_string().

int R_CR_TYPE_from_string ( char * str,

R_CR_ALG_TYPE * type

) ;

Returns the algorithm type for the string str. This function is used for interpreting user input.
Parameters:

str [In] The type identifier string.
See Operation Types for valid values.

type [Out] The algorithm type identifier.
See Operation Types for valid values.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_CR_ID_to_string(), R_CR_ID_from_string(), R_CR_SUB_to_string() and R_CR_SUB_from_string().

int R_CR_TYPE_to_string ( R_CR_ALG_TYPE type,

size_t max_str_len,

char * str

) ;

Returns the string str for an algorithm type identifier type. This function is used for test output reasons.
Parameters:

type [In] The algorithm type identifier.
See Operation Types for valid values.

max_str_len [In] The maximum length of the string.

str [Out] The string representing the algorithm type.
See Operation Types for valid values.

Returns:
R_ERROR_NONE indicates success.
See Error Identifiers for valid values.
See also:
R_CR_ID_to_string(), R_CR_ID_from_string(), R_CR_SUB_to_string() and R_CR_SUB_from_string().