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

Signed Data Functions

This section details the functions that facilitate signed data cryptographic messages.

Functions
int	R_CM_sign (R_CM *msg, R_CM_INDEX index)
	Generates a signature for each signer of the message. More...
int	R_CM_signer_verify (R_CM msg, R_CERT_STORE_CTX store_ctx, R_VERIFY_CTX vfy_ctx, R_CM_INDEX index, int is_verified)
	Checks the certificate chain verification of the specified signer at the specified index. More...
int	R_CM_signature_verify (R_CM msg, R_CM_INDEX index, R_CM data_msg, int *is_verified)
	Verifies that the signer specified by the index signed the data in the cryptographic message. More...
int	R_CM_get_signer_count (R_CM msg, int count)
	Retrieves a count of signers from a cryptographic message. More...
int	R_CM_signer_add (R_CM msg, R_CERT cert, R_PKEY key, R_CR_ALG_ID dgst, R_CM_INDEX index)
	Creates a new signer and returns the index for future reference. More...
int	R_CM_signer_delete (R_CM *msg, R_CM_INDEX index)
	Removes the signer at the index index from the list of signers. More...
int	R_CM_signer_is_attribute_present (R_CM *msg, R_CM_INDEX index, R_CM_INFO info_id)
	Checks a signer in the cryptographic message for the specified attribute. More...
int	R_CM_signer_get_attribute (R_CM msg, R_CM_INDEX index, R_CM_INFO info_id, R_CM_ATTR attr)
	Obtains the details of the attribute of the signer at the specified index with the specified attribute type from the cryptographic message. More...
int	R_CM_signer_set_attribute (R_CM msg, R_CM_INDEX index, R_CM_INFO info_id, R_CM_ATTR attr)
	Sets the details of the attribute of the signer at the specified index with the specified attribute type from the cryptographic message. More...
int	R_CM_get_verified_signer (R_CM msg, R_CERT_STORE_CTX store_ctx, R_VERIFY_CTX vfy_ctx, R_CM_INDEX start_index, R_CM_INDEX index)
	Returns the index of the next signer that passes a certificate chain verification. More...
int	R_CM_verify (R_CM msg, R_CERT_STORE_CTX store_ctx, R_VERIFY_CTX vfy_ctx, R_CM_INDEX index, R_CM data_msg, int *is_verified)
	Verifies that the signer specified by the index can be used to create a valid certificate chain and to verify the data in this cryptographic message or the one supplied. More...
int	R_CM_signer_get_R_VERIFY_STATE (R_CM msg, R_CM_INDEX index, R_VERIFY_STATE *vfy_state)
	Returns the verification state vfy_state for the specified signer identified by index. More...
void	R_CM_ATTR_msg_dgst_set_data (R_CM_ATTR attr, unsigned char buf, unsigned int len)
	Fills in the data fields of an attribute as required for the message digest attribute. More...
void	R_CM_ATTR_signing_time_set_data (R_CM_ATTR attr, int format, unsigned char buf, unsigned int len)
	Fills in the data fields of an attribute as required for the signing time attribute. More...
void	R_CM_ATTR_counter_sig_set_data (R_CM_ATTR attr, unsigned char buf, unsigned int len)
	Fills in the data fields of an attribute as required for the counter signature attribute. More...
void	R_CM_ATTR_content_type_set_data (R_CM_ATTR attr, unsigned char buf, unsigned int len)
	Fills in the data fields of an attribute as required for the content type attribute. More...

Function Documentation

void R_CM_ATTR_content_type_set_data ( R_CM_ATTR * attr,

unsigned char * buf,

unsigned int len

) ;

Fills in the data fields of an attribute as required for the content type attribute.
Parameters:

attr [In] The attribute.

buf [In] The attribute data.

len [In] The length of the attribute data.

void R_CM_ATTR_counter_sig_set_data ( R_CM_ATTR * attr,

unsigned char * buf,

unsigned int len

) ;

Fills in the data fields of an attribute as required for the counter signature attribute.
Parameters:

