Header file for the Digicert SoT Platform API for Cryptographic Message Syntax (CMS) support. More...

Data Structures
struct	MOC_CMS_IssuerSerialNumber
	The 'issuer' and 'serial number' of a certificate. More...

struct	MOC_CMS_KeyAgreeRecipientId
	The 'RecipientId' structure for the 'KeyAgree' type. More...

struct	MOC_CMS_KeyTransRecipientId
	The 'RecipientId' structure for the 'KeyTrans' type. More...

struct	MOC_CMS_MsgSignInfo
	The 'signer info' structure. More...

struct	MOC_CMS_OriginatorPublicKey
	The 'originatorKey' of a certificate, as defined in RFC-5652 for the 'KeyAgreeRecipientInfo' sequence. More...

struct	MOC_CMS_RecipientId
	The general 'RecipientId' structure for all CMS recipient data. More...

struct	MOC_CMS_SubjectKeyIdentifier
	The 'SubjectKeyIdentifier' of a certificate. More...

Macros
#define	MOC_CMS_signerID_ALL (-1)

#define	NO_TAG (0xFFFFFFFF)

Typedefs
typedef void *	MOC_CMS_context

typedef MSTATUS(*	MOC_CMS_GetCertificate) (const void arg, ubyte pSerialNumber, ubyte4 serialNumberLen, ubyte pIssuer, ubyte4 issuerLen, ubyte ppCertificate, ubyte4 pCertificateLen)
	Callback type when the CMS engine needs the public certificate data identified by the given serial number and issuer name. More...

typedef MSTATUS(*	MOC_CMS_GetPrivateKey) (const void arg, ubyte pSerialNumber, ubyte4 serialNumberLen, ubyte pIssuer, ubyte4 issuerLen, struct AsymmetricKey pKey)
	Callback type when the CMS engine needs the private key data identified by the given serial number and issuer name, found in the public certificate data included in the CMS message. More...

typedef MSTATUS(*	MOC_CMS_GetPrivateKeyEx) (const void arg, const MOC_CMS_RecipientId pRecipientId, struct AsymmetricKey *pKey)
	Callback type when the CMS engine needs the private key data identified by the given MOC_CMS_RecipientId instance, found in the public certificate data included in the CMS message. More...

typedef sbyte4	MOC_CMS_signerID
	The type for a signer's ID value. More...

typedef MSTATUS(*	MOC_CMS_UpdateData) (const void arg, MOC_CMS_context pCtx, MOC_CMS_UpdateType type, ubyte pBuf, ubyte4 bufLen)
	Callback type when the CMS engine has acquired payload data and intends to pass it on to user code. More...

typedef MSTATUS(*	MOC_CMS_ValidateRootCertificate) (const void arg, ubyte pCertificate, ubyte4 certificateLen, MOC_CMS_MsgSignInfo *pSigInfo)
	Callback type when the CMS engine needs to validate a certificate with the user. More...

Enumerations
enum	MOC_CMS_action { E_MOC_CMS_sa_none = 0, E_MOC_CMS_sa_addCert = 1 }
	Action type when adding a certificate to the output CMS. More...

enum	MOC_CMS_ContentType { E_MOC_CMS_ct_undetermined = 0, E_MOC_CMS_ct_data = 1, E_MOC_CMS_ct_signedData = 2, E_MOC_CMS_ct_envelopedData = 3, E_MOC_CMS_ct_signedAndEnvelopedData = 4, E_MOC_CMS_ct_digestedData = 5, E_MOC_CMS_ct_encryptedData = 6, E_MOC_CMS_ct_authData = 102, E_MOC_CMS_ct_invalid = 999 }
	Content type of a received or created CMS. More...

enum	MOC_CMS_UpdateType { E_MOC_CMS_ut_invalid = 0, E_MOC_CMS_ut_update = 1, E_MOC_CMS_ut_final = 2, E_MOC_CMS_ut_result = 3 }
	Payload update type. More...

Functions
MOC_EXTERN MSTATUS	MOC_CMS_addCertificate (MOC_CMS_context context, ubyte *pCert, ubyte4 certLen)
	Add a certificate to the CMS output context. More...

MOC_EXTERN MSTATUS	MOC_CMS_addCRL (MOC_CMS_context context, ubyte *pCRL, ubyte4 CRLLen)
	Add a certificate revocation list to the CMS output context. More...

