RSA Security logo

RSA BSAFE Cert-C
API Reference

cms.h File Reference

This file contains the data structures and functions to create and parse a PKCS #7 message that is a subset of Cryptographic Message Syntax (CMS).

#include "bsafe.h"
#include "basetype.h"
#include "certpath.h"
#include "certext.h"
#include "certalg.h"

Go to the source code of this file.

Data Structures

struct  CERT_IDENTIFIER
 Identifies a certificate by the certificate's issuer name and the certificate's serial number. More...

struct  ISSUER_SERIAL_NUMBER
 Uniquely identifies a certificate by the distinguished name of the certificate issuer and an issuer-specific certificate serial number. More...

struct  KEY_TRANSPORT_INFO
 Holds key transport information. More...

struct  RECIPIENT_INFO
 Holds message recipient information. More...

struct  SIGNER_INFO
 Contains message signer information. More...


Functions

int C_ReadMessageType (CERTC_CTX ctx, ITEM *cmsMsg, ITEM *oid)
 Extracts the OID from a CMS-formatted message. More...

int C_WriteDataMsg (CERTC_CTX ctx, ITEM *data, ITEM *dataMsg)
 Prepares a simple data message. More...

int C_WriteSignedDataMsg (CERTC_CTX ctx, CERT_PATH_CTX *pathCtx, SERVICE database, ITEM *data, UINT4 cmsOptions, LIST_OBJ certificates, LIST_OBJ crls, LIST_OBJ signers, ITEM *signedDataMsg)
 Prepares a signed-data message. More...

int C_WriteEnvelopedDataMsg (CERTC_CTX ctx, SERVICE database, ITEM *data, ALGORITHM_IDENTIFIER *contentEncryptionAlgorithmId, LIST_OBJ recipientInfos, B_KEY_OBJ encryptionKey, POINTER reserved1, ATTRIBUTES_OBJ reserved2, ITEM *envelopedDataMsg)
 Prepares an enveloped-data message. More...

int C_WriteDigestedDataMsg (CERTC_CTX ctx, ITEM *data, int digestAlgorithmId, ITEM *digestedDataMsg)
 Prepares a digested data message. More...

int C_WriteEncryptedDataMsg (CERTC_CTX ctx, ITEM *data, ALGORITHM_IDENTIFIER *encryptAlgorithmId, B_KEY_OBJ encryptionKey, ATTRIBUTES_OBJ reserved, ITEM *encryptedDataMsg)
 Prepares an encrypted data message. More...

int C_ReadDataMsg (CERTC_CTX ctx, ITEM *dataMsg, ITEM *data)
 Takes a CMS Data-Type message and extracts the encapsulated data. More...

int C_ReadSignedDataMsg (CERTC_CTX ctx, CERT_PATH_CTX *pathCtx, SERVICE database, ITEM *signedDataMsg, UINT4 cmsOptions, ITEM *data, ITEM *oid, LIST_OBJ certificates, LIST_OBJ crls, LIST_OBJ verifiedSigners, LIST_OBJ unverifiedSigners)
 Checks a CMS Signed-Data message's signature, then extracts the encapsulated data, oid, certificates, crls, verifiedSigners, and unverifiedSigners information. More...

int C_ReadEnvelopedDataMsg (CERTC_CTX ctx, SERVICE database, ITEM *envelopedDataMsg, ITEM *data, ITEM *oid, RECIPIENT_INFO *recipientInfo, ALGORITHM_IDENTIFIER *contentEncryptionAlgorithmId, B_KEY_OBJ contentEncryptionKey, POINTER reserved1, ATTRIBUTES_OBJ reserved2)
 Decrypts a CMS Enveloped-Data message, and extracts the encapsulated data, recipientInfo, contentEncryptionAlgorithmId, and contentEncryptionKey. More...

int C_ReadDigestedDataMsg (CERTC_CTX ctx, ITEM *digestedDataMsg, ITEM *data, ITEM *oid)
 Decomposes a CMS Digested-Data message, and extracts the encapsulated data and oid. More...

int C_ReadEncryptedDataMsg (CERTC_CTX ctx, ITEM *encryptedDataMsg, B_KEY_OBJ decryptionKey, ITEM *data, ITEM *oid, ATTRIBUTES_OBJ reserved)
 Decomposes a CMS Encrypted-Data message, and extracts the encapsulated data and oid. More...