attr [In] The attribute.

buf [In] The attribute data.

len [In] The length of the attribute data.

void R_CM_ATTR_msg_dgst_set_data ( R_CM_ATTR * attr,

unsigned char * buf,

unsigned int len

) ;

Fills in the data fields of an attribute as required for the message digest attribute.
Parameters:

attr [In] The attribute.

buf [In] The attribute data.

len [In] The length of the attribute data.

void R_CM_ATTR_signing_time_set_data ( R_CM_ATTR * attr,

int format,

unsigned char * buf,

unsigned int len

) ;

Fills in the data fields of an attribute as required for the signing time attribute.
Parameters:

attr [In] The attribute.

format [In] The format of the time in the attribute data. One of:

R_TIME_EXTERNAL_FORMAT_UTC.
R_TIME_EXTERNAL_FORMAT_GT.

buf [In] The attribute data.

len [In] The length of the attribute data.

Samples:
cm_sign_sm.c.

int R_CM_get_signer_count ( R_CM * msg,

int * count

) ;

Retrieves a count of signers from a cryptographic message.
Parameters:

msg [In] The cryptographic message.

count [Out] The count of signers.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_get_info().
Samples:
cm_vfy_strm_cb.c.

int R_CM_get_verified_signer ( R_CM * msg,

R_CERT_STORE_CTX * store_ctx,

R_VERIFY_CTX * vfy_ctx,

R_CM_INDEX start_index,

R_CM_INDEX * index

) ;

Returns the index of the next signer that passes a certificate chain verification.
Parameters:

msg [In] The cryptographic message.

store_ctx [In] The certificate store context.

vfy_ctx [In] The framework to use in order to perform certificate chain verification.

start_index [In] The identifier which indicates where to start searching for signers.
-1 indicates to search from the beginning of the list of signers.

index [Out] The index of the next verified signer.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_signer_verify() and R_CM_signature_verify().

int R_CM_sign ( R_CM * msg,

R_CM_INDEX index

) ;

Generates a signature for each signer of the message. The signing process is applied for all signers if the index parameter is R_CM_INDEX_ALL.
Parameters:

msg [In] The cryptographic message.

index [In] The index of signer information.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
Samples:
cm_sign.c, cm_sign_dgst.c, cm_sign_sm.c, and p7ssl_client.c.

int R_CM_signature_verify ( R_CM * msg,

R_CM_INDEX index,

R_CM * data_msg,

int * is_verified

) ;

Verifies that the signer specified by the index signed the data in the cryptographic message.
Parameters:

msg [In] The cryptographic message.

index [In] The index of the signer.
R_CM_INDEX_ALL indicates that all signers will be verified.

data_msg [In] The message data for the cryptographic message.
This can be NULL if the message data or digest of the message data (in the case of streamed detached data) is in the cryptographic message ,msg.

is_verified [Out] Indicates that the signer details verified the data. One of:
1 indicates success.
0 indicates error.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_get_verified_signer() and R_CM_signer_verify().
Samples:
cm.c, cm_adv.c, cm_dgst.c, cm_sign_sm.c, and p7ssl_server.c.

int R_CM_signer_add ( R_CM * msg,

R_CERT * cert,

R_PKEY * key,

R_CR_ALG_ID dgst,

R_CM_INDEX * index

) ;

Creates a new signer and returns the index for future reference.
Parameters:

msg [In] The cryptographic message.

cert [In] The certificate associated with the private key.

key [In] The private key with which to sign.

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

index [Out] The index into the list of signers.
The index returned is only valid until a new signer is added.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_signer_delete() and R_CM_get_signer_count().
Samples:
cm_sign_sm.c, and p7ssl_client.c.

int R_CM_signer_delete ( R_CM * msg,

R_CM_INDEX index

) ;

Removes the signer at the index index from the list of signers.
Parameters:

msg [In] The cryptographic message.

index [In] The index into the list of signers.