MOC_EXTERN MSTATUS	MOC_CMS_addDigest (MOC_CMS_context context, const ubyte *digestAlgoOID, ubyte4 digestAlgoOIDLen)
	Add a digest to the CMS output context, should it not exits. More...

MOC_EXTERN MSTATUS	MOC_CMS_addRecipient (MOC_CMS_context context, const ubyte *pCert, ubyte4 certLen)
	Add a 'recipient' to the CMS output context. More...

MOC_EXTERN MSTATUS	MOC_CMS_addSignatureRaw (MOC_CMS_context context, const ubyte *pSig, ubyte4 sigLen)
	Add a 'raw' signature to the CMS output context. More...

MOC_EXTERN MSTATUS	MOC_CMS_addSigner (MOC_CMS_context context, ubyte pCert, ubyte4 certLen, const AsymmetricKey pKey, const ubyte pDigestAlgoOID, ubyte4 digestAlgoOIDLen, MOC_CMS_action action, MOC_CMS_signerID pSignID)
	Add a 'signer' to the CMS output context. More...

MOC_EXTERN MSTATUS	MOC_CMS_addSignerAttribute (MOC_CMS_context context, MOC_CMS_signerID signId, const ubyte idOID, ubyte4 oidLen, ubyte4 typeID, const ubyte value, ubyte4 valueLen, intBoolean authenticated)
	Add an attribute to the CMS output context. More...

MOC_EXTERN MSTATUS	MOC_CMS_addUnprotectedAttribute (MOC_CMS_context context, const ubyte idOID, ubyte4 oidLen, ubyte4 typeID, const ubyte value, ubyte4 valueLen)
	Add an attribute to the CMS output context. More...

MOC_EXTERN MSTATUS	MOC_CMS_deleteContext (MOC_CMS_context *pContext)
	Delete the context. More...

MOC_EXTERN MSTATUS	MOC_CMS_deleteRecipientId (MOC_CMS_RecipientId *pRecipient)
	Delete an instance of 'MOC_CMS_RecipientId'. More...

MOC_EXTERN MSTATUS	MOC_CMS_deleteSignerInfo (MOC_CMS_MsgSignInfo *pSigner)
	Delete an instance of 'MOC_CMS_MsgSignInfo'. More...

MOC_EXTERN MSTATUS	MOC_CMS_finalizeContextOut (MOC_CMS_context context)
	Finalize CMS output and flush all data. More...

MOC_EXTERN MSTATUS	MOC_CMS_getCallbacks (MOC_CMS_context context, MOC_CMS_Callbacks *pCB)
	Return the values inside the callback structure. More...

MOC_EXTERN MSTATUS	MOC_CMS_getCertificates (MOC_CMS_context context, const ubyte *ppCerts, ubyte4 pCertLen)
	Return the certificates inside the CMS data context. More...

MOC_EXTERN MSTATUS	MOC_CMS_getContentType (MOC_CMS_context context, MOC_CMS_ContentType *cmsContentType)
	Return the value of type 'CMS_ContentType'. More...

MOC_EXTERN MSTATUS	MOC_CMS_getCRLs (MOC_CMS_context context, const ubyte *ppCRLs, ubyte4 pCRLsLen)
	Return the CRLs inside the CMS data context. More...

MOC_EXTERN MSTATUS	MOC_CMS_getDigestID (MOC_CMS_context context, ubyte4 idx, const ubyte **pDigestAlgoOID)
	Return the OID value for a digest, if applicable. More...

MOC_EXTERN MSTATUS	MOC_CMS_getNumDigests (MOC_CMS_context context, ubyte4 *pNumDigests)
	Return the number of digests, if applicable. More...

MOC_EXTERN MSTATUS	MOC_CMS_getNumRecipients (MOC_CMS_context context, sbyte4 *pNumRecipients)
	Return the number of recipients, if applicable. More...

MOC_EXTERN MSTATUS	MOC_CMS_getNumSignatures (MOC_CMS_context context, sbyte4 *pNumSigs)
	Return the number of signatures, if applicable. More...

MOC_EXTERN MSTATUS	MOC_CMS_getNumSigners (MOC_CMS_context context, sbyte4 *pNumSigners)
	Return the number of signers, if applicable. More...

MOC_EXTERN MSTATUS	MOC_CMS_getRecipientId (MOC_CMS_context context, sbyte4 idxRecipient, MOC_CMS_RecipientId *pRecipient)
	Return the recipient id for 'idxRecipient' value, if applicable. More...

