cms.h

Go to the documentation of this file.

/*
 * cms.h
 *
 * CMS Parser and utilities routines
 *
 * Copyright 2019-2024 DigiCert, Inc. All Rights Reserved.
 * Proprietary and Confidential Material.
 *
 */
#ifndef __CMS_HEADER__
#define __CMS_HEADER__

#ifdef __cplusplus
extern "C" {
#endif


/* Content type of a received CMS cf. CMS_getContentType() */
typedef enum CMS_ContentType
{
    E_CMS_undetermined = 0,
    E_CMS_data = 1,
    E_CMS_signedData = 2,
    E_CMS_envelopedData = 3,
    /* E_PCKS7S_signedAndEnvelopedData = 4, */
    E_CMS_digestedData = 5,
    E_CMS_encryptedData = 6,
    E_CMS_ct_authData = 102,
} CMS_ContentType;

typedef void* CMS_context;  /* opaque structure used when parsing a CMS */

/* opaque structures used when creating a CMS */
typedef void* CMS_signedDataContext;
typedef void* CMS_signerInfo;
typedef void* CMS_envelopedDataContext;


#define NO_TAG (0xFFFFFFFF)

/* data structures used in callbacks */
typedef struct CMSIssuerSerialNumber
{
    ASN1_ITEMPTR pIssuer;
    ASN1_ITEMPTR pSerialNumber;
} CMSIssuerSerialNumber;

typedef struct CMSKeyTransRecipientId
{
    ubyte4 type;
    union
    {
        CMSIssuerSerialNumber issuerAndSerialNumber; /* type = NO_TAG */
        ASN1_ITEMPTR          subjectKeyIdentifier;  /* type = 0 OCTETSTRING */
    } u;
} CMSKeyTransRecipientId;


typedef struct CMSOriginatorPublicKey
{
    ASN1_ITEMPTR pAlgoOID;  /* AlgorithmIdentifier: algorithm OID */
    ASN1_ITEMPTR pAlgoParameters; /* AlgorithmIdentifier: parameters ANY */
    ASN1_ITEMPTR pPublicKey; /* BIT STRING */
} CMSOriginatorPublicKey;

typedef struct CMSKeyAgreeRecipientId
{
    ubyte4 type;
    union
    {
        CMSIssuerSerialNumber   issuerAndSerialNumber;  /* type = NO_TAG */
        ASN1_ITEMPTR            subjectKeyIdentifier;   /* type = 0 OCTETSTRING */
        CMSOriginatorPublicKey  originatorKey;          /* type = 1 */
    } u;
} CMSKeyAgreeRecipientId;

#if 0  /* this is not supported yet */
typedef struct CMSKEKRecipientId
{
    ASN1_ITEMPTR keyIdentifer;
    ASN1_ITEMPTR date;          /* can be NULL */
    ASN1_ITEMPTR other;         /* can be NULL */
} CMSKEKRecipientId;
#endif

/* data structure used in the CMS_GetPrivateKey callback. The callback implementer
should use the content of this structure to determine which key is requested */
typedef struct CMSRecipientId
{
    ubyte4 type;
    union
    {
        CMSKeyTransRecipientId    ktrid;   /* type = NO_TAG */
        CMSKeyAgreeRecipientId    karid;   /* type = 1 */
#if 0
        CMSKEKRecipientId         kekrid;  /* type = 2 */
        CMSPasswordRecipientId    pwrdi;   /* type = 3 */
        CMSOtherRecipientId       orid;    /* type = 4 */
#endif
    } ri;
} CMSRecipientId;

/* this callback is used to retrieve the private key that */
/* corresponds to a CMSRecipientId */
typedef MSTATUS (*CMS_GetPrivateKey)(const void* arg,
                                     CStream cs,
                                     const CMSRecipientId* pRecipientId,
                                     AsymmetricKey* pKey);

/* this callback is used to verify that this certificate is recognized
as valid */
typedef MSTATUS (*CMS_ValidateRootCertificate)(const void* arg,
                                               CStream cs,
                                               ASN1_ITEM* pCertificate);

/* this callback is used to get a certificate given the issuer name and
serial number */
typedef MSTATUS (*CMS_GetCertificate)(const void* arg, CStream cs,
                                      ASN1_ITEM* pSerialNumber,
                                      ASN1_ITEM* pIssuerName,
                                      ubyte** ppCertificate,
                                      ubyte4* certificateLen);

/* all the callbacks that the CMS parser might need. */
typedef struct CMS_Callbacks
{
    CMS_GetPrivateKey             getPrivKeyFun;
    CMS_ValidateRootCertificate   valCertFun;
    CMS_GetCertificate            getCertFun;

} CMS_Callbacks;

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

MOC_EXTERN MSTATUS CMS_newContext(CMS_context* pNewContext,
                                  const void* callbackArg,
                                  const CMS_Callbacks* pCallbacks);

MOC_EXTERN MSTATUS CMS_updateContext( CMS_context context, const ubyte* input,
                                        ubyte4 inputLen, ubyte** ppOutput,
                                        ubyte4* pOutputLen, intBoolean* pFinished);

MOC_EXTERN MSTATUS CMS_deleteContext( CMS_context* pContext);

/*======== other functions to query the context for more information =======*/

/* These functions can return OK (success), ERR_EOF (more data must be provided by calling
CMS_updateContext) or some other error message (invalid data) */
MOC_EXTERN MSTATUS CMS_createContentInfo(const ubyte* contentType,  DER_ITEMPTR *ppContentInfo, DER_ITEMPTR *ppContent);
MOC_EXTERN MSTATUS CMS_getContentType( CMS_context context, CMS_ContentType* cmsContentType);

MOC_EXTERN MSTATUS CMS_getContentTypeOnly( CMS_context context,
                                           const ubyte* pInput,
                                           ubyte4 inputLen, CMS_ContentType* cType);

MOC_EXTERN MSTATUS CMS_getEncapContentType( CMS_context context, ubyte** ppOID);

/********* EnvelopedData recipients **********/

MOC_EXTERN MSTATUS CMS_getNumRecipients( CMS_context context,
                                          sbyte4* numRecipients);

MOC_EXTERN MSTATUS CMS_getRecipientInfo( CMS_context context,
                                          sbyte4 recipientIndexZeroBased,
                                          const ASN1_ITEM** pRecipientInfo,
                                          CStream* pCS);

MOC_EXTERN MSTATUS CMS_getDecryptingRecipient( CMS_context context,
                                          sbyte4* recipientIndexZeroBased);

MOC_EXTERN MSTATUS CMS_getEncryptionAlgo( CMS_context context,
                                         ubyte** ppEncryptionAlgoOID);

/******* SignedData signers **********/

MOC_EXTERN MSTATUS CMS_getNumSigners( CMS_context context,
                                        sbyte4* numSigners);

MOC_EXTERN MSTATUS CMS_getSignerInfo( CMS_context context,
                                      sbyte4 index,
                                      const ASN1_ITEM** ppRecipientInfo,
                                      CStream* pCS);

MOC_EXTERN MSTATUS CMS_getReceiptInfo( const ubyte* receipt, ubyte4 receiptLen,
                                        const ubyte** messageId, ubyte4* messageIdLen,
                                        const ubyte** signature, ubyte4* signatureLen);

MOC_EXTERN MSTATUS CMS_getReceiptMsgDigest( CMS_context context,
                                           const ubyte** ppDigest, ubyte4* pDigestLen);

MOC_EXTERN MSTATUS CMS_getFirstCertificate( CMS_context context,
                                           const ASN1_ITEM** ppCertificate,
                                           CStream* pCS);

MOC_EXTERN MSTATUS CMS_detachedSignature(CMS_context context, intBoolean* detached);

MOC_EXTERN MSTATUS CMS_setDetachedSignatureData( CMS_context context, const ubyte* payload,
                                                ubyte4 payloadLen, intBoolean final);

MOC_EXTERN MSTATUS CMS_createSignedReceipt( CMS_context context,
                                            sbyte4 index,
                                            RNGFun rngFun, void* rngFunArg,
                                            const ubyte* signerCert, ubyte4 signerCertLen,
                                            const AsymmetricKey* pKey, const ubyte* hashAlgoOID,
                                            ubyte** ppReceipt, ubyte4* pReceiptLen);

/************ CREATING CMS API **************************************/
/* 2 distinct APIs are provided for creating CMS, one for signed data and the other
for enveloped data */


MOC_EXTERN MSTATUS CMS_signedNewContext( CMS_signedDataContext* pNewCtx,
                                           const ubyte* payloadTypeOID,
                                           intBoolean detached, RNGFun rngFun,
                                           void* rngFunArg);

MOC_EXTERN MSTATUS CMS_signedAddCertificate( CMS_signedDataContext myCtx, const ubyte* cert,
                                        ubyte4 certLen);

MOC_EXTERN MSTATUS CMS_signedAddCRL( CMS_signedDataContext myCtx, const ubyte* crl,
                                        ubyte4 crlLen);

/* flags in CMS_signedAddSigner are a combination of the following values */
enum {
    e_cms_signer_addCert = 0x0001,       /* add the certificate to the CMS */
    e_cms_signer_forceAuthAttr = 0x0002  /* this signer wants to add some authenticated attributes */
};

MOC_EXTERN MSTATUS CMS_signedAddSigner( CMS_signedDataContext myCtx,
                                        const ubyte* cert,
                                        ubyte4 certLen,
                                        const AsymmetricKey* pKey,
                                        const ubyte* digestAlgoOID,
                                        ubyte4 flags,
                                        CMS_signerInfo* pNewSignerInfo);


MOC_EXTERN MSTATUS CMS_signedAddSignerWithCallback( MOC_HW(hwAccelDescr hwAccelCtx)
                                                    CMS_signedDataContext myCtx,
                                                    const ubyte* cert,
                                                    ubyte4 certLen,
                                                    CMS_SignData signCallback,
                                                    void* pCbInfo,
                                                    const ubyte* digestAlgoOID,
                                                    ubyte4 flags,
                                                    CMS_signerInfo* pNewSignerInfo);
MOC_EXTERN MSTATUS CMS_signedAddSignerAttribute( CMS_signedDataContext myCtx,
                                            CMS_signerInfo signerInfo,
                                            const ubyte* typeOID,
                                            ubyte4 type, /* id|tag */
                                            const ubyte* value,
                                            ubyte4 valueLen,
                                            intBoolean authenticated);

MOC_EXTERN MSTATUS CMS_signedAddReceiptRequest( MOC_HASH(hwAccelDescr hwAccelCtx)
                        CMS_signedDataContext myCtx,
                        const ubyte** receiptFrom,  /* Array of recipient email addresses from which receipts are requested*/
                        sbyte4 numReceiptFrom,      /* -1 for all, 0 for not on mailing list or > 0 to use the receiptFrom arg */
                        const ubyte** receiptTo,    /* Array of email addresses that receipts are to be sent to */
                        sbyte4 numReceiptTo);

MOC_EXTERN MSTATUS CMS_signedGetRequestInfo( CMS_signedDataContext myCtx,
                                        CMS_signerInfo signerInfo,
                                        const ubyte** messageId, ubyte4* messageIdLen,
                                        const ubyte** digest, ubyte4* digestLen,
                                        const ubyte** signature, ubyte4* signatureLen);

MOC_EXTERN MSTATUS CMS_signedUpdateContext( MOC_ASYM(hwAccelDescr hwAccelCtx)
                                           CMS_signedDataContext myCtx,
                                           const ubyte* data, ubyte4 dataLen,
                                           ubyte** ppOutput, ubyte4* pOutputLen,
                                           intBoolean finished);

MOC_EXTERN MSTATUS CMS_signedDeleteContext(MOC_HASH(hwAccelDescr hwAccelCtx)
                                           CMS_signedDataContext* ppCtx);


MOC_EXTERN MSTATUS CMS_envelopedNewContext( CMS_envelopedDataContext* pNewCtx,
                                                  const ubyte* encryptAlgoOID,
                                                  RNGFun rngFun, void* rngFunArg);

MOC_EXTERN MSTATUS CMS_envelopedAddRecipient( CMS_envelopedDataContext myCtx,
                                              const ubyte* cert, ubyte4 certLen);


MOC_EXTERN MSTATUS CMS_envelopedAddUnauthAttribute( CMS_envelopedDataContext myCtx,
                                            const ubyte* typeOID,
                                            ubyte4 type, /* id|tag */
                                            const ubyte* value,
                                            ubyte4 valueLen);

MOC_EXTERN MSTATUS CMS_envelopedUpdateContext(MOC_HW(hwAccelDescr hwAccelCtx)
                                              CMS_envelopedDataContext myCtx,
                                              const ubyte* data, ubyte4 dataLen,
                                              ubyte** ppOutput, ubyte4* pOutputLen,
                                              intBoolean finished);

MOC_EXTERN MSTATUS CMS_envelopedDeleteContext(MOC_SYM(hwAccelDescr hwAccelCtx)
                                              CMS_envelopedDataContext* ppCtx);


#ifdef __cplusplus
}
#endif

#endif  /*#ifndef __CMS_HEADER__ */