int C_AddSignerToList (LIST_OBJ listObject, SIGNER_INFO *signer, unsigned int *entryIndex)
 Adds a copy of a signer to the specified list object. More...

int C_InsertSignerInList (LIST_OBJ listObject, SIGNER_INFO *signer, unsigned int entryIndex)
 Inserts a copy of a signer into the specified list object at the given position. More...

int C_AddUniqueSignerToList (LIST_OBJ listObject, SIGNER_INFO *signer, unsigned int *entryIndex)
 Adds a copy of a signer to the specified list object. More...

void C_FreeSignerEntry (SIGNER_INFO **value)
 Destroys a SIGNER_INFO data structure and its members, and sets the pointer to NULL_PTR. More...

void C_FreeSignerInfo (SIGNER_INFO *value)
 Destroys a SIGNER_INFO data structure's members and frees the associated memory. More...

int C_AddRecipientToList (LIST_OBJ listObject, RECIPIENT_INFO *recipient, unsigned int *entryIndex)
 Adds a copy of a recipient to the specified list object. More...

int C_InsertRecipientInList (LIST_OBJ listObject, RECIPIENT_INFO *recipient, unsigned int entryIndex)
 Inserts a copy of a recipient into the specified list object at the given position. More...

int C_AddUniqueRecipientToList (LIST_OBJ listObject, RECIPIENT_INFO *recipient, unsigned int *entryIndex)
 Adds a copy of a recipient to the specified list object. More...

void C_FreeRecipientEntry (RECIPIENT_INFO **value)
 Destroys a RECIPIENT_INFO data structure and its members, and sets the pointer to NULL_PTR. More...

void C_FreeRecipientInfo (RECIPIENT_INFO *value)
 Destroys a RECIPIENT_INFO data structure's members and frees the associated memory. More...

Function Documentation

int C_AddRecipientToList (  LIST_OBJ    listObject,
RECIPIENT_INFO *    recipient,
unsigned int *    entryIndex
)  ;
 

Adds a copy of a recipient to the specified list object. Duplicate list entries are permitted.

Parameters:
listObject This is both an input and an output parameter. As an input parameter, it is the list object that Cert-C updates with a copy of the recipient information. As an output parameter, it is the updated list.
recipient This input parameter is the recipient to add to the list object.
entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_AddSignerToList (  LIST_OBJ    listObject,
SIGNER_INFO *    signer,
unsigned int *    entryIndex
)  ;
 

Adds a copy of a signer to the specified list object. Duplicate list entries are permitted.

Parameters:
listObject This is both an input and an output parameter. As an input parameter, it is the list object that Cert-C should update with a copy of the signer information. As an output parameter, it is the updated list.
signer This input parameter is the signer to add to the list object.
entryIndex This output parameter is the index of the newly added list entry. If this parameter is (unsigned int *)0, it is ignored.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_AddUniqueRecipientToList (  LIST_OBJ    listObject,
RECIPIENT_INFO *    recipient,
unsigned int *    entryIndex
)  ;
 

Adds a copy of a recipient to the specified list object. If the recipient to add is not in the list, this function adds it. This function does not add the recipient if the recipient is on the list already. Duplicate list entries (which are determined by matching issuer names and serial numbers) are not permitted.

Parameters:
listObject This is both an input and an output parameter. As an input parameter, it is the list object that Cert-C updates with a copy of the recipient information. As an output parameter, it is the updated list.
recipient This input parameter is the recipient to add to the list object.
entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_AddUniqueSignerToList (  LIST_OBJ    listObject,
SIGNER_INFO *    signer,
unsigned int *    entryIndex
)  ;
 

Adds a copy of a signer to the specified list object. If the signer to add is not in the list, this function adds it. This function does not add the signer if the signer is on the list already. Duplicate list entries (which are determined by matching issuer names and serial numbers) are not permitted.

Parameters:
listObject This is both an input and an output parameter. As an input parameter, it is the list object that Cert-C updates with a copy of the signer information. As an output parameter, it is the updated list.
signer This input parameter is the signer to add to the list object.
entryIndex This output parameter is the index of the newly added list entry. If this parameter is (unsigned int *)0, it is ignored.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