MOC_EXTERN MSTATUS	MOC_CMS_getSignerInfo (MOC_CMS_context context, sbyte4 idxSigner, MOC_CMS_MsgSignInfo *pSigner)
	Return the signing info for 'idxSigner' value, if applicable. More...

MOC_EXTERN MSTATUS	MOC_CMS_newContext (MOC_CMS_context pNewContext, const void callbackArg, const MOC_CMS_Callbacks *pCallbacks)
	Create a new context to parse a CMS. More...

MOC_EXTERN MSTATUS	MOC_CMS_newContextOut (MOC_CMS_context pNewContext, MOC_CMS_ContentType type, RNGFun rngFun, void rngFunArg, intBoolean isStreaming, const void *callbackArg, MOC_CMS_UpdateData dataUpdateFun)
	Create a new context to output data in a CMS format. More...

MOC_EXTERN MSTATUS	MOC_CMS_setEncryption (MOC_CMS_context context, const ubyte encryptAlgoOID, ubyte4 encryptAlgoOIDLen, RNGFun rngFun, void rngFunArg)
	Sets the encryption algorithm for the CMS output context. More...

MOC_EXTERN MSTATUS	MOC_CMS_setPayloadLength (MOC_CMS_context context, ubyte4 len)
	Sets the pay load length for the CMS output context. More...

MOC_EXTERN MSTATUS	MOC_CMS_updateContext (MOC_CMS_context context, const ubyte input, ubyte4 inputLen, intBoolean pFinished)
	Add CMS message data to the context. More...

MOC_EXTERN MSTATUS	MOC_CMS_updateContextOut (MOC_CMS_context context, const ubyte *output, ubyte4 outputLen, intBoolean last)
	Add pay load data to the context for CMS output. More...

Detailed Description

Header file for the Digicert SoT Platform API for Cryptographic Message Syntax (CMS) support.

Flags To enable these functions, the following conditions must be met:

__ENABLE_MOCANA_CMS__ must be defined

moccms.h

Typedef Documentation

◆ MOC_CMS_GetCertificate

typedef MSTATUS(* MOC_CMS_GetCertificate) (const void *arg, ubyte *pSerialNumber, ubyte4 serialNumberLen, ubyte *pIssuer, ubyte4 issuerLen, ubyte **ppCertificate, ubyte4 *pCertificateLen)

The returned status is either 'OK', or a failure condition. When 'OK' is returned, the ppCertificate pointer must have been set to valid ASN1 data string, representing the certificate data, and pCertificateLen must contain the length of that data (in bytes).

◆ MOC_CMS_GetPrivateKey

typedef MSTATUS(* MOC_CMS_GetPrivateKey) (const void *arg, ubyte *pSerialNumber, ubyte4 serialNumberLen, ubyte *pIssuer, ubyte4 issuerLen, struct AsymmetricKey *pKey)

The returned status is either 'OK', or a failure condition. When 'OK' is returned, the pKey pointer must be set to a valid 'AsymmetricKey' representing the private key.

This call is issued when the provided data has been located in the CMS message. The locating this type of data in the CMS message depends on the 'type' of the certificate and choices made by the creator of the message.

◆ MOC_CMS_GetPrivateKeyEx

typedef MSTATUS(* MOC_CMS_GetPrivateKeyEx) (const void *arg, const MOC_CMS_RecipientId *pRecipientId, struct AsymmetricKey *pKey)

The returned status is either 'OK', or a failure condition. When 'OK' is returned, the pKey pointer must be set to a valid 'AsymmetricKey' representing the private key.

◆ MOC_CMS_signerID

typedef sbyte4 MOC_CMS_signerID

◆ MOC_CMS_UpdateData

typedef MSTATUS(* MOC_CMS_UpdateData) (const void *arg, MOC_CMS_context pCtx, MOC_CMS_UpdateType type, ubyte *pBuf, ubyte4 bufLen)

The data is delivered as a byte array (pBuf) with the given length bufLen.

An update call contains a 'type', that indicates where in the payload delivery this piece of data fits in (see MOC_CMS_UpdateType):

E_MOC_CMS_ut_update: The first or next data of the payload.
E_MOC_CMS_ut_final: The last data of the payload.
E_MOC_CMS_ut_result: The final call, which allows inspection of the context state, but does not deliver any data.

The CMS context pointer, so that public API calls like MOC_CMS_getContentType are available to the user.

◆ MOC_CMS_ValidateRootCertificate

