RSA BSAFE Cert-C API Reference

cmsobj.h File Reference

#include "basetype.h"
#include "cms.h"

Go to the source code of this file.

Defines
#define	C_CMS_IO_FLAGS_COMPLETE
	Flag(s) for use with C_ReadCMSMessage() and C_WriteCMSMessage().
Typedefs
typedef POINTER	C_CMS_OBJ
	Represents a CMS message object. More...
Functions
int	C_CreateCMSObject (CERTC_CTX ctx, C_CMS_OBJ *pCMSObj)
	Creates a new CMS message object and stores the result in pCMSObj. More...
void	C_DestroyCMSObject (C_CMS_OBJ *pCMSObj)
	Destroys a CMS message object and frees its associated memory. More...
int	C_SetCMSMessageType (C_CMS_OBJ cmsObj, C_CMS_MSG_TYPE msgType)
	Sets the CMS message type. More...
int	C_GetCMSMessageType (C_CMS_OBJ cmsObj, C_CMS_MSG_TYPE *pMsgType, ITEM *pOID)
	Gets the message type of a CMS message object. More...
int	C_ReadCMSMessage (C_CMS_OBJ cmsObj, unsigned int maxReadLen, unsigned char *pData, unsigned int *pDataLen, UINT4 *pFlags)
	Reads up to maxReadLen bytes from a CMS message object. More...
int	C_WriteCMSMessage (C_CMS_OBJ cmsObj, unsigned char *pData, unsigned int dataLen, UINT4 flags)
	Writes (adds) data into a CMS message object. More...
int	C_GetCMSInnerDataContentType (C_CMS_OBJ cmsObj, C_CMS_MSG_TYPE *pContentType, ITEM *pOID)
	Gets the message (content) type of encapsulated data within a CMS message object. More...
int	C_GetCMSRecipients (C_CMS_OBJ cmsObj, LIST_OBJ *pRecipientList)
	Gets the list of RECIPIENT_INFO for which an EnvelopedData message has been composed. More...
int	C_AddCMSRecipient (C_CMS_OBJ cmsObj, RECIPIENT_INFO *pRecipient)
	Adds a RECIPIENT_INFO to the list of recipients of an EnvelopedData message. More...

Typedef Documentation

typedef POINTER C_CMS_OBJ

Represents a CMS message object. The following restrictions apply to all interface functions: C_CMS_VERSION can only be CMS_VERSION_V0 for CMS message decoding, and can only be encoded as CMS_VERSION_V0. RECPIENT_INFOs present in the RecipientList have only the existing choices with the original CMS/PKCS#7 API, namely KeyTransport as the RecipientInfo type, and using IssuerSerial for the RecipientIdentifier. KeyEncryptionIdentifiers is limited to RSA encryption. ContentEncryptionAlgorithms is limited to Triple-DES. See cms.h for the existing datatypes for PKCS#7 functionality. Encapsulation of CMS datatypes other than "Data" is not currently supported in EnvelopedData messages for either composition or decomposition of messages.

Function Documentation

int C_AddCMSRecipient (  C_CMS_OBJ    cmsObj, RECIPIENT_INFO *    pRecipient )  ;

Adds a RECIPIENT_INFO to the list of recipients of an EnvelopedData message. If, at the time that this call is made, a certificate cannot be found in the object's retained Cert-C context, E_NOT_FOUND will be returned. When composing an EnvelopedData message, at least one recipient must be set before any data is read from or written to this object. Parameters: cmsObj This input parameter specifies the CMS message object. pRecipient This input parameter is a pointer to a RECIPIENT_INFO. The caller may reuse the memory for this data structure after this call is complete. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_CreateCMSObject (  CERTC_CTX    ctx, C_CMS_OBJ *    pCMSObj )  ;

Creates a new CMS message object and stores the result in pCMSObj. If unsuccessful, no memory is allocated, pCMSObj is set to (C_CMS_OBJ)0, and E_ALLOC is returned. The default value for the CMS message version is CMS_VERSION_V0. Parameters: ctx This input parameter is the Cert-C context. pCMSObj This output parameter points to the newly created CMS message object. It keeps an internal reference to the current Cert-C context. Returns: If successful, returns 0. If not, returns a Cert-C error code.

void C_DestroyCMSObject (  C_CMS_OBJ *    pCMSObj )  ;

Destroys a CMS message object and frees its associated memory. It sets pCMSObj to (C_CMS_OBJ)0. If pCMSObj is already (C_CMS_OBJ)0, then no action is taken. Parameters: pCMSObj This is both an input and an output parameter. As an input parameter, it is the CMS message object that Cert-C should destroy. As an output parameter, it is (C_CMS_OBJ)0. Returns: None.

int C_GetCMSInnerDataContentType (  C_CMS_OBJ    cmsObj, C_CMS_MSG_TYPE *    pContentType, ITEM *    pOID )  ;