void C_FreeRecipientEntry (  RECIPIENT_INFO **    value )  ;
 

Destroys a RECIPIENT_INFO data structure and its members, and sets the pointer to NULL_PTR. If you do not want to destroy the RECIPIENT_INFO structure, use C_FreeRecipientInfo() instead.

Parameters:
value This is both an input and an output parameter. As an input parameter, it points to the recipient entry to be destroyed. As an output parameter, it is set to NULL_PTR.
Returns:
None.

void C_FreeRecipientInfo (  RECIPIENT_INFO *    value )  ;
 

Destroys a RECIPIENT_INFO data structure's members and frees the associated memory. This function does not destroy and free the RECIPIENT_INFO structure itself. To destroy both the contents and the structure, use C_FreeRecipientEntry() instead.

Parameters:
value This is both an input and an output parameter. As an input parameter, it is a pointer to a RECIPIENT_INFO structure. On output, all members are freed and set to 0 (zero).
Returns:
None.

void C_FreeSignerEntry (  SIGNER_INFO **    value )  ;
 

Destroys a SIGNER_INFO data structure and its members, and sets the pointer to NULL_PTR. If you do not want to destroy the SIGNER_INFO structure, use C_FreeSignerInfo() instead.

Parameters:
value This is both an input and output parameter. As an input parameter, it points to the signer entry to be destroyed. As an output parameter, it is set to NULL_PTR.
Returns:
None.

void C_FreeSignerInfo (  SIGNER_INFO *    value )  ;
 

Destroys a SIGNER_INFO data structure's members and frees the associated memory. This function does not destroy and free the SIGNER_INFO structure itself. To destroy both the contents and the structure, use C_FreeSignerEntry() instead.

Parameters:
value This is both an input and an output parameter. As an input parameter, it points to a SIGNER_INFO structure. As an output parameter, the members of the SIGNER_INFO structure are set to NULL_PTR.
Returns:
None.

int C_InsertRecipientInList (  LIST_OBJ    listObject,
RECIPIENT_INFO *    recipient,
unsigned int    entryIndex
)  ;
 

Inserts a copy of a recipient into the specified list object at the given position. Duplicate list entries are permitted.

Parameters:
listObject This is both an input and an output parameter. As an input parameter, it is the list object that Cert-C should update with a copy of a recipient. As an output parameter, it is the updated list.
recipient This input parameter is the recipient to add to the list object.
entryIndex This input parameter is the index of the position for the newly added list entry.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_InsertSignerInList (  LIST_OBJ    listObject,
SIGNER_INFO *    signer,
unsigned int    entryIndex
)  ;
 

Inserts a copy of a signer into the specified list object at the given position. Duplicate list entries are permitted. SIGNER_INFO is the data structure for the signer information.

Parameters:
listObject This is both an input and an output parameter. As an input parameter, it is the list object that Cert-C should update with a copy of a signer. As an output parameter, it is the updated list.
signer This input parameter is the signer to add.
entryIndex This input parameter is the index of the position for the newly added list entry.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ReadDataMsg (  CERTC_CTX    ctx,
ITEM *    dataMsg,
ITEM *    data
)  ;
 

Takes a CMS Data-Type message and extracts the encapsulated data.

Parameters:
ctx This input parameter is the initialized Cert-C context.
dataMsg This input parameter is the formatted CMS Data-Type message.
data This output parameter is the actual data value extracted from the data message. It is necessary to free the data to which this ITEM points.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ReadDigestedDataMsg (  CERTC_CTX    ctx,
ITEM *    digestedDataMsg,
ITEM *    data,
ITEM *    oid
)  ;
 

Decomposes a CMS Digested-Data message, and extracts the encapsulated data and oid.

Parameters:
ctx This input parameter is the initialized Cert-C context.
digestedDataMsg This input parameter is the CMS Digested-Data message to digest. You must free this data.
data This output parameter is the data extracted and digested from the CMS Digested-Data message. You must free the data to which this ITEM points.
oid This output parameter is the OID that indicates the type of the data extracted from the CMS Digested-Data message. Valid oid types are as follows:

CMS Object Identifier Type Length
CT_ID_DATA CT_ID_DATA_LEN
CT_ID_SIGNED_DATA CT_ID_SIGNED_DATA_LEN
CT_ID_ENVELOPED_DATA CT_ID_ENVELOPED_DATA_LEN
CT_ID_DIGESTED_DATA CT_ID_DIGESTED_DATA_LEN
CT_ID_ENCRYPTED_DATA CT_ID_ENCRYPTED_DATA_LEN
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ReadEncryptedDataMsg (  CERTC_CTX    ctx,
ITEM *    encryptedDataMsg,
B_KEY_OBJ    decryptionKey,
ITEM *    data,
ITEM *    oid,
ATTRIBUTES_OBJ    reserved
)  ;
 

Decomposes a CMS Encrypted-Data message, and extracts the encapsulated data and oid. Note that the encryption key and algorithm identifier are not included in the message. This information must be exchanged with the sender by other means.

Parameters:
ctx This input parameter is the initialized Cert-C context.
encryptedDataMsg This input parameter is the CMS Encrypted-Data message.
decryptionKey This input parameter is the key to decompose the data.
data This output parameter is the data extracted and decomposed from the CMS Encrypted Data message. You must free the data to which this ITEM points.
oid This output parameter is the OID that indicates the type of data extracted from the CMS Encrypted-Data message. Valid oid types are as follows:

CMS Object Identifier Type Length
CT_ID_DATA CT_ID_DATA_LEN
CT_ID_SIGNED_DATA CT_ID_SIGNED_DATA_LEN
CT_ID_ENVELOPED_DATA CT_ID_ENVELOPED_DATA_LEN
CT_ID_DIGESTED_DATA CT_ID_DIGESTED_DATA_LEN
CT_ID_ENCRYPTED_DATA CT_ID_ENCRYPTED_DATA_LEN

reserved This output parameter is reserved for future use. Pass an (ATTRIBUTES_OBJ)0 for this parameter.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ReadEnvelopedDataMsg (  CERTC_CTX    ctx,
SERVICE    database,
ITEM *    envelopedDataMsg,
ITEM *    data,
ITEM *    oid,
RECIPIENT_INFO *    recipientInfo,
ALGORITHM_IDENTIFIER *    contentEncryptionAlgorithmId,
B_KEY_OBJ    contentEncryptionKey,
POINTER    reserved1,
ATTRIBUTES_OBJ    reserved2
)  ;
 

Decrypts a CMS Enveloped-Data message, and extracts the encapsulated data, recipientInfo, contentEncryptionAlgorithmId, and contentEncryptionKey. The caller is responsible for allocating and freeing all memory used by the recipientInfo, contentEncryptionAlgorithmId, and contentEncryptionKey return variables.

Note: First, Cert-C searches the service specified by the database parameter for the recipient certificate used to encrypt the internal content-encryption key. This recipient certificate is then used to look up the private key needed to decrypt the internal content-encryption key. If the information is not found in database, Cert-C checks for the necessary information in the database referenced in the ctx context.

Parameters:
ctx This input parameter is the initialized Cert-C context. If the necessary information is not found in database, Cert-C checks the database referenced in this ctx context.
database This input parameter is the Cert-C database handle. Cert-C searches the service specified by database for the recipient certificates, which enable certificate-path verification, and for associated CRLs, which provide relevant revocation status.
envelopedDataMsg This input parameter is the CMS Enveloped-Data message to decrypt.
data This output parameter is the data extracted and decrypted from the CMS Enveloped-Data message. The application must free the data to which this ITEM points.
oid This output parameter is the object identifier that indicates the type of the data extracted from the CMS Enveloped-Data message. Valid oid types are as follows:

CMS Object Identifier Type Length
CT_ID_DATA CT_ID_DATA_LEN
CT_ID_SIGNED_DATA CT_ID_SIGNED_DATA_LEN
CT_ID_ENVELOPED_DATA CT_ID_ENVELOPED_DATA_LEN
CT_ID_DIGESTED_DATA CT_ID_DIGESTED_DATA_LEN
CT_ID_ENCRYPTED_DATA CT_ID_ENCRYPTED_DATA_LEN