typedef MSTATUS(* MOC_CMS_ValidateRootCertificate) (const void *arg, ubyte *pCertificate, ubyte4 certificateLen, MOC_CMS_MsgSignInfo *pSigInfo)

The public certificate data is obtained from the CMS message.

The returned status 'shall' reflect the validity of the certificate, where 'OK' signifies that the certificate is valid, and a failure code that it is not.

Enumeration Type Documentation

◆ MOC_CMS_action

enum MOC_CMS_action

◆ MOC_CMS_ContentType

enum MOC_CMS_ContentType

These values reflect the ContentType types as defined by RFC-5652. It also includes an 'undetermined' and 'invalid' value to support the implementation's core logic.

Not all of these type are supported by the CMS API.

◆ MOC_CMS_UpdateType

enum MOC_CMS_UpdateType

See the callback function MOC_CMS_updateData.

Function Documentation

◆ MOC_CMS_addCertificate()

MOC_EXTERN MSTATUS MOC_CMS_addCertificate	(	MOC_CMS_context	context,
		ubyte *	pCert,
		ubyte4	certLen
	)

This function adds a X509 certificate to the CMS output, which can be extracted by the reader of the CMS. The X509 formatted binary data is provided as input.

The data is not validate, just copied into the CMS.

Parameters

context	The context to which to add the certificate data
pCert	The memory containing the binary certificate data
certLen	The length of the certificate binary

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_addCRL()

MOC_EXTERN MSTATUS MOC_CMS_addCRL	(	MOC_CMS_context	context,
		ubyte *	pCRL,
		ubyte4	CRLLen
	)

This function adds a X509 CRL to the CMS output, which can be extracted by the reader of the CMS. The X509 formatted binary data is provided as input.

The data is not validate, just copied into the CMS.

Parameters

context	The context to which to add the CRL data
pCRL	The memory containing the binary CRL data
CRLLen	The length of the CRL binary

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_addDigest()

MOC_EXTERN MSTATUS MOC_CMS_addDigest	(	MOC_CMS_context	context,
		const ubyte *	digestAlgoOID,
		ubyte4	digestAlgoOIDLen
	)

This function adds a digest algorithm the CMS context, which will be used for verifying the CMS payload.

This call is used for 'resigning' a payload read from an input CMS, when the original signatures in the CMS need to be preserved and the reader needs to use the given digest for validation.

See 'MOC_CMS_getDigestID()' on how to access the digest OID of a parsed CMS input.

This call is only valid for CMS types that sign or digest data.

Parameters

context	The context to which to add the digest algorithm
digestAlgoOID	The ASN1 encoded OID of the digest, e.g. SHA-256
digestAlgoOIDLen	The length of `digestAlgoOID` in bytes

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_addRecipient()

MOC_EXTERN MSTATUS MOC_CMS_addRecipient	(	MOC_CMS_context	context,
		const ubyte *	pCert,
		ubyte4	certLen
	)

This function adds all needed data to encrypt a payload in a envelop-data CMS with a public key of a recipient. The identity is found in X509 data and its public key is used encrypt the encryption key.

This call is only valid for CMS types that encrypt data.

Parameters

context	The context to which to add the 'Recipient' data
pCert	The byte array containing the X509 certificate data
certLen	The length of the above array

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_addSignatureRaw()

MOC_EXTERN MSTATUS MOC_CMS_addSignatureRaw	(	MOC_CMS_context	context,
		const ubyte *	pSig,
		ubyte4	sigLen
	)

This function adds a binary signature field the CMS output, which is found by the reader of the CMS just like a generated signature. The binary data is provided as input.

The data is not validate, just copied into the CMS.

This call is used for 'resigning' a payload read from an input CMS, when the original signatures in the CMS need to be preserved.

This call is only valid for CMS types that sign or digest data.

Parameters

context	The context to which to add the 'raw' signature
pSig	The memory containing the signature data
sigLen	The length of the signature data

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_addSigner()

MOC_EXTERN MSTATUS MOC_CMS_addSigner	(	MOC_CMS_context	context,
		ubyte *	pCert,
		ubyte4	certLen,
		const AsymmetricKey *	pKey,
		const ubyte *	pDigestAlgoOID,
		ubyte4	digestAlgoOIDLen,
		MOC_CMS_action	action,
		MOC_CMS_signerID *	pSignID
	)

This function adds all needed data to sign a payload in a sign-data CMS with a specific 'Signer' identity. The identity is found in X509 data and a private key is used to sign. Also, the digest algorithm is specified.