Obtain the index by finding the signer by an identifier, or by iterating over all signers.
See also:
R_CM_get_verified_signer().

int R_CM_signer_get_attribute ( R_CM * msg,

R_CM_INDEX index,

R_CM_INFO info_id,

R_CM_ATTR * attr

) ;

Obtains the details of the attribute of the signer at the specified index with the specified attribute type from the cryptographic message.
Parameters:

msg [In] The cryptographic message.

index [In] The index into the list of signers.

info_id [In] The type of the attribute to retrieve.
See Attribute Identifiers for valid values.

attr [Out] The attribute details.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_signer_is_attribute_present() and R_CM_get_info().

int R_CM_signer_get_R_VERIFY_STATE ( R_CM * msg,

R_CM_INDEX index,

R_VERIFY_STATE ** vfy_state

) ;

Returns the verification state vfy_state for the specified signer identified by index. If the verification process fails, the reason code is returned.
Parameters:

msg [In] The cryptographic message (signed data).

index [In] The index of the signer.

vfy_state [Out] The retrieved signer verification state.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_verify() and R_CM_signer_verify().

int R_CM_signer_is_attribute_present ( R_CM * msg,

R_CM_INDEX index,

R_CM_INFO info_id

) ;

Checks a signer in the cryptographic message for the specified attribute.
Parameters:

msg [In] The cryptographic message.

index [In] The index into the list of signers.

info_id [In] The type of the attribute to retrieve.
See Attribute Identifiers for valid values.

Returns:
1 indicates the attribute is present in the signer's details.
0 indicates the attribute is not present in the signer's details.
See also:
R_CM_signer_get_attribute().

int R_CM_signer_set_attribute ( R_CM * msg,

R_CM_INDEX index,

R_CM_INFO info_id,

R_CM_ATTR * attr

) ;

Sets the details of the attribute of the signer at the specified index with the specified attribute type from the cryptographic message.
Parameters:

msg [In] The cryptographic message.

index [In] The index into the list of signers.

info_id [In] The type of the attribute to set.
See Attribute Identifiers for valid values.

attr [In] The attribute details.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_signer_is_attribute_present(), R_CM_signer_get_attribute() and R_CM_set_info().
Samples:
cm_sign_sm.c.

int R_CM_signer_verify ( R_CM * msg,

R_CERT_STORE_CTX * store_ctx,

R_VERIFY_CTX * vfy_ctx,

R_CM_INDEX index,

int * is_verified

) ;

Checks the certificate chain verification of the specified signer at the specified index.
Parameters:

msg [In] The cryptographic message (signed data).

store_ctx [In] The certificate store context.

vfy_ctx [In] The framework to use in order to perform certificate chain verification.

index [In] The index of the signer to verify.
R_CM_INDEX_ALL indicates that all signers will be verified.

is_verified [Out] Indicates that the signer details have been verified. One of:

1 indicates success.
0 indicates error.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_get_verified_signer(), R_CM_signature_verify() and R_CM_signer_get_R_VERIFY_STATE().
Samples:
cm.c, cm_adv.c, and cm_dgst.c.

int R_CM_verify ( R_CM * msg,

R_CERT_STORE_CTX * store_ctx,

R_VERIFY_CTX * vfy_ctx,

R_CM_INDEX index,

R_CM * data_msg,

int * is_verified

) ;

Verifies that the signer specified by the index can be used to create a valid certificate chain and to verify the data in this cryptographic message or the one supplied.
Parameters:

msg [In] The cryptographic message.

store_ctx [In] The certificate store context.

vfy_ctx [In] The framework to use in order to perform certificate chain verification.

index [In] The index of the signer.
R_CM_INDEX_ALL indicates that all signers will be verified.

data_msg [In] The cryptographic message (data).

is_verified [Out] Indicates that the signer details verified the data. One of:

1 indicates success.
0 indicates error.

Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CM_get_verified_signer(), R_CM_signer_verify() and R_CM_signer_get_R_VERIFY_STATE().
Samples:
cm_smpl.c.