recipientInfo This output parameter is a RECIPIENT_INFO structure that contains information about the recipient whose private key was used to encrypt the internal content-encryption key. The caller can use C_FreeRecipientInfo() to free the memory associated with the value.
contentEncryptionAlgorithmId This output parameter is the encryption algorithm used to encrypt the content. The calling function is responsible for allocating and freeing all memory. This is an optional parameter and may be NULL_PTR.
contentEncryptionKey This output parameter is the symmetric key used to encrypt the content. The calling function is responsible for allocating and freeing all memory. This is an optional parameter and may be NULL_PTR.
reserved1 This output parameter is reserved for future use. Pass a NULL_PTR for this parameter.
reserved2 This output parameter is reserved for future use. Pass a NULL_PTR for this parameter.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ReadMessageType (  CERTC_CTX    ctx,
ITEM *    cmsMsg,
ITEM *    oid
)  ;
 

Extracts the OID from a CMS-formatted message. This allows the application to determine the message type so the correct C_Read*DataMsg() function can be used.

Parameters:
ctx This input parameter is the initialized Cert-C context.
cmsMsg This input parameter is the CMS-formatted message from which oid is extracted.
oid This output parameter is the OID extracted from the CMS-formatted message. Valid oid types are as follows:

CMS Object Identifier Type Length
CT_ID_DATA CT_ID_DATA_LEN
CT_ID_SIGNED_DATA CT_ID_SIGNED_DATA_LEN
CT_ID_ENVELOPED_DATA CT_ID_ENVELOPED_DATA_LEN
CT_ID_DIGESTED_DATA CT_ID_DIGESTED_DATA_LEN
CT_ID_ENCRYPTED_DATA CT_ID_ENCRYPTED_DATA_LEN
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ReadSignedDataMsg (  CERTC_CTX    ctx,
CERT_PATH_CTX *    pathCtx,
SERVICE    database,
ITEM *    signedDataMsg,
UINT4    cmsOptions,
ITEM *    data,
ITEM *    oid,
LIST_OBJ    certificates,
LIST_OBJ    crls,
LIST_OBJ    verifiedSigners,
LIST_OBJ    unverifiedSigners
)  ;
 

Checks a CMS Signed-Data message's signature, then extracts the encapsulated data, oid, certificates, crls, verifiedSigners, and unverifiedSigners information. The caller is responsible for freeing the memory associated with data, certificates, crls, verifiedSigners, and unverifiedSigners.

Note: First, Cert-C searches the service specified by the database parameter for the signer certificates, which enable certificate-path verification, and for associated CRLs, which provide relevant revocation status. If the information is not found in database, Cert-C checks for the necessary information in the database referenced in the certificates object and then in the ctx context.

The function can put the signer in either the verifiedSigners or the unverifiedSigners LIST_OBJ. The following table shows the placement of the signer in different scenarios. The return value alone cannot be used to determine the location of the signer.

Cert found? Signature verified? Path validated? LIST_OBJ for Signer Returns
No N/A N/A unverifiedSigners E_NOT_FOUND
Yes No No unverifiedSigners E_VERIFY_ASN_SIGNATURE
Yes No Yes verifiedSigners E_VERIFY_ASN_SIGNATURE
Yes Yes No unverifiedSigners 0
Yes Yes Yes verifiedSigners 0

Note: "Path validated" means that the path from the trusted certificated to the signing certificate can be validated. If the cmsOptions parameter is set to CMSF_NONE, the path is not validated.

Parameters:
ctx This input parameter is the initialized Cert-C context. If the necessary information is not found in database, Cert-C checks the database referenced in this ctx context.
pathCtx This input parameter is the path-processing context. It is used to ensure that the constructed certificate path is valid. The pathCtx.pathOptions field can be used to request the appropriate level of checking during path construction.
database This input parameter is the Cert-C database handle. Cert-C searches the service specified by this database parameter for the signer certificates, which enable certificate-path verification, and for associated CRLs, which provide relevant revocation status.
signedDataMsg This input parameter is the CMS Signed-Data message.
cmsOptions This input parameter contains the CMS option flags. Valid values are as follows:

CMS Option Flag Description
CMSF_NONE No options specified.
CMSF_VERIFY_SIGNER_CERTS The SignedData extraction message processing should verify the revocation status and validate the certificate chain for each signer certificate.
CMSF_EXTERNAL_SIGNATURE Decode a signature-only message.

data This output parameter is the data extracted from the signed-data message. You must free the data to which this ITEM points. When cmsOptions is set to CMSF_NONE or CMSF_VERIFY_SIGNER_CERTS, this is an output parameter; it is the data extracted from the SignedData message. When cmsOptions is set to CMSF_EXTERNAL_SIGNATURE, this is an input parameter; it is the data used to compute the message digest against the recovered message digest in the message.
oid This output parameter is the OID, and points to memory that Cert-C manages. It indicates the type of data extracted from the signed-data message. Valid oid types are as follows:

CMS Object Identifier Type Length
CT_ID_DATA CT_ID_DATA_LEN
CT_ID_SIGNED_DATA CT_ID_SIGNED_DATA_LEN
CT_ID_ENVELOPED_DATA CT_ID_ENVELOPED_DATA_LEN
CT_ID_DIGESTED_DATA CT_ID_DIGESTED_DATA_LEN
CT_ID_ENCRYPTED_DATA CT_ID_ENCRYPTED_DATA_LEN

certificates This output parameter is the collection of certificates that is included in the message. These certificates do not include any certificate that is read from a database to verify the signers' certificate paths. These certificates are not added to the database.
crls This output parameter is the collection of CRLs that is included in the message. These CRLs do not include any CRL that is read from a database to verify the signers' certificate revocation status. These CRLs are not added to the database.
verifiedSigners This output parameter is a list of verified signer information. If cmsOption is CMSF_VERIFY_SIGNATURE, SIGNER_INFO is the structure in the LIST_OBJ that holds the per-signer information. Cert-C ignores this parameter if cmsOptions is CMSF_EXTERNAL_SIGNATURE or CMSF_NONE.
unverifiedSigners This output parameter is a list of unverified signer information. SIGNER_INFO is the structure in the LIST_OBJ that holds the per-signer information.
Returns:
If successful, returns 0. If not, returns a Cert-C error code. See the table above for more information on interpreting return values for this function.

int C_WriteDataMsg (  CERTC_CTX    ctx,
ITEM *    data,
ITEM *    dataMsg
)  ;
 

Prepares a simple data message. The output of this function is a correctly formatted CMS Data-Type message, which contains the ST_ID_DATA OID and the data.

Parameters:
ctx This input parameter is the initialized Cert-C context.
data This input parameter is the PKCS #7 data content to be encapsulated in the data message.
dataMsg This output parameter is the formatted CMS Data-Type message. It is the responsibility of the caller of this function to free the data to which this ITEM points.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_WriteDigestedDataMsg (  CERTC_CTX    ctx,
ITEM *    data,
int    digestAlgorithmId,
ITEM *    digestedDataMsg
)  ;
 

Prepares a digested data message. The output of this function is a properly formatted CMS Digested Data message.

Parameters:
ctx This input parameter is the initialized Cert-C context.
data This input parameter is the PKCS #7 data content to be digested and encapsulated in the CMS Digested-Data message. This is usually the output from one of the other CMS write functions, such as C_WriteDataMsg().
digestAlgorithmId This input parameter is the identifier for the algorithm to digest the data in the message. The following algorithms are supported: DAI_SHA1, DAI_MD5, DAI_MD2.
digestedDataMsg This output parameter is the formatted CMS Digested-Data message. Free the data to which this ITEM points.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_WriteEncryptedDataMsg (  CERTC_CTX    ctx,
ITEM *    data,
ALGORITHM_IDENTIFIER *    encryptAlgorithmId,
B_KEY_OBJ    encryptionKey,
ATTRIBUTES_OBJ    reserved,
ITEM *    encryptedDataMsg
)  ;
 

Prepares an encrypted data message. The output of this function is a correctly formatted CMS Encrypted-Data message. Note that the encryption key and algorithm identifier are not included in the message; the key and algorithm must be exchanged with the recipient by other means.