This function can return a unique ID value for the signer, that can be used in the 'MOC_CMS_addSignerAttribute' function to set an attribute for a 'signer'.

This call is only valid for CMS types that sign or digest data.

Parameters

context	The context to which to add the 'Signer' data.
pCert	The byte array containing the X509 certificate data.
certLen	The length of the above array.
pKey	Pointer to the private key data, stored as an 'AsymmetricKey' type.
pDigestAlgoOID	The ASN1 encoded identifier for the digest algorithm, e.g. NIST SHA256.
digestAlgoOIDLen	The length of the OID in bytes.
action	A bit-OR of values from the 'MOC_CMS_action' enum, to cause further action for this 'Signer'. It can for instance cause the certificate to be included in the output.
pSignId	Pointer to memory where the 'Signer' ID value is stored, if it is not NULL.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_addSignerAttribute()

MOC_EXTERN MSTATUS MOC_CMS_addSignerAttribute	(	MOC_CMS_context	context,
		MOC_CMS_signerID	signId,
		const ubyte *	idOID,
		ubyte4	oidLen,
		ubyte4	typeID,
		const ubyte *	value,
		ubyte4	valueLen,
		intBoolean	authenticated
	)

This function adds an 'attribute' to the CMS output, which can be authenticated with a 'Signer' signature, or not. The attribute type and value are provided as input and the CMS will contain that data in ASN1/DER formatting.

This call is only valid for CMS types that sign or digest data.

Parameters

context	The context to which to add the 'attribute' data
signId	The 'Signer' identity to which this attribute shall belong, or the value 'MOC_CMS_signerID_ALL'.
idOID	The ASN1 encoded OID used as the attribute's identifier.
oidLen	The length of the `idOID` in bytes.
typeID	The type of the value, e.g. an id taken from 'mocasn1.h' like 'MASN1_TYPE_INTEGER'
value	The memory containing the value, passed as a byte array.
valueLen	The size of the value memory in bytes.
authenticated	A Boolean to cause the attribute to be 'signed' so that it can be authenticated by the reader of the CMS data.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_addUnprotectedAttribute()

MOC_EXTERN MSTATUS MOC_CMS_addUnprotectedAttribute	(	MOC_CMS_context	context,
		const ubyte *	idOID,
		ubyte4	oidLen,
		ubyte4	typeID,
		const ubyte *	value,
		ubyte4	valueLen
	)

This function adds an 'attribute' to the CMS output. The attribute type and value are provided as input and the CMS will contain that data in ASN1/DER formatting.

This call is only valid for CMS types that encrypt data.

The data is never authenticated.

Parameters

context	The context to which to add the 'attribute' data
idOID	The ASN1 encoded OID used as the attribute's identifier.
oidLen	The length of `idOID` in bytes.
typeID	The type of the value, e.g. an id taken from 'mocasn1.h' like 'MASN1_TYPE_INTEGER' Use 'MASN1_TYPE_ENCODED' if you add a 'raw' DER encoded value.
value	The memory containing the value, passed as a byte array.
valueLen	The size of the value memory in bytes.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_deleteContext()

MOC_EXTERN MSTATUS MOC_CMS_deleteContext ( MOC_CMS_context * pContext )

Frees all memory referenced by the context.

The argument is a pointer to the memory where the context reference is stored. It will be set to NULL.

Parameters

pContext A pointer to the CMS context

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_deleteRecipientId()

MOC_EXTERN MSTATUS MOC_CMS_deleteRecipientId ( MOC_CMS_RecipientId * pRecipient )

This function allows the user code to free the memory held by a 'MOC_CMS_RecipientId' instance, easily.

Parameters

pRecipient The pointer to a recipient struct (MOC_CMS_RecipientId).

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_deleteSignerInfo()

MOC_EXTERN MSTATUS MOC_CMS_deleteSignerInfo ( MOC_CMS_MsgSignInfo * pSigner )

This function allows the user code to free the memory held by a 'MOC_CMS_MsgSignInfo' instance, easily.

Parameters

pSigner The pointer to a signer struct (MOC_CMS_MsgSignInfo).

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_finalizeContextOut()

MOC_EXTERN MSTATUS MOC_CMS_finalizeContextOut ( MOC_CMS_context context )

This causes the CMS context generate all final data and write all buffered data to the output callback.

Parameters

context The CMS context

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_getCallbacks()

