	RSA BSAFE Micro Edition Suite	Streamlined security for mobile and embedded devices

Operation Functions

This section details the functions that facilitate cryptographic message objects.

Functions
int	R_CM_new (R_CM_CTX ctx, R_CM_TYPE type, R_CM *msg)
	Creates a new cryptographic message msg. More...
int	R_CM_free (R_CM *msg)
	Deallocates the cryptographic message msg and all associated data. More...
int	R_CM_from_binary (R_CM_CTX ctx, R_FLAG_SHARE flag, R_CM_TYPE type, R_CM_ENCODING encoding_format, unsigned int max_buf_len, unsigned char buf, unsigned int consumed_len, R_CM *msg)
	Creates a cryptographic message from the specified binary data. More...
int	R_CM_to_binary (R_CM msg, R_CM_ENCODING encoding_format, unsigned int max_buf_len, unsigned char buf, unsigned int *out_len)
	Creates a binary cryptographic message from the specified cryptographic message. More...
int	R_CM_get_info (R_CM msg, R_CM_INFO info_id, void value)
	Retrieves information from the cryptographic message. More...
int	R_CM_set_info (R_CM msg, R_CM_INFO info_id, void value)
	Sets information into the cryptographic message. More...
int	R_CM_write (R_CM msg, BIO bio, R_FORMAT format, void *format_arg, R_CM_ENCODING encoding_format)
	Writes the cryptographic message to a BIO in the specified format. More...
int	R_CM_write_file (R_CM msg, char filename, R_FORMAT format, void *format_arg, R_CM_ENCODING encoding_format)
	Writes the cryptographic message to a file in the specified format. More...
int	R_CM_read (R_CM_CTX ctx, BIO bio, R_FORMAT format, R_CM_ENCODING encoding_format, R_CM **msg)
	Creates a new cryptographic message object from data read in from a BIO. More...
int	R_CM_read_file (R_CM_CTX ctx, char filename, R_FORMAT format, R_CM_ENCODING encoding_format, R_CM **msg)
	Creates a new cryptographic message object from data read in from a file. More...
int	R_CM_TYPE_from_string (char str, R_CM_TYPE type)
	Converts a cryptographic message type string into a cryptographic message type value. More...
int	R_CM_TYPE_to_string (R_CM_TYPE type, unsigned int max_str_len, char *str)
	Converts a cryptographic message type value into a cryptographic message type string. More...
int	R_CM_content_to_R_CM (R_CM msg, R_FLAG_SHARE flag, R_CM *new_msg)
	Retrieves the `ContentInfo` block from the cryptographic message and creates a new cryptographic message from its contents. More...
int	R_CM_content_from_R_CM (R_CM msg, R_FLAG_SHARE flag, R_CM in_msg)
	Sets the cryptographic message in_msg into the `ContentInfo` block of the cryptographic message msg. More...
int	R_CM_get_index (R_CM msg, R_CERT cert, R_CM_INDEX *index)
	Finds the first signer or recipient in a cryptographic message that matches the subject certificate. More...
int	R_CM_to_BIO (R_CM msg, int flag, BIO *bio)
	Creates a BIO filter from the cryptographic message object. More...

Function Documentation

int R_CM_content_from_R_CM ( R_CM * msg,

R_FLAG_SHARE flag,

R_CM * in_msg

) ;

Sets the cryptographic message in_msg into the ContentInfo block of the cryptographic message msg.
Parameters:

msg [In] The cryptographic message.

flag [In] Specifies if the data in in_msg should be used by reference or not.

in_msg [In] The cryptographic message to set into the ContentInfo.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_get_info().
Samples:
cm_env.c, cm_env_sm.c, cm_sign.c, cm_sign_sm.c, and p7ssl_client.c.

int R_CM_content_to_R_CM ( R_CM * msg,

R_FLAG_SHARE flag,

R_CM ** new_msg

) ;

Retrieves the ContentInfo block from the cryptographic message and creates a new cryptographic message from its contents.
Parameters:

msg [In] The cryptographic message.

flag [In] Specifies if the data in msg should be used by reference or not.

new_msg [Out] The cryptographic message constructed from the ContentInfo of msg.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_get_info().
Samples:
cm.c, cm_adv.c, cm_env_sm.c, cm_open.c, and cm_smpl.c.

int R_CM_free ( R_CM * msg ) ;

Deallocates the cryptographic message msg and all associated data. Data referenced by the object is not deallocated.
Parameters:

msg [In] The cryptographic message to deallocate.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_new(), R_CM_CTX_new() and R_CM_CTX_free().
Samples:
cm.c, cm_adv.c, cm_dgst.c, cm_env.c, cm_env_sm.c, cm_env_strm.c, cm_env_strm_membio.c, cm_open.c, cm_open_strm.c, cm_open_strm_cb.c, cm_open_strm_membio.c, cm_sign.c, cm_sign_dgst.c, cm_sign_sm.c, cm_sign_strm.c, cm_smpl.c, cm_strm.c, cm_type.c, cm_vfy_strm_cb.c, p7ssl_client.c, and p7ssl_server.c.

int R_CM_from_binary ( R_CM_CTX * ctx,

R_FLAG_SHARE flag,

R_CM_TYPE type,

R_CM_ENCODING encoding_format,

unsigned int max_buf_len,

unsigned char * buf,

unsigned int * consumed_len,

R_CM ** msg

) ;

Creates a cryptographic message from the specified binary data.
Parameters:

ctx [In] The cryptographic message context.

flag [In] The data to reference or copy.

type [In] The type of cryptographic message.
See Types for valid values.

encoding_format [In] The format of the encoding.
See Encoding Formats for valid values.

max_buf_len [In] The length of the binary data.

buf [In] The binary data buffer holding the cryptographic message.

consumed_len [Out] The amount of data used in creating the cryptographic message.

msg [Out] The created cryptographic message.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_to_binary(), R_CM_read(), R_CM_read_file(), R_CM_write() and R_CM_write_file().
Samples:
cm.c, cm_adv.c, cm_dgst.c, cm_env.c, cm_env_sm.c, cm_open.c, cm_sign_sm.c, cm_smpl.c, cm_type.c, p7ssl_client.c, and p7ssl_server.c.

int R_CM_get_index ( R_CM * msg,

R_CERT * cert,

R_CM_INDEX * index

) ;

Finds the first signer or recipient in a cryptographic message that matches the subject certificate.
Parameters:

msg [In] The cryptographic message.

cert [In] A signer/recipient's certificate.

index [Out] The index into the list of signers or recipients that matches the certificate.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
Samples:
cm_env_sm.c, and cm_open.c.

int R_CM_get_info ( R_CM * msg,

R_CM_INFO info_id,

void * value

) ;

Retrieves information from the cryptographic message.
Parameters:

msg [In] The cryptographic message.

info_id [In] The identifier of the information from which to retrieve the cryptographic message.
See Identifiers and Flags for valid values and the data type of value.

value [Out] The requested information.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
Samples:
cm.c, cm_adv.c, cm_dgst.c, cm_env.c, cm_env_sm.c, cm_open.c, cm_open_strm_cb.c, cm_sign_sm.c, cm_smpl.c, cm_type.c, and cm_vfy_strm_cb.c.

int R_CM_new ( R_CM_CTX * ctx,

R_CM_TYPE type,

R_CM ** msg

) ;

Creates a new cryptographic message msg.
Parameters:

ctx [In] The cryptographic message context from which to create the cryptographic message.

type [In] The type of cryptographic message to create.
See Types for valid values.

msg [Out] The created cryptographic message.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_free(), R_CM_CTX_new() and R_CM_CTX_free().
Samples:
cm.c, cm_adv.c, cm_env.c, cm_env_sm.c, cm_env_strm.c, cm_env_strm_membio.c, cm_open_strm.c, cm_open_strm_cb.c, cm_open_strm_membio.c, cm_sign.c, cm_sign_dgst.c, cm_sign_sm.c, cm_sign_strm.c, cm_smpl.c, cm_strm.c, cm_vfy_strm_cb.c, and p7ssl_client.c.

int R_CM_read ( R_CM_CTX * ctx,

BIO * bio,

R_FORMAT format,

R_CM_ENCODING encoding_format,

R_CM ** msg

) ;

Creates a new cryptographic message object from data read in from a BIO.
Parameters:

ctx [In] The cryptographic message context.

bio [In] The BIO from which to retrieve the cryptographic message.

format [In] The format of the cryptographic message data in the BIO.
See Data Encoding Formats for valid values.

encoding_format [In] The format of the encoding.
See Encoding Formats for valid values.

msg [Out] The new cryptographic message.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_read_file(), R_CM_to_binary() and R_CM_from_binary().
Samples:
cm_sign_sm.c.

int R_CM_read_file ( R_CM_CTX * ctx,

char * filename,

R_FORMAT format,

R_CM_ENCODING encoding_format,

R_CM ** msg

) ;

Creates a new cryptographic message object from data read in from a file.
Parameters:

ctx [In] The cryptographic message context.

filename [In] The name of the file from which to retrieve the cryptographic message.

format [In] The format of the cryptographic message in the file.
See Data Encoding Formats for valid values.

encoding_format [In] The format of the encoding.
See Encoding Formats for valid values.

msg [Out] The new cryptographic message.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_read(), R_CM_to_binary() and R_CM_from_binary().
Samples:
cm_env.c, cm_env_sm.c, and cm_sign.c.