Parameters:
ctx This input parameter is the initialized Cert-C context.
data This input parameter is the PKCS #7 data content to be encrypted and encapsulated in the CMS Encrypted-Data message. This is usually the output from one of the other CMS write functions, such as C_WriteDataMsg().
encryptAlgorithmId This input parameter is the algorithm identifier for the algorithm used to encrypt the data in the message. The following algorithms are supported: EAI_RC2, EAI_RC4, EAI_RC5, EAI_DES3, EAI_DES.
encryptionKey This input parameter is the key used to encrypt the data in the message.
reserved This input parameter is reserved for future use. Pass a NULL pointer for this parameter.
encryptedDataMsg This output parameter is the formatted CMS Encrypted-Data message. Free the data to which this ITEM points.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_WriteEnvelopedDataMsg (  CERTC_CTX    ctx,
SERVICE    database,
ITEM *    data,
ALGORITHM_IDENTIFIER *    contentEncryptionAlgorithmId,
LIST_OBJ    recipientInfos,
B_KEY_OBJ    encryptionKey,
POINTER    reserved1,
ATTRIBUTES_OBJ    reserved2,
ITEM *    envelopedDataMsg
)  ;
 

Prepares an enveloped-data message. The output is a correctly formatted CMS Enveloped-Data message. If both contentEncryptionAlgorithmId and encryptionKey are (B_KEY_OBJ)0, Triple DES is the default algorithm used to encrypt the message data. If encryptionKey is (B_KEY_OBJ)0, encryptionKey is generated according to the input of contentEncryptionAlgorithmId. If encryptionKey is not (B_KEY_OBJ)0 but contentEncryptionAlgorithmId is (B_KEY_OBJ)0, C_WriteEnvelopedDataMsg() returns an error.

Note: First, Cert-C searches the service specified by the database parameter for the recipient certificate used to encrypt the internal content-encryption key. If the information is not found in database, Cert-C checks for the necessary information in the database referenced in the ctx context.

Parameters:
ctx This input parameter is the initialized Cert-C context. If the necessary information is not found in database, Cert-C checks the database referenced in this ctx context.
database This input parameter is the Cert-C database handle. Cert-C searches the service specified by this database parameter for the recipient or recipient certificates.
data This input parameter is the PKCS #7 data content to encrypt and encapsulate in the enveloped-data message. This is usually the output from one of the other CMS write functions, such as C_WriteDataMsg().
contentEncryptionAlgorithmId This is both an input and an output parameter; it is the identifier for the encryption algorithm used to encrypt the message data. The following algorithms are supported: EAI_DES3, EAI_RC2, EAI_DES, EAI_RC5, and EAI_RC4. If both contentEncryptionAlgorithmId and encryptionKey are (B_KEY_OBJ)0, Triple DES is the default algorithm used to encrypt the message data. If encryptionKey is (B_KEY_OBJ)0, encryptionKey is generated according to the input of contentEncryptionAlgorithmId. If encryptionKey is not (B_KEY_OBJ)0 but contentEncryptionAlgorithmId is NULL, C_WriteEnvelopedDataMsg() returns an error.
recipientInfos This input parameter is the LIST_OBJ of per-recipient RECIPIENT_INFO structures.
encryptionKey This is both an input and an output parameter; it is the key that is used to encrypt the data. If both contentEncryptionAlgorithmId and encryptionKey are 0, Triple DES is the default algorithm used to encrypt the message data. If encryptionKey is (B_KEY_OBJ)0, encryptionKey is generated according to the input of contentEncryptionAlgorithmId. If encryptionKey is not (B_KEY_OBJ)0 but contentEncryptionAlgorithmId is NULL, C_WriteEnvelopedDataMsg() returns an error.
reserved1 This input parameter is reserved for future use. Pass a NULL_PTR pointer for this parameter.
reserved2 This input parameter is reserved for future use. Pass a (ATTRIBUTES_OBJ)0 pointer for this parameter.
envelopedDataMsg This output parameter is the formatted CMS Enveloped-Data message. You must free the data to which this ITEM points.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_WriteSignedDataMsg (  CERTC_CTX    ctx,
CERT_PATH_CTX *    pathCtx,
SERVICE    database,
ITEM *    data,
UINT4    cmsOptions,
LIST_OBJ    certificates,
LIST_OBJ    crls,
LIST_OBJ    signers,
ITEM *    signedDataMsg
)  ;
 