MOC_EXTERN MSTATUS MOC_CMS_getCallbacks	(	MOC_CMS_context	context,
		MOC_CMS_Callbacks *	pCB
	)

Allows access to the field inside the 'opaque' context, and returns its current value.

The returned data is a copy and changing it does not change the function pointers within the context.

Parameters

context	The CMS context
pCB	The pointer to the memory where the 'MOC_CMS_Callback' copy is to be stored. It is not allowed to be NULL.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_getCertificates()

MOC_EXTERN MSTATUS MOC_CMS_getCertificates	(	MOC_CMS_context	context,
		const ubyte **	ppCerts,
		ubyte4 *	pCertLen
	)

This call is only valid when the CMS context type is 'E_MOC_CMS_ct_signedData'.

A concatenated array of certificates is returned in memory, the memory is 'owned' by the context and the caller must make a copy if it wants to retain the data.

In case there were no certificates in the CMS data (yet), a NULL is returned.

Parameters

context	The CMS context
ppCerts	The pointer to a variable where the memory pointer will be stored.
pCertLen	The pointer to a variable where the size of the memory will be stored.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_getContentType()

MOC_EXTERN MSTATUS MOC_CMS_getContentType	(	MOC_CMS_context	context,
		MOC_CMS_ContentType *	cmsContentType
	)

Allows access to the field inside the 'opaque' context, and returns its current value.

Parameters

context	The CMS context
cmsContentType	The pointer to the memory where the content type value is to be stored. It is not allowed to be NULL.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_getCRLs()

MOC_EXTERN MSTATUS MOC_CMS_getCRLs	(	MOC_CMS_context	context,
		const ubyte **	ppCRLs,
		ubyte4 *	pCRLsLen
	)

This call is only valid when the CMS context type is 'E_MOC_CMS_ct_signedData'.

A concatenated array of CRL entries is returned in memory, the memory is 'owned' by the context and the caller must make a copy if it wants to retain the data.

In case there were no CRLs in the CMS data (yet), a NULL is returned.

Parameters

context	The CMS context
ppCRLs	The pointer to a variable where the CRL pointer will be stored.
pCRLsLen	The pointer to a variable where the size of the memory will be stored.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_getDigestID()

MOC_EXTERN MSTATUS MOC_CMS_getDigestID	(	MOC_CMS_context	context,
		ubyte4	idx,
		const ubyte **	pDigestAlgoOID
	)

This call is only valid when the CMS context type is 'E_MOC_CMS_ct_signedData'.

A digest is identified with ASN1 encoded OID.

The returned data is reference to context data and MAY NOT be freed by the caller.

Parameters

context	The CMS context
idx	The index number of the requested digest. A valid value must be larger than or equal 0, and be smaller than the number obtained with 'MOC_CMS_getNumDigests'.
pDigestAlgoOID	The pointer to a memory pointer, that is 'const'. It will be set to point to data within the context. It is not allowed to be NULL.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_getNumDigests()

MOC_EXTERN MSTATUS MOC_CMS_getNumDigests	(	MOC_CMS_context	context,
		ubyte4 *	pNumDigests
	)

This call is only valid when the CMS context type is 'E_MOC_CMS_ct_signedData'.

The returned value represents the number of digests used in the CMS data.

Parameters

context	The CMS context
pNumDigests	The pointer to the memory where the value is to be stored.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_getNumRecipients()

MOC_EXTERN MSTATUS MOC_CMS_getNumRecipients	(	MOC_CMS_context	context,
		sbyte4 *	pNumRecipients
	)

This call is only valid when the CMS context type is 'E_MOC_CMS_ct_envelopedData'.

The returned value represents the number of recipients found in the CMS message

Parameters

context	The CMS context
pNumRecipients	The pointer to the memory where the value is to be stored.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_getNumSignatures()

MOC_EXTERN MSTATUS MOC_CMS_getNumSignatures	(	MOC_CMS_context	context,
		sbyte4 *	pNumSigs
	)

This call is only valid when the CMS context type is 'E_MOC_CMS_ct_signedData'.

The returned value represents the number of signature fields found in the CMS.

Parameters

context	The CMS context
pNumSigs	The pointer to the memory where the value is to be stored.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_getNumSigners()

MOC_EXTERN MSTATUS MOC_CMS_getNumSigners	(	MOC_CMS_context	context,
		sbyte4 *	pNumSigners
	)

This call is only valid when the CMS context type is 'E_MOC_CMS_ct_signedData'.

