	RSA BSAFE Cert-C	Certificate Components for C
		Crypto-C 6.2.1 Developer's Guide
		Search

cms.h File Reference

This file contains the data structures and functions required 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 issuer name and serial number. More...

struct ISSUER_SERIAL_NUMBER

Uniquely identifies a certificate by the Distinguished Name (DN) 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 associated with a single recipient of a CMS message (supported) or a PKI message (deprecated). More...

struct SIGNER_INFO

Contains message signer information, including information associated with a single signer of a CMS message (supported) or a PKI message (deprecated). 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 if it is not in the list. 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 if it is not in the list. 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 [In, Out] 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 [In] The recipient to add to the list object.

entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.

Returns:
0 indicates success.
See Errors for error information.
Samples:
datamsg.c, and p7stream.c.

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 [In, Out] 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 [In] The signer to add to the list object.

entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is (unsigned int *)0.

Returns:
0 indicates success.
See Errors for error information.
Samples:
datamsg.c, mscapicert.c, and pkcs11msg.c.

int C_AddUniqueRecipientToList ( LIST_OBJ listObject,

RECIPIENT_INFO * recipient,

unsigned int * entryIndex

) ;

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

listObject [In, Out] 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 [In] The recipient to add to the list object.

entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.

Returns:
0 indicates success.
See Errors for error information.

int C_AddUniqueSignerToList ( LIST_OBJ listObject,

SIGNER_INFO * signer,

unsigned int * entryIndex

) ;

Adds a copy of a signer to the specified list object if it is not in the list. It 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 [In, Out] 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 [In] The signer to add to the list object.

entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is (unsigned int *)0.

Returns:
0 indicates success.
See Errors for error information.

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 [In, Out] As an input parameter, it points to the recipient entry to be destroyed. As an output parameter, it is set to NULL_PTR.

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().
Parameters:

value [In, Out] As an input parameter, it is a pointer to a RECIPIENT_INFO structure. On output, all members are freed and set to 0 (zero).

Samples:
datamsg.c.

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 [In, Out] 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().
Parameters:

value [In, Out] 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 [In, Out] 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 [In] The recipient to add to the list object.

entryIndex [In] The index of the position for the newly added list entry.

Returns:
0 indicates success.
See Errors for error information.

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 [In, Out] 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 [In] The signer to add.

entryIndex [In] The index of the position for the newly added list entry.

Returns:
0 indicates success.
See Errors for error information.

int C_ReadDataMsg ( CERTC_CTX ctx,

ITEM * dataMsg,

ITEM * data

) ;

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

ctx [In] The initialized Cert-C context.

dataMsg [In] The formatted CMS Data-Type message.

data [Out] The data value extracted from the data message. Free the data to which this ITEM points.

Returns:
0 indicates success.
See Errors for error information.
Samples:
datamsg.c.

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 [In] The initialized Cert-C context.

digestedDataMsg [In] The CMS Digested-Data message to digest. You must free this data.

data [Out] The data extracted and digested from the CMS Digested-Data message. Free the data to which this ITEM points.

oid [Out] 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:
0 indicates success.
See Errors for error information.
Samples:
datamsg.c.

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 [In] The initialized Cert-C context.

encryptedDataMsg [In] The CMS Encrypted-Data message.

decryptionKey [In] The key to decompose the data.

data [Out] The data extracted and decomposed from the CMS Encrypted Data message. Free the data to which this ITEM points.

oid [Out] 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 Reserved for future use. Pass an (ATTRIBUTES_OBJ)0 for this parameter.

Returns:
0 indicates success.
See Errors for error information.
Samples:
datamsg.c.

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.
Cert-C first 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 [In] 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 [In] 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 [In] The CMS Enveloped-Data message to decrypt.

data [Out] The data extracted and decrypted from the CMS Enveloped-Data message. The application must free the data to which this ITEM points.

oid [Out] 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 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 [Out] 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 [Out] 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 [Out] Reserved for future use. Pass a NULL_PTR for this parameter.

reserved2 [Out] Reserved for future use. Pass a NULL_PTR for this parameter.

Returns:
0 indicates success.
See Errors for error information.
Samples:
datamsg.c.

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 [In] The initialized Cert-C context.

cmsMsg [In] The CMS-formatted message from which oid is extracted.