Prepares a signed-data message. The output of this function is a correctly formatted CMS Signed-Data message. The data content to be signed must be a BER-encoded PKCS #7 message.

Note: If the data content to be signed is not a PKCS #7 data message, PKCS #7 states that the signed-data message must contain authenticated attributes with at least the contentType and messageDigest attributes present. In this case, Cert-C automatically adds these attributes. Whenever a SIGNER_INFO is present in the list of signers and the SIGNER_INFO.signedAttributes field is not set to (ATTRIBUTES_OBJ)NULL_PTR, Cert-C computes the needed values and adds the two mandatory attributes, contentType and messageDigest, to signedAttributes.
To create a detached signature, set the CMSF_EXTERNAL_SIGNATURE option. A certificates-only or CRLs-only message can be created by passing in a (LIST_OBJ)0 signers parameter and a NULL data parameter.

Note: First, Cert-C searches the service specified by the database parameter for the signer certificates, which enable certificate-path verification, and for associated CRLs, which provide relevant revocation status. If the information is not found in database, Cert-C checks for the necessary information in the database referenced in the certificates object and then in the ctx context.

Parameters:
ctx This input parameter is the initialized Cert-C context. If the necessary information is not found in database, Cert-C checks the database referenced in this ctx context.
pathCtx This input parameter is the path-processing context. It is used to ensure that the constructed certificate path is valid. Use the pathCtx.pathOptions field to request the appropriate level of checking during path construction.
database This input parameter is the Cert-C database handle. Cert-C searches the service specified by this database parameter for the signer certificates, which enable certificate-path verification, and for associated CRLs, which provide relevant revocation status.
data This input parameter is the data content to be signed and, optionally, encapsulated in the signed-data message. The data content to be signed must be a BER-encoded PKCS #7 message; for example, the data can be a PKCS #7 Data message or a PKCS #7 Enveloped-Data message. This is an optional parameter and can be set to (ITEM *)0.
cmsOptions This input parameter is the CMS option flag. Valid values for this flag are as follows:

CMS Option Flag Description
CMSF_NONE No options specified.
CMSF_EXTERNAL_SIGNATURE Causes the Signed-Data message processing to format a message that does not include any data content, which enables the creation of a detached or external signature.
CMSF_INCLUDE_CERTS Causes the Signed-Data message processing to build certificate paths to a trusted root by searching the databases for required certificates and including these certificates in the set of certificates in the message.
CMSF_INCLUDE_CRLS Causes the Signed-Data message processing to include relevant CRLs by searching the databases for the latest CRLs for each certificate in the certificate list and including these CRLs in the set of CRLs in the message.
CMSF_VERIFY_SIGNER_CERTS Causes the Signed-Data extraction message processing to verify the revocation status and validate the certificate chain for each signer certificate.
CMSF_EXCLUDE_SIGNER_CERT Causes the Signed-Data message processing not to include signer certificate in the message. By default, the signer certificate is included in the message.

certificates This input parameter is a LIST_OBJ of certificates to be included in the CMS Signed-Data message. This LIST_OBJ can contain the certificates that are required to build a chain from recognized roots to all of the signers of the message. It can contain either more or fewer certificates than necessary to perform chaining. This is an optional parameter and can be set to (LIST_OBJ)0.
crls This input parameter is a LIST_OBJ of certificate revocation lists. This set of CRLs can contain sufficient information to determine whether or not the certificates in the certificates parameter are valid. This is an optional parameter and can be set to (LIST_OBJ)0.
signers This input parameter is the LIST_OBJ of per-signer SIGNER_INFO structures. This is an optional parameter and can be set to (LIST_OBJ)0.

Note: When the data content to be signed is not a PKCS #7 data message and a SIGNER_INFO is present in the list of signers, then if the SIGNER_INFO.signedAttributes field is not set to (ATTRIBUTES_OBJ)0, Cert-C computes the needed values and adds the two mandatory attributes, contentType and messageDigest, to signedAttributes.
signedDataMsg This output parameter is the formatted CMS Signed-Data message. The application must free the data to which this ITEM points.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.


RSA BSAFE® Cert-C 2.7 API Reference