CMS (Cryptographic Message Syntax) Callback Functions

Typedefs
typedef MSTATUS(*	CMS_GetCertificate) (const void *arg, CStream cs, ASN1_ITEM *pSerialNumber, ASN1_ITEM *pIssuerName, ubyte **ppCertificate, ubyte4 *certificateLen)
	Return a message's certificate that matches a given serial number and issuer name. More...
typedef MSTATUS(*	CMS_GetPrivateKey) (const void *arg, CStream cs, const CMSRecipientId *pRecipientId, AsymmetricKey *pKey)
	Get the private key associated with a given certificate in a CMS message stream. More...
typedef MSTATUS(*	CMS_SignData) (void *pCbInfo, const ubyte *digestAlgoOID, const ubyte *pDataToSign, ubyte4 dataToSignLen, ubyte *pSigBuffer, ubyte4 sigBufferLen)
	This callback is used to perform a signature operation. More...
typedef MSTATUS(*	CMS_ValidateRootCertificate) (const void *arg, CStream cs, ASN1_ITEM *pCertificate)
	Validate the certificates in a CMS message. More...

Detailed Description

Typedef Documentation

CMS_GetCertificate

typedef MSTATUS(* CMS_GetCertificate) (const void *arg, CStream cs, ASN1_ITEM *pSerialNumber, ASN1_ITEM *pIssuerName, ubyte **ppCertificate, ubyte4 *certificateLen)

This callback function searches a given CMS stream (message), cs, for a certificate that matches serial number and issuer name. If no match is found, this callback function should search a private store of certificates (which has been read into a CStream) for a match.

(when is callback invoked?) (what's the "arg" param for?)

cms.h

Parameters

arg	TBD.
cs	CStream containing the CMS message in which to search for the certificate.
pSerialNumber	Pointer to ANS1_ITEM that references the serial number to search for.
pIssuerName	Pointer to ANS1_ITEM that references the issuer name to search for.
ppCertificate	On return, pointer to the matching certificate; NULL if no matching certificate is found.
pCertStream	On return, pointer to CStream that contains the matching certificate, ppCertificate. The CStream can be the same as the input, cs, or it can be a CStream containing a private store of certificates.

Returns

OK (0). If no matching certificate is found, NULL is returned in the ppCertificate parameter.

cms.h

CMS_GetPrivateKey

typedef MSTATUS(* CMS_GetPrivateKey) (const void *arg, CStream cs, const CMSRecipientId *pRecipientId, AsymmetricKey *pKey)

This callback function searches a given CMS stream (message), cs, for a certificate that matches given recipient information — serial number and issuer name. To obtain the certificate, call the CMS_GetCertificate() callback function. To validate the certificate, call the CMS_ValidateRootCertificate() callback function. If the certificate is valid, this callback function (CMS_GetPrivateKey()) can get the associated private key.

If the subject's PEM-encoded private key is stored in a file, you can copy the key to an AsymmetricKey structure as follows:

AsymmetricKey key;
ubyte* pemKeyFile = FILE_PATH("key.pem");
ubyte *pPemKey=NULL, *pKeyblob=NULL;
ubyte4 pemKeyLen, keyblobLen;

if (OK > (status = MOCANA_readFile( pemKeyFile, &pPemKey, &pemKeyLen)))
    goto exit;   // at exit, handle error

if (OK > (status = BASE64_initializeContext()))
    goto exit;

if (OK > (status = CA_MGMT_convertKeyPEM(pPemKey, pemKeyLen, &pKeyblob, &keyblobLen)))
    goto exit;

if (OK > (status = BASE64_freeContext()))
    goto exit;

if (OK > (status = CRYPTO_initAsymmetricKey( &key)))
    goto exit;

if (OK > (status = CA_MGMT_extractKeyBlobEx(pKeyblob, keyblobLen, &key)))
    goto exit;

Given this code, the callback function returns the private key through the pKey parameter.

(when is callback invoked?) (what is the arg param?)

cms.h

Parameters

arg	TBD.
cs	CStream containing the CMS message (a ContentInfo object containing a CMS EnvelopedData object) to search.
pRecipientId	Pointer to CMS RecipientId object that contains the serial number and issuer name of the certificate of interest.
pKey	On return, pointer to the certificate's private key.

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.

cms.h

CMS_SignData

typedef MSTATUS(* CMS_SignData) (void *pCbInfo, const ubyte *digestAlgoOID, const ubyte *pDataToSign, ubyte4 dataToSignLen, ubyte *pSigBuffer, ubyte4 sigBufferLen)

This callback is used to perform a signature operation. It can be used in place of a private key when a private key itself is unavailable, for example in a tpm.

cms.h

Parameters

pCbInfo	Optional callback args you may need for your routine.
digestAlgoOID	For RSA, the digest OID to be used when a digest info needs to be created.
pDataToSign	The data to sign. This should be a raw digest and not a digest info.
dataToSignLen	The length of the data to sign in bytes.
pSigBuffer	Buffer that will hold the resulting signature. For ECC and DSA this is r concatenated by s with each padded to their standard length based on the curve or q.
sigBufferLen	The length of the signature buffer in bytes.

Returns

OK (0) and a negative return code if otherwise.

cms.h

CMS_ValidateRootCertificate

typedef MSTATUS(* CMS_ValidateRootCertificate) (const void *arg, CStream cs, ASN1_ITEM *pCertificate)

This callback function validates the certificates in a CMS message.

Which validity checks to perform depends on your application and environment. Typical checks are:

• Validity dates.
• Walking a certificate chain to endsure that each certificate was issued by the next certificate in the chain.
• Ensuring that the last certificate in a chain is trusted.
• For incomplete certificate chains, searching a private store for certificates that could complete the chain.
• Business logic indicating whether access is ok (regardless of the validity of the certificate itself), such as an employee's current status or whether a customer's purchase has enabled a given service/access.

(when is callback invoked?) (is the "top" certificate the root or end-user?) (what's the "arg" param for?)

cms.h

Parameters

arg	TBD.
cs	CStream containing the CMS message of interest.
pCertificate	Pointer to topmost certificate in the certificate chain whether it is the root or not.

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.

cms.h