oid [Out] 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:
0 indicates success.
See Errors for error information.
Samples:
datamsg.c.

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 verifySigners,

LIST_OBJ unVerifySigners

) ;

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.
Cert-C first 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

Parameters:

ctx [In] 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 [In] 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 [In] 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 [In] The CMS Signed-Data message.

cmsOptions [In, Out] 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 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 [Out] The OID, which 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 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 [Out] 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.

verifySigners [Out] 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.

unVerifySigners [Out] A list of unverified signer information. SIGNER_INFO is the structure in the LIST_OBJ# that holds the per-signer information.

Returns:
0 indicates success.
See Errors for error information. See the table above for more information on interpreting return values for this function.

"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.
Samples:
datamsg.c, and extract.c.

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 [In] The initialized Cert-C context.

data [In] The PKCS #7 data content to be encapsulated in the data message.

dataMsg [Out] 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:
0 indicates success.
See Errors for error information.
Samples:
certsonly.c, datamsg.c, mscapicert.c, p7stream.c, and pkcs11msg.c.

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 [In] The initialized Cert-C context.

data [In, Out] The PKCS #7 data content to digest and encapsulate in the CMS Digested-Data message. This is usually the output from one of the other CMS write functions, such as C_WriteDataMsg().

digestAlgorithmId [In] The identifier for the algorithm to digest the data in the message. The following algorithms are supported:

DAI_SHA1
DAI_MD5
DAI_MD2.

digestedDataMsg [Out] The formatted CMS Digested-Data message. Free the data to which this ITEM points.

Returns:
0 indicates success.
See Errors for error information.
Samples:
datamsg.c.

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. 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 [In] The initialized Cert-C context.

data [In, Out] The PKCS #7 data content to encrypt and encapsulate in the CMS Encrypted-Data message. This is usually the output from one of the other CMS write functions, such as C_WriteDataMsg().

encryptAlgorithmId [In] The 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 [In] The key used to encrypt the data in the message.

reserved [In] Reserved for future use. Pass a NULL pointer.

encryptedDataMsg [Out] The formatted CMS Encrypted-Data message. Free the data to which this ITEM points.

Returns:
0 indicates success.
See Errors for error information.
Samples:
datamsg.c.

int C_WriteEnvelopedDataMsg ( CERTC_CTX ctx,

SERVICE database,

ITEM * data,

ALGORITHM_IDENTIFIER * contentEncryptionAlgorithmId,

LIST_OBJ recipientInfosList,

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, this function returns an error.
Cert-C first searches the service specified by 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 [In] 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 [In] The Cert-C database handle. Cert-C searches the service specified by this database parameter for the recipient or recipient certificates.

data [In, Out] 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 [In, Out] 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.

recipientInfosList [In] The LIST_OBJ of per-recipient RECIPIENT_INFO structures.

encryptionKey [In, Out] 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 [In] Reserved for future use. Pass a NULL_PTR pointer for this parameter.

reserved2 [In] Reserved for future use. Pass a (ATTRIBUTES_OBJ)0 pointer for this parameter.

envelopedDataMsg [Out] The formatted CMS Enveloped-Data message. You must free the data to which this ITEM points.

Returns:
0 indicates success.
See Errors for error information.
Samples:
datamsg.c, and p7stream.c.

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.

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.

Cert-C first 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 [In, Oout] 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 [In] 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 [In] 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 [In] The data content to sign and, optionally, encapsulate 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 [In] 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 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 [In] 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 [In] The LIST_OBJ of per-signer SIGNER_INFO structures. This is an optional parameter and can be set to (LIST_OBJ)0.

signedDataMsg [Out] The formatted CMS Signed-Data message. The application must free the data to which this ITEM points.

Returns:
0 indicates success.
See Errors for error information.

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.
Samples:
certsonly.c, datamsg.c, mscapicert.c, and pkcs11msg.c.

Data Structures
struct	CERT_IDENTIFIER
	Identifies a certificate by the issuer name and serial number. More...
struct	ISSUER_SERIAL_NUMBER
	Uniquely identifies a certificate by the Distinguished Name (DN) 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 associated with a single recipient of a CMS message (supported) or a PKI message (deprecated). More...
struct	SIGNER_INFO
	Contains message signer information, including information associated with a single signer of a CMS message (supported) or a PKI message (deprecated). 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 if it is not in the list. 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 if it is not in the list. 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...