Gets the message (content) type of encapsulated data within a CMS message object. This function must be used when the content type of data being read from a CMS object is not known in advance. An additional C_CMS_OBJ must be created to decode the data stream further, if the transported nested content is a different CMS datatype. This function should be called only when decoding a CMS message. If the encapsulated data type is not yet known because not enough of the input data stream has been parsed, the Cert-C error E_VALUE_NOT_SET will be returned. Later in the decoding process, a definitive value can be retrieved using this call. Parameters: cmsObj This input parameter specifies the CMS message object. pContentType This output parameter specifies the content type of the encapsulated message. pOID This output parameter specifies the OID of the type of the encapsulated message. This information is useful if *pContentType is C_CMS_MSGTYPE_UNRECOGNIZED; that is, not one of the CMS-defined data types. This data should not be modified or freed by the caller. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_GetCMSMessageType (  C_CMS_OBJ    cmsObj, C_CMS_MSG_TYPE *    pMsgType, ITEM *    pOID )  ;

Gets the message type of a CMS message object. Parameters: cmsObj This input parameter specifies the CMS message object. pMsgType This output parameter specifies the message type to retrieve. pOID This output parameter specifies the OID of the type of the CMS message. This data should not be modified or freed by the caller. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_GetCMSRecipients (  C_CMS_OBJ    cmsObj, LIST_OBJ *    pRecipientList )  ;

Gets the list of RECIPIENT_INFO for which an EnvelopedData message has been composed. Parameters: cmsObj This input parameter specifies the CMS message object. pRecipientList This output parameter contains a LIST_OBJ of RECIPIENT_INFO data structures in the CMS message. This data structure is owned by the toolkit and should not be modified or destroyed. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_ReadCMSMessage (  C_CMS_OBJ    cmsObj, unsigned int    maxReadLen, unsigned char *    pData, unsigned int *    pDataLen, UINT4 *    pFlags )  ;

Reads up to maxReadLen bytes from a CMS message object. End of input is signaled by the presence of the CMS_IO_FLAGS_COMPLETE bit in *pFlags. Periodic reading of data may be desirable to limit the amount of data buffered within the object. After data is read, it is no longer contained in the CMS object. Data may not always be available for reading at all times prior to message completion -- a call returning pDataLen equal to zero does not signify end-of-data, but rather that no data is available for reading at this time (more data must be made available by adding data with C_WriteCMSMessage). Calls to this API for reading after a previous call has indicated CMS_IO_FLAGS_COMPLETE will result in an error. Data read from a C_CMS_OBJ of type C_CMS_MSGTYPE_ENVELOPED_DATA returns clear and unencapsulated data if the inner encapsulation is of type C_CMS_MSGTYPE_DATA. Parameters: cmsObj This input parameter specifies the CMS message object. maxReadLen This input parameter specifies the size of the buffer pointed to by pData. No more than maxReadLen bytes will be returned in pData. pData This input/output parameter specifies the buffer where the retrieved data from the CMS message object is stored. pDataLen This output parameter is the address of the variable to recieve the number of bytes actually put into the buffer specified by pData. pFlags This output parameter specifies zero or more CMS_IO_FLAGS_* bits of condition information. As of this release, only the CMS_IO_FLAGS_COMPLETE bit has been defined. It denotes that no more data may be read and that the message is complete. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_SetCMSMessageType (  C_CMS_OBJ    cmsObj, C_CMS_MSG_TYPE    msgType )  ;

Sets the CMS message type. This API is used when composing CMS messages. Changing an existing object from one defined type to another is not supported. Parameters: cmsObj This input/output parameter specifies the message object. msgType This input parameter specifies the message type to set. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_WriteCMSMessage (  C_CMS_OBJ    cmsObj, unsigned char *    pData, unsigned int    dataLen, UINT4    flags )  ;

Writes (adds) data into a CMS message object. The final write into the object must be signaled by the presence of the CMS_IO_FLAGS_COMPLETE bit in flags. Calls to this API after the CMS_IO_FLAGS_COMPLETE flag has been set will result in an error. The first call to this API is the indication that all other C_CMS_OBJ setup has been completed. For example, for C_CMS_OBJ of type C_CMS_MSGTYPE_ENVELOPED_DATA, the setup is complete when one or more RECIPIENT_INFOs have been added by calling C_AddCMSRecipient. If no message recipients have been added before this API is called, an error will result because an EnvelopedData message with no recipients is not valid. If the C_CMS_OBJ is C_CMS_MSGTYPE_ENVELOPED_DATA and is encapsulating a C_CMS_MSGTYPE_DATA, then the information to envelope should be the plaintext, and not a CMS Data message. This eliminates the need for two objects to envelope plain text. The default inner content type of a C_CMS_MSGTYPE_ENVELOPED_DATA object is C_CMS_MSGTYPE_DATA. Parameters: cmsObj This input parameter specifies the CMS message object into which data should be written. pData This input parameter specifies the buffer of data to write (add) into the CMS message object. dataLen This input parameter is the number of bytes of data in the buffer specified by pData. flags This input parameter specifies zero or more CMS_IO_FLAGS_* bits of condition information. As of this release, only the CMS_IO_FLAGS_COMPLETE bit has been defined. It denotes that no more data content will be provided and that message composition should be finalized. Returns: If successful, returns 0. If not, returns a Cert-C error code.