The returned value represents the number of verified signatures.

Parameters

context	The CMS context
pNumSigners	The pointer to the memory where the value is to be stored.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_getRecipientId()

MOC_EXTERN MSTATUS MOC_CMS_getRecipientId	(	MOC_CMS_context	context,
		sbyte4	idxRecipient,
		MOC_CMS_RecipientId *	pRecipient
	)

This call is only valid when the CMS context type is 'E_MOC_CMS_ct_envelopedData'.

A signer is identified with an instance of 'MOC_CMS_RecipientId'.

The returned data is a deep copy of the context data fields and MUST be freed by the caller.

Parameters

context	The CMS context
idxRecipient	The index number of the requested recipient. A valid value must be larger than or equal 0, and be smaller than the number obtained with 'MOC_CMS_getNumRecipients'.
pRecipient	The pointer to a recipient struct (MOC_CMS_RecipientId). The selected data will be copied to that memory, and it is not allowed to be NULL.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_getSignerInfo()

MOC_EXTERN MSTATUS MOC_CMS_getSignerInfo	(	MOC_CMS_context	context,
		sbyte4	idxSigner,
		MOC_CMS_MsgSignInfo *	pSigner
	)

This call is only valid when the CMS context type is 'E_MOC_CMS_ct_signedData'.

A signer is identified with an instance of 'MOC_CMS_MsgSignInfo'.

The returned data is a deep copy of the context data fields and MUST be freed by the caller.

Parameters

context	The CMS context
idxSigner	The index number of the requested signer. A valid value must be larger than or equal 0, and be smaller than the number obtained with 'MOC_CMS_getNumSigners'.
pSigner	The pointer to a signer struct (MOC_CMS_MsgSignInfo). The selected data will be copied to that memory, and it is not allowed to be NULL.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_newContext()

MOC_EXTERN MSTATUS MOC_CMS_newContext	(	MOC_CMS_context *	pNewContext,
		const void *	callbackArg,
		const MOC_CMS_Callbacks *	pCallbacks
	)

Allocates the new context instance and sets the 'pNewContext' pointer.

The function takes a generic callback argument and a pointer to a 'MOC_CMS_Callbacks' structure to set up callback calls to the user code.

Parameters

pNewContext	A pointer to where the memory address of the context is stored. Is not allowed to be NULL.
callbackArg	Argument passed to all callback functions.
pCallbacks	The 'MOC_CMS_Callbacks' structure containing function pointers to the user's callback code.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_newContextOut()

MOC_EXTERN MSTATUS MOC_CMS_newContextOut	(	MOC_CMS_context *	pNewContext,
		MOC_CMS_ContentType	type,
		RNGFun	rngFun,
		void *	rngFunArg,
		intBoolean	isStreaming,
		const void *	callbackArg,
		MOC_CMS_UpdateData	dataUpdateFun
	)

Allocates the new context instance and sets the 'pNewContext' pointer.

The generated CMS format is determined by the 'type' value.

The function takes a generic callback argument and a pointer to a function of type 'MOC_CMS_UpdateData' to set up a callback with formatted data to the user code.

The CMS format can handle 'streaming' data of a length not determined at the start of the processing. If this is way this instance should behave, the value of 'isStreaming' must be set to 'TRUE'. Otherwise, use FALSE.

Parameters

pNewContext	A pointer to where the memory address of the context is stored. Is not allowed to be NULL.
type	The type of CMS format to be created. Selected with a value from the 'MOC_CMS_ContentType' enum, e.g. 'E_MOC_CMS_ct_signedData'.
rngFun	Pointer to a function that generates random numbers suitable for cryptographic use. To be FIPS-compliant, reference RANDOM_rngFun() (defined in random.c), and make sure that `__ENABLE_MOCANA_FIPS_MODULE__` is defined in moptions.h
rngFunArg	Pointer to arguments that are required by the function referenced in `rngFun`. If you use RANDOM_rngFun(), you must supply a `randomContext` structure, which you can create by calling `RANDOM_acquireContext`(...).
isStreaming	A Boolean value telling the context to use a 'streaming' format or not.
callbackArg	Argument passed to the callback function.
dataUpdateFun	A function pointer of type 'MOC_CMS_UpdateData' that will receive the formatted data as input.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_setEncryption()

MOC_EXTERN MSTATUS MOC_CMS_setEncryption	(	MOC_CMS_context	context,
		const ubyte *	encryptAlgoOID,
		ubyte4	encryptAlgoOIDLen,
		RNGFun	rngFun,
		void *	rngFunArg
	)