int R_CM_set_info ( R_CM * msg,

R_CM_INFO info_id,

void * value

) ;

Sets information into the cryptographic message.
Parameters:

msg [In] The cryptographic message.

info_id [In] The identifier of the information into which to set the cryptographic message.
See Identifiers and Flags for valid values and the data type of value.

value [In] The information to set.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_get_info().
Samples:
cm.c, cm_adv.c, cm_dgst.c, cm_env.c, cm_env_strm.c, cm_env_strm_membio.c, cm_open.c, cm_sign.c, cm_sign_dgst.c, and cm_smpl.c.

int R_CM_to_binary ( R_CM * msg,

R_CM_ENCODING encoding_format,

unsigned int max_buf_len,

unsigned char * buf,

unsigned int * out_len

) ;

Creates a binary cryptographic message from the specified cryptographic message.
Parameters:

msg [In] The cryptographic message.

encoding_format [In] The format of the encoding.
See Encoding Formats for valid values.

max_buf_len [In] The amount of memory allocated to the buffer.

buf [Out] The binary data buffer into which to put the binary cryptographic message.

out_len [Out] The amount of data put into the buffer.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_from_binary(), R_CM_write(), R_CM_write_file(), R_CM_read() and R_CM_read_file().
Samples:
p7ssl_client.c.

int R_CM_to_BIO ( R_CM * msg,

int flag,

BIO ** bio

) ;

Creates a BIO filter from the cryptographic message object.
Parameters:

msg [In] The cryptographic message object.

flag [In] The flag indicating the context of use.
See Flags for valid values.

bio [Out] The BIO filter.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_to_binary(), R_CM_from_binary() R_CM_read(), R_CM_read_file(), R_CM_write() and R_CM_write_file().
Samples:
cm_env_strm.c, cm_env_strm_membio.c, cm_open_strm.c, cm_open_strm_cb.c, cm_open_strm_membio.c, cm_sign_strm.c, cm_strm.c, and cm_vfy_strm_cb.c.

int R_CM_TYPE_from_string ( char * str,

R_CM_TYPE * type

) ;

Converts a cryptographic message type string into a cryptographic message type value.
Parameters:

str [In] The cryptographic message type string.

type [Out] The cryptographic message type value.
See Types for valid values and corresponding input strings.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_TYPE_to_string().
Samples:
cm_env_strm.c, cm_env_strm_membio.c, and cm_sign_strm.c.

int R_CM_TYPE_to_string ( R_CM_TYPE type,

unsigned int max_str_len,

char * str

) ;

Converts a cryptographic message type value into a cryptographic message type string.
Parameters:

type [In] The cryptographic message type value.
See Types for valid values and corresponding output strings.

max_str_len [In] The amount of memory allocated to the string.

str [Out] The cryptographic message type string.

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

R_CM_TYPE_MAX_STR_LENGTH indicates the maximum length of a cryptographic message type string.
See also:
R_CM_TYPE_from_string().
Samples:
cm_env_sm.c, cm_sign_sm.c, cm_smpl.c, and cm_type.c.

int R_CM_write ( R_CM * msg,

BIO * bio,

R_FORMAT format,

void * format_arg,

R_CM_ENCODING encoding_format

) ;

Writes the cryptographic message to a BIO in the specified format.
Parameters:

msg [In] The cryptographic message.

bio [In] The BIO into which to put the cryptographic message.

format [In] The output format of the cryptographic message.
See Data Encoding Formats for valid values and the corresponding argument.

format_arg [In] The extra data for the specific format.

encoding_format [In] The encoding format of the data written to bio.
See Encoding Formats for valid values.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_write_file(), R_CM_read(), R_CM_read_file(), R_CM_to_binary() and R_CM_from_binary().
Samples:
cm.c, cm_adv.c, cm_env.c, cm_env_sm.c, cm_env_strm.c, cm_env_strm_membio.c, cm_open.c, cm_open_strm.c, cm_open_strm_cb.c, cm_open_strm_membio.c, cm_sign.c, cm_sign_dgst.c, cm_sign_sm.c, cm_sign_strm.c, and cm_smpl.c.

int R_CM_write_file ( R_CM * msg,

char * filename,

R_FORMAT format,

void * format_arg,

R_CM_ENCODING encoding_format

) ;

Writes the cryptographic message to a file in the specified format.
Parameters:

msg [In] The cryptographic message.

filename [In] The name of the file into which to put the cryptographic message.

format [In] The output format of the cryptographic message.
See Data Encoding Formats for valid values and the corresponding argument.

format_arg [In] The extra data for the specific format.

encoding_format [In] The encoding format for the data written to file.
See Encoding Formats for valid values.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_write(), R_CM_read(), R_CM_read_file(), R_CM_to_binary() and R_CM_from_binary().