This function defines the crypto algorithm the CMS context, which will be used for encrypting the CMS payload.

A random number generator function is passed as well. It may be needed by the cryptographic algorithm, e.g. for salt generation. It can be set to a different RNG function than provided when the context was created, or the same RNG function can be used.

This call is only valid for CMS types that encrypt data.

Parameters

context	The context for which to configure the encryption algorithm
encryptAlgoOID	The ASN1 encoded OID of the cryptographic algorithm, e.g AES-256
encryptAlgoOIDLen	The length of `encryptAlgoOID` in bytes
rngFun	A function pointer to a random number generate, typed as 'RNGFun'
rngFunArg	The argument passed to the RNG function when it is called

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_setPayloadLength()

MOC_EXTERN MSTATUS MOC_CMS_setPayloadLength	(	MOC_CMS_context	context,
		ubyte4	len
	)

This function may be used when the output format of the CMS is NOT of the 'streaming' type, i.e. the value FALSE was used for isStreaming when creating the CMS output context. It informs the CMS context about the size of the payload and it then can enforce that value while the function MOC_CMS_updateContextOut() processes input data.

You can safely 'ignore' this function.

A call to this function is valid for all output CMS types.

This function must be called before the first pay load data is provided to the same context.

Parameters

context	The context for which to set the pay load length.
len	The total length (in bytes) of the pay load embedded in the CMS output.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_updateContext()

MOC_EXTERN MSTATUS MOC_CMS_updateContext	(	MOC_CMS_context	context,
		const ubyte *	input,
		ubyte4	inputLen,
		intBoolean *	pFinished
	)

Passes new message data to the CMS context for parsing.

If the logical end of the processing has been reached (i.e. no more data is necessary), the returned '*pFinished' value is no longer FALSE.

Parameters

context	The CMS context
input	The 'ubyte' array of new CMS data
inputLen	The size of the above array
pFinished	A pointer to 'intBoolean' to store the 'Finished' flag

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ MOC_CMS_updateContextOut()

MOC_EXTERN MSTATUS MOC_CMS_updateContextOut	(	MOC_CMS_context	context,
		const ubyte *	output,
		ubyte4	outputLen,
		intBoolean	last
	)

Passes new message data to the CMS context so that it is part of the output.

If the last pay load data is being passed in, signal that with a 'final' value of TRUE.

Parameters

context	The CMS context
output	The 'ubyte' array of new pay load data
outputLen	The size of the above array
last	An 'intBoolean' signal the end of the pay load data

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ MOC_CMS_GetCertificate

◆ MOC_CMS_GetPrivateKey

◆ MOC_CMS_GetPrivateKeyEx

◆ MOC_CMS_signerID

◆ MOC_CMS_UpdateData

◆ MOC_CMS_ValidateRootCertificate

Enumeration Type Documentation

◆ MOC_CMS_action

◆ MOC_CMS_ContentType

◆ MOC_CMS_UpdateType

Function Documentation

◆ MOC_CMS_addCertificate()

◆ MOC_CMS_addCRL()

◆ MOC_CMS_addDigest()

◆ MOC_CMS_addRecipient()

◆ MOC_CMS_addSignatureRaw()

◆ MOC_CMS_addSigner()

◆ MOC_CMS_addSignerAttribute()

◆ MOC_CMS_addUnprotectedAttribute()

◆ MOC_CMS_deleteContext()

◆ MOC_CMS_deleteRecipientId()

◆ MOC_CMS_deleteSignerInfo()

◆ MOC_CMS_finalizeContextOut()

◆ MOC_CMS_getCallbacks()

◆ MOC_CMS_getCertificates()

◆ MOC_CMS_getContentType()

◆ MOC_CMS_getCRLs()

◆ MOC_CMS_getDigestID()

◆ MOC_CMS_getNumDigests()

◆ MOC_CMS_getNumRecipients()

◆ MOC_CMS_getNumSignatures()

◆ MOC_CMS_getNumSigners()

◆ MOC_CMS_getRecipientId()

◆ MOC_CMS_getSignerInfo()

◆ MOC_CMS_newContext()

◆ MOC_CMS_newContextOut()

◆ MOC_CMS_setEncryption()

◆ MOC_CMS_setPayloadLength()

◆ MOC_CMS_updateContext()

◆ MOC_CMS_updateContextOut()