PKCS functionality. More...

Functions
MOC_EXTERN MSTATUS	CMC_SignData (MOC_ASYM(hwAccelDescr hwAccelCtx) ubyte4 flags, struct DER_ITEM pStart, struct DER_ITEM pParent, struct ASN1_ITEM pCACertificatesParseRoots[], CStream pCAStreams[], sbyte4 numCACerts, struct ASN1_ITEM pCrlsParseRoots[], CStream pCrlStreams[], sbyte4 numCrls, cmcSignerInfoPtr pCmcSignerInfos, ubyte4 numSigners, const ubyte payLoadType, const ubyte pPayLoad, ubyte4 payLoadLen, RNGFun rngFun, void rngFunArg, ubyte *ppSigned, ubyte4 pSignedLen)
	Create a DER-encoded, version 1, ASN.1 `SignedData` object for data internal or external to the `SignedData` object. More...

MOC_EXTERN MSTATUS	PKCS10_CertReqToCSR (const ubyte pCertReq, ubyte4 pCertReqLength, ubyte ppCsr, ubyte4 pCsrLength)
	Generate a text representation of a DER-encoded certificate request. More...

MOC_EXTERN MSTATUS	PKCS10_GenerateCertReqFromASN1Name (AsymmetricKey pKey, ubyte signAlgo, const ubyte pASN1Name, ubyte4 asn1NameLen, const requestAttributes pReqAttrs, ubyte ppCertReq, ubyte4 pCertReqLength)
	Generate a DER-encoded PKCS #10 certificate request for a given ASN.1 name. More...

MOC_EXTERN MSTATUS	PKCS10_GenerateCertReqFromDN (AsymmetricKey pKey, ubyte signAlgo, const certDistinguishedName pCertInfo, const requestAttributes pReqAttrs, ubyte ppCertReq, ubyte4 pCertReqLength)
	Generate a DER-encoded PKCS #10 certificate request for a given distinguished name. More...

MOC_EXTERN MSTATUS	PKCS10_GenerateCertReqFromDNEx (AsymmetricKey pKey, ubyte signAlgo, const certDistinguishedName pCertInfo, const requestAttributesEx pReqAttrs, ubyte ppCertReq, ubyte4 pCertReqLength)
	This is the same as PKCS10_GenerateCertReqFromDN, except that it takes a requestAttributesEx. More...

MOC_EXTERN MSTATUS	PKCS12_decrypt (MOC_SYM(hwAccelDescr hwAccelCtx) ASN1_ITEMPTR pEncryptedData, ASN1_ITEMPTR pAlgoIdentifier, CStream s, const ubyte password, sbyte4 passwordLen, ubyte decryptedInfo, sbyte4 decryptedInfoLen)
	Decrypt data according to a given algorithm, `pAlgorithmIdentifier`. More...

MOC_EXTERN MSTATUS	PKCS12_DecryptPFXPduPwMode (ubyte pPkcs12Data, ubyte4 pkcs12DataLen, ubyte pEncPw, ubyte4 encPwLen, ubyte pPrivacyPswd, ubyte4 privacyPswdLen, ubyte pIntegrityPswd, ubyte4 integrityPswdLen, SizedBuffer *ppCerts, ubyte4 pCertCount, ubyte *ppKeyBlob, ubyte4 pKeyBlobLen)
	Decrypt a password integrity mode encrypted PFX PDU. More...

MOC_EXTERN MSTATUS	PKCS12_encrypt (MOC_SYM(hwAccelDescr hwAccelCtx) ubyte pbeSubType, const ubyte password, sbyte4 passwordLen, const ubyte salt, sbyte4 saltLen, ubyte4 iterCount, ubyte *plainText, sbyte4 plainTextLen)
	Encrypt a buffer, typically a public key, according to the specified algorithm. More...

MOC_EXTERN MSTATUS	PKCS12_EncryptPFXPdu (MOC_HW(hwAccelDescr hwAccelCtx) randomContext pRandomContext, ubyte4 integrityMode, const ubyte pIntegrityPswd, ubyte4 integrityPswdLen, AsymmetricKey pVsrcSigK, const ubyte pDigestAlgoOID, CStream csSignerCertificate[], ubyte4 numSignerCerts, const PKCS12PrivacyModeConfig pPkcs12PrivacyModeConfig, PKCS12DataObject pkcs12DataObject[], ubyte4 numPKCS12DataObj, ubyte ppRetPkcs12CertDer, ubyte4 pRetPkcs12CertDerLen)
	Create an encrypted PFX PDU. More...

MOC_EXTERN MSTATUS	PKCS12_EncryptPFXPduCertMode (randomContext pRandomContext, SizedBuffer pCerts, ubyte4 certCount, ubyte pKeyBlob, ubyte4 keyBlobLen, ubyte pCA, ubyte4 caLen, ubyte pEncPw, ubyte4 encPwLen, ubyte4 pkcs12EncryptionType, ubyte pEncKeyCert, ubyte4 encKeyCertLen, const ubyte pEncAlgoId, ubyte pIntegrityKeyblob, ubyte4 integrityKeyblobLen, ubyte pIntegrityCert, ubyte4 integrityCertLen, const ubyte pDigestAlgoOID, ubyte *ppRetPkcs12CertDer, ubyte4 pRetPkcs12CertDerLen)
	Create a key integrity mode encrypted PFX PDU. More...

MOC_EXTERN MSTATUS	PKCS12_EncryptPFXPduPwMode (randomContext pRandomContext, SizedBuffer pCerts, ubyte4 certCount, ubyte pKeyBlob, ubyte4 keyBlobLen, ubyte pCA, ubyte4 caLen, ubyte pEncPw, ubyte4 encPwLen, ubyte4 pkcs12EncryptionType, ubyte pPrivacyPswd, ubyte4 privacyPswdLen, ubyte pIntegrityPswd, ubyte4 integrityPswdLen, ubyte ppRetPkcs12CertDer, ubyte4 pRetPkcs12CertDerLen)
	Create a password integrity mode encrypted PFX PDU. More...

MOC_EXTERN MSTATUS	PKCS12_ExtractInfo (MOC_HW(hwAccelDescr hwAccelCtx) ASN1_ITEM pRootItem, CStream s, const ubyte uniPassword, sbyte4 uniPassLen, void pkcs7CBArg, PKCS7_Callbacks pkcs7CBs, void *handlerContext, PKCS12_contentHandler handler)
	Extract and decrypt information from a PFX PDU, and submit the information to the given callback. More...

MOC_EXTERN const BulkEncryptionAlgo *	PKCS12_GetEncryptionAlgo (ubyte pbeSubType)
	Return function pointers for create, delete, and decrypt/encrypt operations for the specified PBE sub type. More...

MOC_EXTERN MSTATUS	PKCS5_CreateKey_PBKDF1 (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte pSalt, ubyte4 saltLen, ubyte4 iterationCount, enum hashFunc hashingFunction, const ubyte pPassword, ubyte4 passwordLen, ubyte4 dkLen, ubyte *pRetDerivedKey)
	Generate a key based on the RFC 2898 PBKDF1 key generation method. More...

MOC_EXTERN MSTATUS	PKCS5_CreateKey_PBKDF2 (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte pSalt, ubyte4 saltLen, ubyte4 iterationCount, ubyte rsaAlgoId, const ubyte pPassword, ubyte4 passwordLen, ubyte4 dkLen, ubyte *pRetDerivedKey)
	Generate a key based on the RFC 2898 PBKDF2 key generation method. More...

MOC_EXTERN MSTATUS	PKCS5_decrypt (MOC_SYM(hwAccelDescr hwAccelCtx) ubyte subType, CStream cs, ASN1_ITEMPTR pPBEParam, ASN1_ITEMPTR pEncrypted, const ubyte password, sbyte4 passwordLen, ubyte privateKeyInfo, sbyte4 privateKeyInfoLen)
	Decrypt data that is PKCS5 encrypted. More...

MOC_EXTERN MSTATUS	PKCS5_decryptV2 (MOC_SYM(hwAccelDescr hwAccelCtx) const ubyte pAsn1PBE, ubyte4 pbeLen, ubyte pData, ubyte4 dataLen, const ubyte pPassword, sbyte4 passwordLen, ubyte pPrivateKeyInfo, ubyte4 privKeyInfoBufferLen, ubyte4 *pPrivKeyInfoLen)
	Decrypt data that is PKCS5 V2 encrypted and in a raw buffer form. More...

MOC_EXTERN MSTATUS	PKCS5_encryptV1 (MOC_SYM(hwAccelDescr hwAccelCtx) ubyte pkcs5SubType, const ubyte password, ubyte4 passwordLen, const ubyte salt, ubyte4 saltLen, ubyte4 iterCount, ubyte *plainText, ubyte4 ptLen)
	Encrypt a plaintext buffer with PBES1 encryption as defined in RFC 2898. More...

MOC_EXTERN MSTATUS	PKCS5_encryptV2 (MOC_SYM(hwAccelDescr hwAccelCtx) const BulkEncryptionAlgo pAlgo, ubyte rsaAlgoId, ubyte4 keyLength, sbyte4 effectiveKeyBits, const ubyte password, ubyte4 passwordLen, const ubyte salt, ubyte4 saltLen, ubyte4 iterCount, const ubyte iv, ubyte *plainText, ubyte4 ptLen)
	Encrypt a plaintext buffer with PBES2 encryption as defined in RFC 2898. More...

MOC_EXTERN MSTATUS	PKCS7_DecryptEnvelopedData (MOC_HW(hwAccelDescr hwAccelCtx) struct ASN1_ITEM pEnvelopedData, CStream s, const void callbackArg, PKCS7_GetPrivateKey getPrivateKeyFun, ubyte *decryptedInfo, sbyte4 decryptedInfoLen)
	Extract and decrypt the encrypted content of an `EnvelopedData` object. More...

MOC_EXTERN MSTATUS	PKCS7_DecryptEnvelopedDataAux (MOC_HW(hwAccelDescr hwAccelCtx) struct ASN1_ITEM pEnvelopedData, CStream s, const void callbackArg, PKCS7_GetPrivateKey getPrivateKeyFun, enum encryptedContentType pType, struct ASN1_ITEM ppEncryptedContent, BulkCtx ppBulkCtx, const BulkEncryptionAlgo **ppBulkAlgo, ubyte iv[])
	Decrypt an `EnvelopedData` object and get its encryption details. More...

MOC_EXTERN MSTATUS	PKCS7_DigestData (MOC_HASH(hwAccelDescr hwAccelCtx) struct DER_ITEM pStart, struct DER_ITEM pParent, const ubyte payLoadType, ubyte hashType, const ubyte pPayLoad, ubyte4 payLoadLen, ubyte *ppDigested, ubyte4 pDigestedLen)
	Create a DER-encoded, ASN.1 `DigestedData` object for the given data. More...

MOC_EXTERN MSTATUS	PKCS7_EnvelopData (MOC_HW(hwAccelDescr hwAccelCtx) struct DER_ITEM pStart, struct DER_ITEM pParent, struct ASN1_ITEM pCACertificatesParseRoots[], CStream pStreams[], sbyte4 numCACerts, const ubyte encryptAlgoOID, RNGFun rngFun, void rngFunArg, const ubyte pPayLoad, ubyte4 payLoadLen, ubyte *ppEnveloped, ubyte4 pEnvelopedLen)
	Create a DER-encoded, version 0, ASN.1 `EnvelopedData` object containing a given payload. More...

MOC_EXTERN MSTATUS	PKCS7_EnvelopDataWoaep (MOC_HW(hwAccelDescr hwAccelCtx) struct DER_ITEM pStart, struct DER_ITEM pParent, struct ASN1_ITEM pCACertificatesParseRoots[], CStream pStreams[], sbyte4 numCACerts, const ubyte encryptAlgoOID, RNGFun rngFun, void rngFunArg, ubyte isOaep, ubyte4 oaepHashAlgo, sbyte pOaepLabel, const ubyte pPayLoad, ubyte4 payLoadLen, ubyte ppEnveloped, ubyte4 pEnvelopedLen)
	Create a DER-encoded, version 0, ASN.1 `EnvelopedData` object containing a given payload. More...

MOC_EXTERN MSTATUS	PKCS7_GetCertificates (struct ASN1_ITEM pRootItem, CStream s, struct ASN1_ITEM *ppFirstCertificate)
	If a given `CStream` contains a PKCS #7 `SignedData` object, get the first certificate. More...

MOC_EXTERN MSTATUS	PKCS7_GetSignerDigestAlgo (struct ASN1_ITEM pSignerInfo, CStream cs, ubyte hashAlgoId)
	Get a `SignerInfo` object's digest hash function identifier. More...

MOC_EXTERN MSTATUS	PKCS7_GetSignerSignatureAlgo (struct ASN1_ITEM pSignerInfo, CStream cs, ubyte pubKeyAlgoId)
	Get a `SignerInfo` object's digest encryption algorithm identifier. More...

MOC_EXTERN MSTATUS	PKCS7_GetSignerSignedAttributes (struct ASN1_ITEM pSignerInfo, struct ASN1_ITEM *ppFirstSignedAttribute)
	Get the first signed attribute in a DER-encoded, ASN.1 `SignerInfo` object. More...

MOC_EXTERN MSTATUS	PKCS7_GetSignerUnsignedAttributes (struct ASN1_ITEM pSignerInfo, struct ASN1_ITEM *ppFirstUnsignedAttribute)
	Get the first unsigned attribute in a DER-encoded, ASN.1 `SignerInfo` object. More...

MOC_EXTERN MSTATUS	PKCS7_SignData (MOC_ASYM(hwAccelDescr hwAccelCtx) ubyte4 flags, struct DER_ITEM pStart, struct DER_ITEM pParent, struct ASN1_ITEM pCACertificatesParseRoots[], CStream pCAStreams[], sbyte4 numCACerts, struct ASN1_ITEM pCrlsParseRoots[], CStream pCrlStreams[], sbyte4 numCrls, signerInfoPtr pSignerInfos, ubyte4 numSigners, const ubyte payLoadType, const ubyte pPayLoad, ubyte4 payLoadLen, RNGFun rngFun, void rngFunArg, ubyte *ppSigned, ubyte4 pSignedLen)
	Create a DER-encoded, version 1, ASN.1 `SignedData` object for data internal or external to the `SignedData` object. More...

MOC_EXTERN MSTATUS	PKCS7_VerifySignedData (MOC_ASYM(hwAccelDescr hwAccelCtx) struct ASN1_ITEM pSignedData, CStream s, const void callbackArg, PKCS7_GetCertificate getCertFun, PKCS7_ValidateRootCertificate valCertFun, const ubyte payLoad, ubyte4 payLoadLen, sbyte4 numKnownSigners)
	Verify the signature of a `SignedData` object that contains the signed data. More...

MOC_EXTERN MSTATUS	PKCS8_decodePrivateKeyDER (const ubyte pFileDerPkcs8, ubyte4 fileSizeDerPkcs8, ubyte ppRsaKeyBlob, ubyte4 pRsaKeyBlobLength)
	Extract a private key from a DER-encoded PKCS #8 object. More...

MOC_EXTERN MSTATUS	PKCS8_decodePrivateKeyPEM (const ubyte pFilePemPkcs8, ubyte4 fileSizePemPkcs8, ubyte ppRsaKeyBlob, ubyte4 pRsaKeyBlobLength)
	Extract a private key from a PEM-encoded PKCS #8 object. More...

MOC_EXTERN MSTATUS	PKCS_getPKCS8Key (MOC_ASYM(hwAccelDescr hwAccelCtx) const ubyte pPKCS8DER, ubyte4 pkcs8DERLen, AsymmetricKey pKey)
	Extract SoT Platform-formatted key from unencrypted PKCS #8 DER file. More...

MOC_EXTERN MSTATUS	PKCS_getPKCS8KeyEx (MOC_HW(hwAccelDescr hwAccelCtx) const ubyte pPKCS8DER, ubyte4 pkcs8DERLen, const ubyte password, ubyte4 passwordLen, AsymmetricKey *pKey)
	Extract SoT Platform-formatted key from PKCS #8 DER file (encrypted or unencrypted). More...

Detailed Description

Function Documentation

◆ CMC_SignData()

MOC_EXTERN MSTATUS CMC_SignData	(	MOC_ASYM(hwAccelDescr hwAccelCtx) ubyte4	flags,
		struct DER_ITEM *	pStart,
		struct DER_ITEM *	pParent,
		struct ASN1_ITEM *	pCACertificatesParseRoots[],
		CStream	pCAStreams[],
		sbyte4	numCACerts,
		struct ASN1_ITEM *	pCrlsParseRoots[],
		CStream	pCrlStreams[],
		sbyte4	numCrls,
		cmcSignerInfoPtr *	pCmcSignerInfos,
		ubyte4	numSigners,
		const ubyte *	payLoadType,
		const ubyte *	pPayLoad,
		ubyte4	payLoadLen,
		RNGFun	rngFun,
		void *	rngFunArg,
		ubyte **	ppSigned,
		ubyte4 *	pSignedLen
	)

This function creates a DER-encoded, version 1, ASN.1 SignedData object for the data internal or external to the SignedData object.

RFC 2315 defines the SignedData object as follows:

    SignedData ::= SEQUENCE {
        version Version,
        digestAlgorithms DigestAlgorithmIdentifiers,
        contentInfo ContentInfo,
        certificates [0] IMPLICIT ExtendedCertificatesAndCertificates OPTIONAL,
        crls [1] IMPLICIT CertificateRevocationLists OPTIONAL,
        signerInfos SignerInfos }

    DigestAlgorithmIdentifiers ::=

        SET OF DigestAlgorithmIdentifier

        SignerInfos ::= SET OF SignerInfo

        SignerInfo ::= SEQUENCE {
            version Version,
            issuerAndSerialNumber IssuerAndSerialNumber,
            digestAlgorithm DigestAlgorithmIdentifier,
            authenticatedAttributes [0] IMPLICIT Attributes OPTIONAL,
            digestEncryptionAlgorithm DigestEncryptionAlgorithmIdentifier,
            encryptedDigest EncryptedDigest,
            unauthenticatedAttributes [1] IMPLICIT Attributes OPTIONAL }

       EncryptedDigest ::= OCTET STRING

If you use this function to create an unsigned SignedData object, the resulting object is referred to as degenerate. RFC 2315 says you can use degenerate objects to distribute certificates and certificate revocation lists.

As required by RFC 2315, you can create a SignedData object that does not contain all the certificates needed to verify all the signatures, so long as the SignedData object is expected to have access to a certificate store contaiing the required signatures.

pkcs7.h

Parameters

flags	Zero (0) or bitmask combination (created by `OR`ing definitions together) specifying which signing elements to include.
pStart	NULL to not encapsulate the generated `SignedData` object in a `ContentInfo` object; otherwise `DER_ITEMPTR` whose referenced structure contains the (mostly empty) ASN.1 DER-encoded `ContentInfo` object that serves as a container for the `SignedData` object to create.
pParent	NULL if the `pStart` parameter is NULL; otherwise \ DER_ITEMPTR for the `pStart` parameter's referenced `ContentInfo` object.
pCACertificatesParseRoots	NULL to exclude certificates from the resultant `SignedData` object; otherwise array of `ASN1_ITEMPTR` pointers. The first array element references the first certificate in the `CStream`, `pCAStreams`, that contains the certificates to include in the resultant `SignedData` object. To get this `ASN1_ITEMPTR`, submit the `pCAStreams` to ASN1_Parse().
pCAStreams	NULL to exclude certificates from the resultant `SignedData` object; otherwise array of `CStream` objects containing the certificates to include in the resultant `SignedData` object.
numCACerts	Number of certificates in `pCAStreams`.
pCrlsParseRoots	NULL to exclude CRLs from the resultant `SignedData` object; otherwise array of `ASN1_ITEMPTR` pointers. The first array element references the first CRL in the `CStream`, `pCrlStreams`, that contains the CRLs to include in the resultant `SignedDat` object. To get this `ASN1_ITEMPTR`, submit the `pCrlStreams` to ASN1_Parse().
pCrlStreams	NULL to exclude CRLs from the resultant `SignedData` object; otherwise array of `CStream` objects containing the CRLs to include in the resultant `SignedData` object.
numCrls	Number of CRLs in `pCrlStreams`.
pSignerInfos	NULL to create an unsigned (degenerate) `SignedData` object; otherwise pointer to array of `signerInfo` structures, each of which contains the signing information for a single signer. For details about populating this structure, see signerInfo.
numSigners	0 (zero) if `pSignerInfos` is NULL; otherwise nubmer of elements in the `pSignerInfos` array.
payLoadType	Pointer to an OID describing the data in `pPayLoad`; typically `pkcs7_data_OID`, but can be any of the following OID type constant arrays from src/asn1/oiddefs.c: pkcs7_data_OID pkcs7_signedData_OID pkcs7_envelopedData_OID pkcs7_signedAndEnvelopedData_OID pkcs7_digestedData_OID pkcs7_encryptedData_OID
pPayLoad	Pointer to data for which to create signatures.
payLoadLen	Pointer to length of payload, `pPayLoad`.
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().
ppSigned	On return, if `pStart` = NULL, pointer to the address of a DER-encoded, version 1, ASN.1 `SignedData` object; otherwise, pointer to a DER-encoded ASN.1 `ContentInfo` structure that contains the `SignedData` object created by this function.
pSignedLen	On return, pointer to length of the `SignedData` object, `ppSigned`.

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.

pkcs7.h

◆ PKCS10_CertReqToCSR()

MOC_EXTERN MSTATUS PKCS10_CertReqToCSR	(	const ubyte *	pCertReq,
		ubyte4	pCertReqLength,
		ubyte **	ppCsr,
		ubyte4 *	pCsrLength
	)

This function generates a text representaiton of a DER-encoded certificate request by using Base64 encoding and generating lines of the proper length for compatibility with most CAs (certificate authorities).

Warning: The buffer containing the returned certificate text is allocated by the MALLOC() function/macro; you must free it using the FREE() function/macro.

Since: 6.4

Version: 6.4 and later

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS10__

pkcs10.h

Parameters

pCertReq	Pointer to DER-encoded certificate request.
certReqLen	Length of the DER-encoded certificate request, `pCertReq`.
ppCsr	On successful return, pointer to a buffer containing the text representation of the DER-encoded certificat
pCsrLength	On successful return, pointer to length of the certificate text buffer, `ppCsr`.

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.

pkcs10.h

◆ PKCS10_GenerateCertReqFromASN1Name()

MOC_EXTERN MSTATUS PKCS10_GenerateCertReqFromASN1Name	(	AsymmetricKey *	pKey,
		ubyte	signAlgo,
		const ubyte *	pASN1Name,
		ubyte4	asn1NameLen,
		const requestAttributes *	pReqAttrs,
		ubyte **	ppCertReq,
		ubyte4 *	pCertReqLength
	)

This function generates a DER-encoded PKCS #10 certificate request for a given ASN.1 name.

Note: This function is very convenient for generating a certificate request for the subject or issuer of an existing DER-encoded certificate. Point the pASN1Name parameter to the correct part of the existing DER-encoded certificate.

Warning: The buffer containing the returned certificate request is allocated by the MALLOC() function/macro; you must free it using the FREE() function/macro.

Since: 6.4

Version: 6.4 and later

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS10__

pkcs10.h

Parameters

pKey	Pointer to key (RSA or ECC) to use in the certificate request. The public part of the key is placed in the certificate request; the private part of the key is used to sign the certificate request.
signAlgo	Hash function used to generate the signature. The values are defined in crypto/crypto.h as enums with the prefix "ht_" (for HashType). Recommended values as of this writing (2016) are: ht_sha256 ht_sha384 ht_sha512
pASN1Name	Pointer to buffer containing the ASN.1 DER-encoded X.509 name (a sequence of `RelativeDistinguishedName` objects) that identifies the subject to associate with the public key.
asn1NameLen	Pointer to length of ASN.1 Der-encoded X.509 name, `pASN1Name`.
pReqAttrs	NULL pointer or pointer to a populated `requestAttributes` structure containing a challenge password and the requested X.509 version 3 certificate extensions for the new certificate.
ppCertReq	On successful return, pointer to buffer containing the ASN.1 DER-encoded certificate request.
pCertReqLength	On successful return, pointer to length of new certificate request, `ppCertReq`.

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.

pkcs10.h

◆ PKCS10_GenerateCertReqFromDN()

MOC_EXTERN MSTATUS PKCS10_GenerateCertReqFromDN	(	AsymmetricKey *	pKey,
		ubyte	signAlgo,
		const certDistinguishedName *	pCertInfo,
		const requestAttributes *	pReqAttrs,
		ubyte **	ppCertReq,
		ubyte4 *	pCertReqLength
	)

This function generates a DER-encoded PKCS #10 certificate request for a given distinguished name.

Warning: The buffer containing the returned certificate request is allocated by the MALLOC() function/macro; you must free it using the FREE() function/macro.

Since: 6.4

Version: 6.4 and later

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS10__

pkcs10.h

Parameters

pKey	Pointer to key (RSA or ECC) to use in the certificate request. The public part of the key is placed in the certificate request; the private part of the key is used to sign the certificate request.
signAlgo	Hash function used to generate the signature. The values are defined in crypto/crypto.h as enums with the prefix "ht_" (for HashType). Recommended values as of this writing (2016) are: ht_sha256 ht_sha384 ht_sha512
pCertInfo	Pointer to a certDistinguishedName structure that identifies the subject to associate with the public key.
pReqAttrs	NULL pointer or pointer to a populated `requestAttributes` structure containing a challenge password and the requested X.509 version 3 certificate extensions for the new certificate.
ppCertReq	On successful return, pointer to buffer containing the ASN.1 DER-encoded certificate request.
pCertReqLength	On successful return, pointer to length of new certificate request, `ppCertReq`.

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.

pkcs10.h

◆ PKCS10_GenerateCertReqFromDNEx()

MOC_EXTERN MSTATUS PKCS10_GenerateCertReqFromDNEx	(	AsymmetricKey *	pKey,
		ubyte	signAlgo,
		const certDistinguishedName *	pCertInfo,
		const requestAttributesEx *	pReqAttrs,
		ubyte **	ppCertReq,
		ubyte4 *	pCertReqLength
	)

The original function took in a request attributes struct that allowed for only two specific request attributes: challenge password and extension request. The new requestAttributesEx allows for more attributes.

Warning: The buffer containing the returned certificate request is allocated by the MALLOC() function/macro; you must free it using the FREE() function/macro.

Since: 6.4

Version: 6.4 and later

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS10__

pkcs10.h

Parameters

pKey	Pointer to key (RSA or ECC) to use in the certificate request. The public part of the key is placed in the certificate request; the private part of the key is used to sign the certificate request.
signAlgo	Hash function used to generate the signature. The values are defined in crypto/crypto.h as enums with the prefix "ht_" (for HashType). Recommended values as of this writing (2016) are: ht_sha256 ht_sha384 ht_sha512
pCertInfo	Pointer to a certDistinguishedName structure that identifies the subject to associate with the public key.
pReqAttrs	NULL pointer or pointer to a populated `requestAttributesEx` structure containing a challenge password, requested X.509 version 3 certificate extensions for the new certificate, and optional other attributes.
ppCertReq	On successful return, pointer to buffer containing the ASN.1 DER-encoded certificate request.
pCertReqLength	On successful return, pointer to length of new certificate request, `ppCertReq`.

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.

pkcs10.h

◆ PKCS12_decrypt()

MOC_EXTERN MSTATUS PKCS12_decrypt	(	MOC_SYM(hwAccelDescr hwAccelCtx) ASN1_ITEMPTR	pEncryptedData,
		ASN1_ITEMPTR	pAlgoIdentifier,
		CStream	s,
		const ubyte *	password,
		sbyte4	passwordLen,
		ubyte **	decryptedInfo,
		sbyte4 *	decryptedInfoLen
	)

This function decrypts data according to a given algorithm, pAlgorithmIdentifier.

Note: The PKCS12_ExtractInfo() function performs data decryption; therefore you do not need to call this decryption function for information that is extracted by the PKCS12_ExtractInfo() function. This function is a convenience function for data obtained other ways.

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS12__

pkcs12.h

Parameters

pEncryptedData	`ASN1_ITEMPTR` object referencing the data to decrypt.
pAlgoIdentifier	`ASN1_ITEMPTR` referencing the decryption algorithm.
s	Pointer to CStream that contains the data referenced by the ASN1_ITEMPTR objects, `pEncryptedData` and `pAlgoIdentifier`.
password	Password required to decrypt the data. The password is not required to be in Unicode.
passwordLen	Length of the password, `password`.
decryptedInfo	On return, pointer to the address of a buffer containing the decrypted data.
decryptedInfoLen	On return, pointer to address containing the length of the decrypted information, `decryptedInfo`.

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.

pkcs12.h

◆ PKCS12_DecryptPFXPduPwMode()

MOC_EXTERN MSTATUS PKCS12_DecryptPFXPduPwMode	(	ubyte *	pPkcs12Data,
		ubyte4	pkcs12DataLen,
		ubyte *	pEncPw,
		ubyte4	encPwLen,
		ubyte *	pPrivacyPswd,
		ubyte4	privacyPswdLen,
		ubyte *	pIntegrityPswd,
		ubyte4	integrityPswdLen,
		SizedBuffer **	ppCerts,
		ubyte4 *	pCertCount,
		ubyte **	ppKeyBlob,
		ubyte4 *	pKeyBlobLen
	)

Decrypt a password integrity mode encrypted PFX PDU. This function decrypts a PFX PDU generated from PKCS12_EncryptPFXPduPwMode. The certificate(s) and private key are extracted from the pkcs12 data.

To enable this function, the following flag must be defined in moptions.h: flags:

__ENABLE_MOCANA_PKCS12__

pkcs12.h

Parameters

pPkcs12Data	Buffer containing pkcs12 document in DER format.
pkcs12DataLen	Length of the pkcs12 document.
pEncPw	Encryption password used to protect the private key stored in the pkcs12 document.
encPwLen	Length of the encryption password.
pPrivacyPswd	Privacy password used to encrypt the pkcs12 document.
privacyPswdLen	Length of the privacy password.
pIntegrityPswd	Integrity password used to generate the pkcs12 document MAC.
integrityPswdLen	Length of the integrity password.
ppCerts	Contents will be set to the certificates extracted from the pkcs12 document. Must be freed by caller.
pCertCount	Contents will be set to the number of certificates extracted.
ppKeyBlob	Contents will be set to the private key extracted from the pkcs12 document. Must be freed by caller.
pKeyBlobLen	Contents will be set to the number of bytes allocated in the key buffer.

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.

pkcs12.h

◆ PKCS12_encrypt()

MOC_EXTERN MSTATUS PKCS12_encrypt	(	MOC_SYM(hwAccelDescr hwAccelCtx) ubyte	pbeSubType,
		const ubyte *	password,
		sbyte4	passwordLen,
		const ubyte *	salt,
		sbyte4	saltLen,
		ubyte4	iterCount,
		ubyte *	plainText,
		sbyte4	plainTextLen
	)

This function encrypts the submitted plaintext according to the specified algorithm. Its main purpose is not bulk encryption but the generation of a PCKS #12 public key from an input asymmetric key.

To create an encrypted PFX PDU, use PKCS12_EncryptPFXPdu(). This function (PKCS12_encrypt), is provided as a convenience.

pkcs12.h

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS12__

Parameters

pbeSubType	Encryption sub type; any of the following `PKCS8EncryptionType` enum values from pkcs_key.h: `PCKS8_EncryptionType_pkcs12_sha_2des` `PCKS8_EncryptionType_pkcs12_sha_3des` `PCKS8_EncryptionType_pkcs12_sha_rc2_40` `PCKS8_EncryptionType_pkcs12_sha_rc2_128` `PCKS8_EncryptionType_pkcs12_sha_rc4_40` `PCKS8_EncryptionType_pkcs12_sha_rc4_128`
password	Password required to encrypt the data. The password does not need to be in UNICODE.
passwordLen	Length of the password, `password`.
salt	Pointer to salt to use as input to the key generation. The salt bits should be a random value generated by a cryptographically strong pseudo-random number generator. At a minimum, generate a salt value of at least eight bits.
saltLen	Length of the salt buffer, `salt`.
iterCount	Number of iterations to apply in the key generation algorithm. The more iterations, the heavier the computational load, but the stronger the generated key. A value of 2048 is recommended.
plainText	On input, pointer to plaintext message to encrypt. On return, pointer to encrypted ciphertext.
plainTextLen	Length in bytes of plaintext message, `plainText`. On return, the ciphertext will have the same length.

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.

pkcs12.h

◆ PKCS12_EncryptPFXPdu()

MOC_EXTERN MSTATUS PKCS12_EncryptPFXPdu	(	MOC_HW(hwAccelDescr hwAccelCtx) randomContext *	pRandomContext,
		ubyte4	integrityMode,
		const ubyte *	pIntegrityPswd,
		ubyte4	integrityPswdLen,
		AsymmetricKey *	pVsrcSigK,
		const ubyte *	pDigestAlgoOID,
		CStream	csSignerCertificate[],
		ubyte4	numSignerCerts,
		const PKCS12PrivacyModeConfig *	pPkcs12PrivacyModeConfig,
		PKCS12DataObject	pkcs12DataObject[],
		ubyte4	numPKCS12DataObj,
		ubyte **	ppRetPkcs12CertDer,
		ubyte4 *	pRetPkcs12CertDerLen
	)

This function creates an encrypted PFX PDU.

To enable this function, the following flag must be defined in moptions.h: flags:

__ENABLE_MOCANA_PKCS12__

pkcs12.h

Parameters

pRandomContext	Pointer to a `randomContext` structure, an opaque structure containing information required to generate a random number using the functions documented in random.dxd. To allocate this structure, call RANDOM_acquireContext(). To release the memory for such a structure, call RANDOM_releaseContext().
integrityMode	Integrity mode; either of the following `ePKCS12Mode` enum values from pkcs12.h: `PKCS12Mode_Integrity_password` — Use the submitted password for authentication. `PKCS12Mode_Integrity_pubKey` — Use certificates for authentication.
pIntegrityPswd	If `integrityMode` is specified as `PKCS12Mode_Integrity_password`, the secret password; otherwise NULL.
integrityPswdLen	If `pIntegrityPswd` is not NULL, length of the secret password, `pIntegrityPswd`.
pVsrcSigK	If `integrityMode` is specified as \ PKCS12Mode_Integrity_pubKey, the source private signature key; otherwise NULL.
pDigestAlgoOID	If `integrityMode` is specified as PKCS12Mode_Integrity_pubKey, the digest algorithm to use for the digital signature; any of the following preconfigured OID arrays from src/asn1/oiddefs.h: `md5_OID` `sha1_OID` `sha1_OID` `sha224_OID` `sha256_OID` `sha384_OID` `sha512_OID`
csSignerCertificate	If `integrityMode` is specified as `PKCS12Mode_Integrity_pubKey`, array containing the signer certificate streams used to digitally sign the PKCS #12 PDU.
numSignerCerts	If `integrityMode` is specified as `PKCS12Mode_Integrity_pubKey`, number of signer certificate streams in array, `csSignerCertificate`.
pPkcs12PrivacyModeConfig	Pointer to structure containing the parameters required for the privacy mode.
pkcs12DataObject	Pointer to array of `PKCS12DataObject` structures that contain the data objects to put into the PKCS #12 PDU. Valid objects are certificates, CRLs, and PKCS #8 private keys.
numPKCS12DataObj	Number of objects in the `PKCS12DataObject` array, `pkcs12DataObject`.
ppRetPkcs12CertDer	On return, pointer to address of resulting DER-encoded PKCS #12 PDU.
pRetPkcs12CertDerLen	On return, pointer to address of length of resulting PDU, `ppRetPkcs12CertDer`.

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.

pkcs12.h

◆ PKCS12_EncryptPFXPduCertMode()

MOC_EXTERN MSTATUS PKCS12_EncryptPFXPduCertMode	(	randomContext *	pRandomContext,
		SizedBuffer *	pCerts,
		ubyte4	certCount,
		ubyte *	pKeyBlob,
		ubyte4	keyBlobLen,
		ubyte *	pCA,
		ubyte4	caLen,
		ubyte *	pEncPw,
		ubyte4	encPwLen,
		ubyte4	pkcs12EncryptionType,
		ubyte *	pEncKeyCert,
		ubyte4	encKeyCertLen,
		const ubyte *	pEncAlgoId,
		ubyte *	pIntegrityKeyblob,
		ubyte4	integrityKeyblobLen,
		ubyte *	pIntegrityCert,
		ubyte4	integrityCertLen,
		const ubyte *	pDigestAlgoOID,
		ubyte **	ppRetPkcs12CertDer,
		ubyte4 *	pRetPkcs12CertDerLen
	)

Create a key integrity mode encrypted PFX PDU.

To enable this function, the following flag must be defined in moptions.h: flags:

__ENABLE_MOCANA_PKCS12__

pkcs12.h

Parameters

pRandomContext	(Optional) Pointer to a `randomContext` structure. If NULL then the global default will be used.
pCerts	The target certificates to be pkcs12 encoded.
certCount	The number of certificates in the `pCerts` buffers.
pKeyBlob	The serialized target key to be pkcs12 encoded.
keyBlobLen	The length of the serialized target key in bytes.
pCA	(Optional) A CA cert in DER form to be pkcs12 encoded.
caLen	The length of the CA cert in bytes.
pEncPw	(Optional) The encryption password to be used for the key and certs.
encPwLen	The length of the encryption password in bytes.
pkcs12EncryptionType	Any of the following `PKCS8EncryptionType` enum values from pkcs_key.h: `PCKS8_EncryptionType_pkcs12_sha_2des` `PCKS8_EncryptionType_pkcs12_sha_3des` `PCKS8_EncryptionType_pkcs12_sha_rc2_40` `PCKS8_EncryptionType_pkcs12_sha_rc2_128` `PCKS8_EncryptionType_pkcs12_sha_rc4_40` `PCKS8_EncryptionType_pkcs12_sha_rc4_128`
pEncKeyCert	Certificate holding the public key used to encrypt each target.
encKeyCertLen	The length of the certificate in bytes.
pEncAlgoId	The public key encrption algorithm OID.
pIntegrityKeyblob	Serialized private key used to sign the generated pkcs12 document.
integrityKeyblobLen	The length of the serialized private key in bytes.
pIntegrityCert	The certificate associated with the signing private key.
integrityCertLen	The length of the certificate in bytes.
pDigestAlgoOID	The digest algorithm OID of that to be used in the signing process.
ppRetPkcs12CertDer	Contents will be set to the location of the allocated buffer holding the generated DER form pkcs12 document.
pRetPkcs12CertDerLen	Contents will be set to the length of the allocated buffer 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.

pkcs12.h

◆ PKCS12_EncryptPFXPduPwMode()

MOC_EXTERN MSTATUS PKCS12_EncryptPFXPduPwMode	(	randomContext *	pRandomContext,
		SizedBuffer *	pCerts,
		ubyte4	certCount,
		ubyte *	pKeyBlob,
		ubyte4	keyBlobLen,
		ubyte *	pCA,
		ubyte4	caLen,
		ubyte *	pEncPw,
		ubyte4	encPwLen,
		ubyte4	pkcs12EncryptionType,
		ubyte *	pPrivacyPswd,
		ubyte4	privacyPswdLen,
		ubyte *	pIntegrityPswd,
		ubyte4	integrityPswdLen,
		ubyte **	ppRetPkcs12CertDer,
		ubyte4 *	pRetPkcs12CertDerLen
	)

Create a password integrity mode encrypted PFX PDU.

To enable this function, the following flag must be defined in moptions.h: flags:

__ENABLE_MOCANA_PKCS12__

pkcs12.h

Parameters

pRandomContext	(Optional) Pointer to a `randomContext` structure. If NULL then the global default will be used.
pCerts	The target certificates to be pkcs12 encoded.
certCount	The number of certificates in the `pCerts` buffers.
pKeyBlob	The serialized target key to be pkcs12 encoded.
keyBlobLen	The length of the serialized target key in bytes.
pCA	(Optional) A CA cert in DER form to be pkcs12 encoded.
caLen	The length of the CA cert in bytes.
pEncPw	(Optional) The encryption password to be used for the key and certs.
encPwLen	The length of the encryption password in bytes.
pkcs12EncryptionType	Any of the following `PKCS8EncryptionType` enum values from pkcs_key.h: `PCKS8_EncryptionType_pkcs12_sha_2des` `PCKS8_EncryptionType_pkcs12_sha_3des` `PCKS8_EncryptionType_pkcs12_sha_rc2_40` `PCKS8_EncryptionType_pkcs12_sha_rc2_128` `PCKS8_EncryptionType_pkcs12_sha_rc4_40` `PCKS8_EncryptionType_pkcs12_sha_rc4_128`
pPrivacyPswd	(Optional) The privacy password.
privacyPswdLen	The length of the privacy password in bytes.
pIntegrityPswd	(Optional) Buffer holding the secret password for the pkcs12 document.
integrityPswdLen	The length of the secret password in bytes.
ppRetPkcs12CertDer	Contents will be set to the location of the allocated buffer holding the generated DER form pkcs12 document.
pRetPkcs12CertDerLen	Contents will be set to the length of the allocated buffer 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.

pkcs12.h

◆ PKCS12_ExtractInfo()

MOC_EXTERN MSTATUS PKCS12_ExtractInfo	(	MOC_HW(hwAccelDescr hwAccelCtx) ASN1_ITEM *	pRootItem,
		CStream	s,
		const ubyte *	uniPassword,
		sbyte4	uniPassLen,
		void *	pkcs7CBArg,
		PKCS7_Callbacks *	pkcs7CBs,
		void *	handlerContext,
		PKCS12_contentHandler	handler
	)

This function extracts information from a PFX PDU, decrypts the information, and submits the information to the given callback.

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS12__

pkcs12.h

Parameters

pRootItem	Pointer to `ASN1_ITEM` for the root of the CStream, `s`, that contains the PFX object from which to extract information. To get this root item pointer, call ASN1_Parse() for the CStream. For details about setting up this CStream and getting the root, see Setting up a CStream and Getting the ASN1_ITEM for the Root ASN.1 Object in the pkcs7.dxd documentation.
s	Pointer to CStream that contains the PFX object, `pRootItem`.
uniPassword	UNICODE password that protects the PFX PDU.
uniPassLen	Length of the UNICODE password, `uniPassword`.
callbackArg	Pointer to arguments that are required by the function referenced in `pkcs7CBs`.
pkcs7CBs	Pointer to a PKCS7_Callbacks structure containing callback functions to decrypt a PKCS #12 file if the contents of the PFX PDU are digitally signed with a private signature key or if the contents are encrypted with a trusted public key.
handlerContext	TBD.
handler	Pointer to callback function that conforms to the prototype, PKCS12_contentHandler(). After PKCS12_ExtractInfo() extracts the information from the specified PFX object, it passes that information to this `handler` parameter's callback function.

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.

pkcs12.h

◆ PKCS12_GetEncryptionAlgo()

MOC_EXTERN const BulkEncryptionAlgo* PKCS12_GetEncryptionAlgo ( ubyte pbeSubType )

This funciton returns a BulkEncryptionAlgo structure containing the function pointers for create, delete, and decrypt/encrypt operations for the specified PBE sub type.

Note: If you call PKCS12_EncryptPFXPdu(), you do not need to call this convenience function.

Warning: If you directly access the ciphers that are accessible through this function, you take on the responsibility of managing IVs (initialization vectors). To ensure confidentiality, it is essential to correctly manage IVs.

The BulkEncryptionAlgo structure is defined in crypto.h as follows:

    typedef struct BulkEncryptionAlgo
    {
        ubyte4                  blockSize;
        CreateBulkCtxFunc       createFunc;
        DeleteBulkCtxFunc       deleteFunc;
        CipherFunc              cipherFunc;
    } BulkEncryptionAlgo;

For The CreateBulkCtxFunc, DeleteBulkCtxFunc, and CipherFunc typedefs are defined in crypto.h:

    typedef BulkCtx (*CreateBulkCtxFunc)(MOC_SYM(hwAccelDescr hwAccelCtx)
             ubyte* keyMaterial, sbyte4 keyLength, sbyte4 encrypt);
    typedef MSTATUS (*DeleteBulkCtxFunc) (MOC_SYM(hwAccelDescr hwAccelCtx)
             BulkCtx *ctx);
    typedef MSTATUS (*CipherFunc)(MOC_SYM(hwAccelDescr hwAccelCtx)
             BulkCtx ctx, ubyte* data, sbyte4 dataLength, sbyte4 encrypt, ubyte* iv);

Using `CreateBulkCtxFunc` typedef

The CreateBulkCtxFunc function creates an encryption/decryption context. The following parameters are required:

keyMaterial — Key appropriate to the underlying cipher.
- 3DES in two-key mode: pass in key material that is a concatenation of two distinct DES keys (a total of 16 bytes for both keys).
- 3DES in three-key mode: use a concatenation of three unique DES keys (24 bytes for all three keys).
- RC2: pass in an RC2 key of the appropriate length for the PBE sub type. The key length can be from one to 16 bytes (and is typically 16 bytes).
- RC4: pass in a 16-byte key.
keylength — Length of the key material, keyMaterial.
encrypt — To encrypt data, specify TRUE; to decrypt data, specify FALSE. You cannot use the same encryption/decryption context for encryption and decryption.

Using `CipherFunc` typedef

The CipherFunc function encrypts or decrypts a content buffer. The following parameters are required:

ctx — Context for the cipher, returned by the CreateBulkCtxFunc function.
data — On input, pointer to the address of the plaintext buffer to encrypt or the ciphertext buffer to decrypt. If the underlying cipher is a block cipher, this buffer must be an even multiple of the block size. If it is not, you must pad the data.

On return, pointer to address of the resulting ciphertext or plaintext buffer.
dataLength — Length of plaintext/ciphertext buffer, data.
encrypt — To encrypt data, specify TRUE; to decrypt data, specify FALSE. The value must match the value that was specified in the CreateBulkCtxFunc call that created the context in ctx.
iv — Initialization vector appropriate to the cipher. For RC4 (a symmetric-key stream cipher), pass NULL because no initialization vector is required.

Using DeleteBulkCtxFunc

After the data is encrypted/decrypted, call DeleteBulkCtxFunc to free the context (which was allocated by CreateBulkCtxFunc).

Generating Initialization Vectors

All the block ciphers accessible through this function are implemented in CBC mode. As input, a block cipher in CBC mode requires an initialization vector, iv, which is generated externally from this API. that is you must handle it within your application. This iv must be known by the message recipient in order for it to decrypt the message. For the CBC mode, the iv need not be secret, which simplifies the problem of getting the iv to the recipient. However, the iv must be unpredictable for any particular plaintext.

One method for producing an unpredictable iv is to apply the encryption function (using the same key that is used to encrypt the data) to a nonce. This nonce must be a data block that is unique for each buffer encrypted under a given key. Useful sources of unique nonce values are counters (as described in Appendix B of NIST Special Publication 800-38A, 2001 Edition) or message numbers. Another commonly used method is to generate a random data block using a FIPS-approved (and therefore cryptographically strong) random number generator to use as the nonce.

For CBC mode, the iv should be unique for all messages encrypted under a given key. For CBC mode, reusing an iv leaks information on the first block of plaintext, and on any common prefix shared by the two messages.

Padding

For a block cipher in CBC mode, the input for encryption or decryption must be an even multiple of the block size. In the Digicert SoT Platform implementation of these modes, if the input data does not meet this requirement, processing stops and the function returns an error. Therefore, before submitting data to a Digicert SoT Platform API function that implements these modes, be sure to check the size of the data and, if necessary, pad it to an even multiple of the block size. You can use any padding method. Typical schemes are:

RFC 1321, step 3.1, describes a common bit-oriented scheme.
RFC 5652, section 6.3, describes a a byte-oriented padding scheme
Another byte-oriented scheme is provided in ANSI X.923.

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS12__

pkcs12.h

Parameters

pbeSubType

Encryption sub type for which you want a set of function pointers; any of the following PKCS8EncryptionType enum values from pkcs_key.h:

PCKS8_EncryptionType_pkcs12_sha_2des
PCKS8_EncryptionType_pkcs12_sha_3des
PCKS8_EncryptionType_pkcs12_sha_rc2_40
PCKS8_EncryptionType_pkcs12_sha_rc2_128

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.

pkcs12.h

◆ PKCS5_CreateKey_PBKDF1()

MOC_EXTERN MSTATUS PKCS5_CreateKey_PBKDF1	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	pSalt,
		ubyte4	saltLen,
		ubyte4	iterationCount,
		enum hashFunc	hashingFunction,
		const ubyte *	pPassword,
		ubyte4	passwordLen,
		ubyte4	dkLen,
		ubyte *	pRetDerivedKey
	)

This function implements the PBKDF1 key derivation method defined in RFC 2898. It applies the hash function the specified number of times, iterationCount, to the given password and salt (pPassword and pSalt) to derive the key. In addition to supporting SHA-1, MD2, and MD5 as specified by RFC 2898, this function extends support to SHA[224|256|384|512] and MD4 hash functions. The length of the resulting key is bounded by the length of the hash function output, which is:

16 octets for MD2, MD4, and MD5.
20 octets for SHA-1.
28 octets for SHA-224.
32 octets for SHA-256.
48 octets for SHA-384.
64 octets for SHA-512.

Note: Use PBKDF1 only for existing applications that require it for backward compatibility. Use PBKDF2 for newer applications; see PKCS5_CreateKey_PBKDF2().

(is MD4 still, in SoTP 6.4 that is, supported? Global question...)

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS5__

pkcs5.h

Parameters

pSalt	Pointer to salt to hash.
saltLen	Length in bytes of the salt (`pSalt`).
iterationCount	Number of hash function (`hashingFunction`) iterations.
hashingFunction	Hash function to apply to the password and salt; any of the `hashFunc` enum values from pkcs5.h: `md2Encryption` `md4Encryption` `md5Encryption` `sha1Encryption` `sha256Encryption` `sha384Encryption` `sha512Encryption` `sha224Encryption`
pPassword	Pointer to password to hash.
passwordLen	Length in bytes of password (`pPassword`).
dkLen	Length of key to deive. Must be less than or equal to the length of the hash function ouptut.
pRetDerivedKey	On return, pointer to derived key — an octet string of length `dkLen`.

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.

pkcs5.h

◆ PKCS5_CreateKey_PBKDF2()

MOC_EXTERN MSTATUS PKCS5_CreateKey_PBKDF2	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	pSalt,
		ubyte4	saltLen,
		ubyte4	iterationCount,
		ubyte	rsaAlgoId,
		const ubyte *	pPassword,
		ubyte4	passwordLen,
		ubyte4	dkLen,
		ubyte *	pRetDerivedKey
	)

This function implements the PBKDF2 key derivation method defined in RFC 2898. It applies a pseudorandom function the specified number of times, iterationCount, to the given password and salt to derive the key. PBKDF2 is recommended for new applications. The pseudorandom function is HMAC with a digest algorithm. The caller specifies which digest algorithm to use.

In FIPS mode, the only digest algorithms allowed are SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512. In any new allplication, you should not use MD2, MD4, or MD5, they are only provided to support older applications.

In FIPS mode, the salt length must be at least 16 bytes (128 bits).

In FIPS mode, the derived key length (dkLen) must be at least 14 bytes (112 bits).

Note: Use PBKDF2 for new applications. If you have an existing appliation that requires PBKDF1 for backward compatibility, use the PKCS5_CreateKey_PBKDF1() function.

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS5__

pkcs5.h

Parameters

pSalt	Pointer to salt to hash.
saltLen	Length in bytes of the salt (`pSalt`).
iterationCount	Number of pseudorandom function iterations.
digestAlg	Digest algorithm to apply to the password and salt; any of the following enum values from src/crypto/crypto.h: `ht_md2` (not valid in FIPS mode) `md2withRSAEncryption` (same as ht_md2) `ht_md4` (not valid in FIPS mode) `md4withRSAEncryption` (same as ht_md4) `ht_md5` (not valid in FIPS mode) `md5withRSAEncryption` (same as ht_md5) `ht_sha1` `sha1withRSAEncryption` (same as ht_sha1) `ht_sha224` `sha224withRSAEncryption` (same as ht_sha224) `ht_sha256` `sha256withRSAEncryption` (same as ht_sha256) `ht_sha384` `sha384withRSAEncryption` (same as ht_sha384) `ht_sha512` `sha512withRSAEncryption` (same as ht_sha512)
pPassword	Pointer to password to hash.
passwordLen	Length in bytes of password (`pPassword`).
dkLen	Length of key to derive; the maximum value is (2^32 - 1) bytes.
pRetDerivedKey	On return, pointer to derived key — an octet string of length `dkLen`.

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.

pkcs5.h

◆ PKCS5_decrypt()

MOC_EXTERN MSTATUS PKCS5_decrypt	(	MOC_SYM(hwAccelDescr hwAccelCtx) ubyte	subType,
		CStream	cs,
		ASN1_ITEMPTR	pPBEParam,
		ASN1_ITEMPTR	pEncrypted,
		const ubyte *	password,
		sbyte4	passwordLen,
		ubyte **	privateKeyInfo,
		sbyte4 *	privateKeyInfoLen
	)

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS5__

pkcs5.h

Parameters

subType	The type of algorithm used for encryption, either V1 or V2. Use the enum PKCS5_PBES2 to indicate PBE2, anything else will be treated as PBE1.
cs	The CStream associated with the ASN1 item pointers.
pPBEParam	ASN1 item pointing to the PBE params to use for the decryption.
pEncrypted	ASN1 item pointing to the encrypted data to be decrypted.
password	Buffer containing the password that the data was originally encrypted with.
passwordLen	Length in bytes of the password data.
privateKeyInfo	Pointer to the location that will recieve the newly allocated decrypted data buffer.
privateKeyInfoLen	Length in bytes of the decrypted 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.

◆ PKCS5_decryptV2()

MOC_EXTERN MSTATUS PKCS5_decryptV2	(	MOC_SYM(hwAccelDescr hwAccelCtx) const ubyte *	pAsn1PBE,
		ubyte4	pbeLen,
		ubyte *	pData,
		ubyte4	dataLen,
		const ubyte *	pPassword,
		sbyte4	passwordLen,
		ubyte *	pPrivateKeyInfo,
		ubyte4	privKeyInfoBufferLen,
		ubyte4 *	pPrivKeyInfoLen
	)

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS5__

pkcs5.h

Parameters

pAsn1PBE	The PBE params to use for the decryption in a raw buffer ASN1 form.
pbeLen	The length of the `pAsn1PBE` buffer in bytes.
pData	The data to be encrypted in a raw buffer form.
dataLen	The length of the `pData` buffer in bytes.
password	Buffer containing the password that the data was originally encrypted with.
passwordLen	Length in bytes of the password data.
pPrivateKeyInfo	Buffer to hold the decrypted data.
privKeyInfoBufferLen	Length of the `pPrivateKeyInfo` buffer in bytes.
pPrivKeyInfoLen	Contents will be set to the actual length of the private key info.

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.

◆ PKCS5_encryptV1()

MOC_EXTERN MSTATUS PKCS5_encryptV1	(	MOC_SYM(hwAccelDescr hwAccelCtx) ubyte	pkcs5SubType,
		const ubyte *	password,
		ubyte4	passwordLen,
		const ubyte *	salt,
		ubyte4	saltLen,
		ubyte4	iterCount,
		ubyte *	plainText,
		ubyte4	ptLen
	)

This function encrypts a plaintext buffer with PBES1 encryption as defined in RFC 2898. It combines PBKDF1 key derivation with either DES or RC2 block cipher encryption, depending on the given pkdcs5SubType parameter.

Note: Use PBES1 only for compatibility with existing applications because it uses small key sizes and supports only two encryption schemes. Use PBES2 (see PKCS5_encryptV2()) for new applications because it supports large key sizes and many encryption schemes.

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS5__

pkcs5.h

Parameters

pkcs5SubType	PKCS8 encryption type; any of the `PKCS8EncryptionType` enum values from pkcs_key.h: `PCKS8_EncryptionType_pkcs5_v1_md2_des` `PCKS8_EncryptionType_pkcs5_v1_md5_des` `PCKS8_EncryptionType_pkcs5_v1_md2_rc2` `PCKS8_EncryptionType_pkcs5_v1_md5_rc2` `PCKS8_EncryptionType_pkcs5_v1_sha1_des` `PCKS8_EncryptionType_pkcs5_v1_sha1_rc2`
password	Pointer to password to use for key derivation.
passwordLen	Length in bytes of password (`pPassword`).
salt	Pointer to salt to use for key derivation.
saltLen	Length in bytes of the salt (`salt`).
iterCount	Iteration count to use for key derivation.
plainText	On input, pointer to plaintext message to encrypt. On return, pointer to encrypted ciphertext.
ptLen	Length in bytes of plaintext message, `plainText`. On return, the ciphertext will have the same length.

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.

pkcs5.h

◆ PKCS5_encryptV2()

MOC_EXTERN MSTATUS PKCS5_encryptV2	(	MOC_SYM(hwAccelDescr hwAccelCtx) const BulkEncryptionAlgo *	pAlgo,
		ubyte	rsaAlgoId,
		ubyte4	keyLength,
		sbyte4	effectiveKeyBits,
		const ubyte *	password,
		ubyte4	passwordLen,
		const ubyte *	salt,
		ubyte4	saltLen,
		ubyte4	iterCount,
		const ubyte *	iv,
		ubyte *	plainText,
		ubyte4	ptLen
	)

This function encrypts a plaintext buffer with PBES2 encryption as defined in RFC 2898. It combines the PBKDF2 password-based key derivation function with the given bulk encryption algorithm.

Note: Use PBES2 for new applications because it supports large key sizes and many encryption schemes. Use PBES1 (see PKCS5_encryptV1()) only for compatibility with existing applications because it uses small key sizes and supports only two encryption schemes.

(clarify how effectiveKeyBits works)

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS5__

pkcs5.h

Parameters

pAlgo	Pointer to bulk encryption algorithm to apply; any of the following BulkEncryptionAlgo constant arrays defined in src/crypto/crypto.c: `CRYPTO_TripleDESSuite` `CRYPTO_TwoKeyTripleDESSuite` `CRYPTO_DESSuite` `CRYPTO_RC4Suite` `CRYPTO_RC2Suite` `CRYPTO_RC2EffectiveBitsSuite` `CRYPTO_BlowfishSuite` `CRYPTO_AESSuite` `CRYPTO_AESCtrSuite` `CRYPTO_NilSuite`
rsaAlgoId	Pseudorandom function algorithm to apply to the password and salt; any of the following enum values from src/crypto/crypto.h: `md2withRSAEncryption` `md4withRSAEncryption` `md5withRSAEncryption` `sha1withRSAEncryption` `sha224withRSAEncryption` `sha256withRSAEncryption` `sha384withRSAEncryption` `sha512withRSAEncryption`
keyLength	Length of key to derive; the maximum value is (2^32 - 1) bytes.
effectiveKeyBits	Specify "1" to ensure encryption.
password	Pointer to password to use for key derivation.
passwordLen	Length in bytes of password (`password`).
salt	Pointer to salt to use for key derivation.
saltLen	Length in bytes of the salt (`salt`).
iterCount	Iteration count to use for key derivation.
iv	Initialization vector whose first pAlgo->blockSize bytes are appended to the derived key.
plainText	On input, pointer to plaintext message to encrypt. On return, pointer to encrypted ciphertext.
ptLen	Length in bytes of plaintext message, `plainText`. On return, the ciphertext will have the same length.

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.

pkcs5.h

◆ PKCS7_DecryptEnvelopedData()

MOC_EXTERN MSTATUS PKCS7_DecryptEnvelopedData	(	MOC_HW(hwAccelDescr hwAccelCtx) struct ASN1_ITEM *	pEnvelopedData,
		CStream	s,
		const void *	callbackArg,
		PKCS7_GetPrivateKey	getPrivateKeyFun,
		ubyte **	decryptedInfo,
		sbyte4 *	decryptedInfoLen
	)

This function extracts and decrypts the encrypted content of a CMS EnvelopedData object.

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS7__

pkcs7.h

Parameters

pEnvelopedData	Pointer to root of `EnvelopedData` object in the given `CStream`, `s`.
s	`CStream` containing the DER-encoded PKCS #7 message that contains the ASN.1 `EnvelopedData` object to decrypt.
callbackArg	Pointer to arguments that are required by the function referenced in `getPrivateKeyFun`.
getPrivateKeyFun	Pointer to a callback function that gets the private key for the recipient of the `EnvelopedData` object. The recipient is specified by a pair of SerialNumber and IssuerName values, which uniquely identify a certificate, and therefore, a subject. These values are read from the `RecipientInfos` object of the `CStream` `s` object's `EnvelopedData` object.
decryptedInfo	On return, pointer to the address of a buffer containing the decrypted content.
decryptedInfoLen	On return, pointer to length of decrypted data, `decryptedInfo`.

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.

pkcs7.h

◆ PKCS7_DecryptEnvelopedDataAux()

MOC_EXTERN MSTATUS PKCS7_DecryptEnvelopedDataAux	(	MOC_HW(hwAccelDescr hwAccelCtx) struct ASN1_ITEM *	pEnvelopedData,
		CStream	s,
		const void *	callbackArg,
		PKCS7_GetPrivateKey	getPrivateKeyFun,
		enum encryptedContentType *	pType,
		struct ASN1_ITEM **	ppEncryptedContent,
		BulkCtx *	ppBulkCtx,
		const BulkEncryptionAlgo **	ppBulkAlgo,
		ubyte	iv[]
	)

This function extracts and decrypts the encrypted content of an EnvelopedData object, and returns its encryption details.

The EnvelopedData object is defined as follows:

    EnvelopedData ::= SEQUENCE {
        version Version,
        recipientInfos RecipientInfos,
        encryptedContentInfo EncryptedContentInfo }

    RecipientInfos ::= SET OF RecipientInfo

    EncryptedContentInfo ::= SEQUENCE {
        contentType ContentType,
        contentEncryptionAlgorithm ContentEncryptionAlgorithmIdentifier,
        encryptedContent [0] IMPLICIT EncryptedContent OPTIONAL }

    EncryptedContent ::= OCTET STRING

    RecipientInfo ::= SEQUENCE {
        version Version,
        issuerAndSerialNumber IssuerAndSerialNumber,
        keyEncryptionAlgorithm KeyEncryptionAlgorithmIdentifier,
        encryptedKey EncryptedKey }

    EncryptedKey ::= OCTET STRING

(clarify how decrypted info is returned)

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS7__

pkcs7.h

Parameters

pEnvelopedData	Pointer to root of `EnvelopedData` object in the given `CStream`, `s`.
s	`CStream` containing the DER-encoded PKCS #7 message that contains the ASN.1 `EnvelopedData` object to decrypt.
callbackArg	Pointer to arguments that are required by the function referenced in `getPrivateKeyFun`.
getPrivateKeyFun	Pointer to a callback function that gets the private key for the recipient of the `EnvelopedData` object. The recipient is specified by a pair of SerialNumber and IssuerName values, which uniquely identify a certificate, and therefore, a subject. These values are read from the `RecipientInfos` object of the `CStream` `s` object's `EnvelopedData` object.
pType	On return, pointer to `encryptedContentType` enumerated value, from pkcs_common.h, identifying the `EnvelopedData` object's content type.
ppEncryptedContent	On return, pointer to address of the encrypted data.
pBulkCtx	On return, pointer to an opaque encryption context structure.
ppBulkAlgo	On return, pointer to constant array containing information about the bulk encryption algorithm used; any of the following preconfigured BulkEncryptionAlgo arrays from crypto.c: `CRYPTO_TripleDESSuite` `CRYPTO_TwoKeyTripleDESSuite` `CRYPTO_DESSuite` `CRYPTO_RC4Suite` `CRYPTO_RC2Suite` `CRYPTO_RC2EffectiveBitsSuite` `CRYPTO_BlowfishSuite` `CRYPTO_AESSuite` `CRYPTO_AESCtrSuite` `CRYPTO_NilSuite`
iv	On return, pointer to array containing the initialization vector.

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.

pkcs7.h

◆ PKCS7_DigestData()

MOC_EXTERN MSTATUS PKCS7_DigestData	(	MOC_HASH(hwAccelDescr hwAccelCtx) struct DER_ITEM *	pStart,
		struct DER_ITEM *	pParent,
		const ubyte *	payLoadType,
		ubyte	hashType,
		const ubyte *	pPayLoad,
		ubyte4	payLoadLen,
		ubyte **	ppDigested,
		ubyte4 *	pDigestedLen
	)

This function creates a DER-encoded, ASN.1 DigestedData object for the given data.

RFC 2315 defines the DigestedData object as follows:

    DigestedData ::= SEQUENCE {
        version Version,
        digestAlgorithm DigestAlgorithmIdentifier,
        contentInfo ContentInfo,
        digest Digest }

        Digest ::= OCTET STRING

        ContentInfo ::= SEQUENCE {
            contentType ContentType,
            content
                [0] EXPLICIT ANY DEFINED BY contentType OPTIONAL }

Since: 1.41

Version: 2.02

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS7__

pkcs7.h

Parameters

pStart	NULL to not encapsulate the generated `DigestedData` object in a `ContentInfo` object; otherwise `DER_ITEMPTR` whose referenced structure contains the (mostly empty) ASN.1 DER-encoded `ContentInfo` object that serves as a container for the `DigestedData` object to create. (For details about the `ContentInfo` object and how to populate it, see the "About RFC 2315 Objects" writeup for pkcs7.dxd.)
pParent	NULL if the `pStart` parameter is NULL; otherwise `DER_ITEMPTR` for the `pStart` parameter's referenced `ContentInfo` object. In the code snippet for populating a `ContentType` object with a `EnvelopedData` object, shown in the "About RFC 2315 Objects" writeup for pkcs7.dxd, this would be the `pDigestedData` object.
payloadType	Pointer to an OID describing the data in `pPayLoad`; typically `pkcs7_data_OID`, but can be any of the following OID type constant arrays from src/asn1/oiddefs.c: pkcs7_data_OID pkcs7_signedData_OID pkcs7_envelopedData_OID pkcs7_signedAndEnvelopedData_OID pkcs7_digestedData_OID (rarely applicable) pkcs7_encryptedData_OID
hashType	Hash function to use to create the digest; any of the following enum values from src/crypto/crypto.h: `ht_md2` `ht_md4` `ht_md5` `ht_sha1` `ht_sha256` `ht_sha384` `ht_sha512` `ht_sha224`
pPayload	Pointer data to digest.
payloadLen	Pointer to length of payload, `pPayLoad`.
ppDigested	On return, if `pStart` = NULL, pointer to the address of a DER-encoded, version 1, ASN.1 `DigestedData` object; otherwise, pointer to a DER-encoded ASN.1 `ContentInfo` structure that contains the `DigestedData` object created by this function.
pDigestedLen	On return, pointer to length of the `DigestedData` object, `ppDigested`.

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.

pkcs7.h

◆ PKCS7_EnvelopData()

MOC_EXTERN MSTATUS PKCS7_EnvelopData	(	MOC_HW(hwAccelDescr hwAccelCtx) struct DER_ITEM *	pStart,
		struct DER_ITEM *	pParent,
		struct ASN1_ITEM *	pCACertificatesParseRoots[],
		CStream	pStreams[],
		sbyte4	numCACerts,
		const ubyte *	encryptAlgoOID,
		RNGFun	rngFun,
		void *	rngFunArg,
		const ubyte *	pPayLoad,
		ubyte4	payLoadLen,
		ubyte **	ppEnveloped,
		ubyte4 *	pEnvelopedLen
	)

This function creates a DER-encoded, version 0, ASN.1 EnvelopedData object that contains the given payload.

RFC 2315 defines the EnvelopedData object as follows:

    EnvelopedData ::= SEQUENCE {
        version Version,
        recipientInfos RecipientInfos,
        encryptedContentInfo EncryptedContentInfo }

    RecipientInfos ::= SET OF RecipientInfo

    EncryptedContentInfo ::= SEQUENCE {
        contentType ContentType,
        contentEncryptionAlgorithm ContentEncryptionAlgorithmIdentifier,
        encryptedContent[0] IMPLICIT EncryptedContent OPTIONAL }

    EncryptedContent ::= OCTET STRING

    RecipientInfo ::= SEQUENCE {
        version Version,
        issuerAndSerialNumber IssuerAndSerialNumber,
        keyEncryptionAlgorithm KeyEncryptionAlgorithmIdentifier,
        encryptedKey EncryptedKey }

    EncryptedKey ::= OCTET STRING

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS7__

pkcs7.h

Parameters

pStart	NULL to not encapsulate the generated `EnvelopedData` object in a `ContentInfo` object; otherwise `DER_ITEMPTR` whose referenced structure contains the (mostly empty) ASN.1 DER-encoded `ContentInfo` object that serves as a container for the `EnvelopedData` object to create. (For details about the `ContentInfo` object and how to populate it, see the "About RFC 2315 Objects" writeup for pkcs7.dxd.)
pParent	NULL if the `pStart` parameter is NULL; otherwise `DER_ITEMPTR` for the `pStart` parameter's referenced `ContentInfo` object. In the code snippet for populating a `ContentType` object with a `EnvelopedData` object, shown in the "About RFC 2315 Objects" writeup for pkcs7.dxd, this would be the `pEnvelopedData` object.
pCACertificatesParseRoots	Array of `ASN1_ITEMPTR` pointers. Each `ASN1_ITEMPTR` references the root object of its corresponding certificate in the `pStreams` array.
pStreams	Array of `CStream` structures. The certificate supplied in this parameter provides the information required to create new `EnvelopedData` object's `RecipientInfo` object.
numCACerts	Pointer to number of certificates in `pStreams`.
encryptAlgoOID	Pointer to OID array that describes the type of encryption to apply to the `EnvelopedData` object. Use any of the preconfigured OID arrays from src/asn1/oiddefs.h: `aes128CBC_OID` `aes192CBC_OID` `aes256CBC_OID`
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().
pPayLoad	Pointer to the data to envelope in the `EnvelopedData` object created by this function.
payLoadLen	Pointer to length of payload, `pPayLoad`.
ppEnveloped	On return: if `pStart` = NULL, pointer to the address of a DER-encoded ASN.1 `EnvelopedData` object; otherwise, pointer to address of a DER-encoded ASN.1 `ContentInfo` object that contains the `EnvelopedData` object created by this function.
pEnvelopedLen	On return, pointer to length of `EnvelopedData` object, `ppEnveloped`.

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.

pkcs7.h

◆ PKCS7_EnvelopDataWoaep()

MOC_EXTERN MSTATUS PKCS7_EnvelopDataWoaep	(	MOC_HW(hwAccelDescr hwAccelCtx) struct DER_ITEM *	pStart,
		struct DER_ITEM *	pParent,
		struct ASN1_ITEM *	pCACertificatesParseRoots[],
		CStream	pStreams[],
		sbyte4	numCACerts,
		const ubyte *	encryptAlgoOID,
		RNGFun	rngFun,
		void *	rngFunArg,
		ubyte	isOaep,
		ubyte4	oaepHashAlgo,
		sbyte *	pOaepLabel,
		const ubyte *	pPayLoad,
		ubyte4	payLoadLen,
		ubyte **	ppEnveloped,
		ubyte4 *	pEnvelopedLen
	)

Oaep padding for RSA is available.

This function creates a DER-encoded, version 0, ASN.1 EnvelopedData object that contains the given payload. Oaep padding for RSA is available.

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS7__

pkcs7.h

Parameters

pStart	NULL to not encapsulate the generated `EnvelopedData` object in a `ContentInfo` object; otherwise `DER_ITEMPTR` whose referenced structure contains the (mostly empty) ASN.1 DER-encoded `ContentInfo` object that serves as a container for the `EnvelopedData` object to create. (For details about the `ContentInfo` object and how to populate it, see the "About RFC 2315 Objects" writeup for pkcs7.dxd.)
pParent	NULL if the `pStart` parameter is NULL; otherwise `DER_ITEMPTR` for the `pStart` parameter's referenced `ContentInfo` object. In the code snippet for populating a `ContentType` object with a `EnvelopedData` object, shown in the "About RFC 2315 Objects" writeup for pkcs7.dxd, this would be the `pEnvelopedData` object.
pCACertificatesParseRoots	Array of `ASN1_ITEMPTR` pointers. Each `ASN1_ITEMPTR` references the root object of its corresponding certificate in the `pStreams` array.
pStreams	Array of `CStream` structures. The certificate supplied in this parameter provides the information required to create new `EnvelopedData` object's `RecipientInfo` object.
numCACerts	Pointer to number of certificates in `pStreams`.
encryptAlgoOID	Pointer to OID array that describes the type of encryption to apply to the `EnvelopedData` object. Use any of the preconfigured OID arrays from src/asn1/oiddefs.h: `aes128CBC_OID` `aes192CBC_OID` `aes256CBC_OID`
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().
isOaep	For RSA encryption, use oeapPadding.
oaepHashAlgo	For RSA-OAEP encryption, the hashAlgoId to use.
pOaepLabel	For RSA-OAEP encryption, the label to use.
pPayLoad	Pointer to the data to envelope in the `EnvelopedData` object created by this function.
payLoadLen	Pointer to length of payload, `pPayLoad`.
ppEnveloped	On return: if `pStart` = NULL, pointer to the address of a DER-encoded ASN.1 `EnvelopedData` object; otherwise, pointer to address of a DER-encoded ASN.1 `ContentInfo` object that contains the `EnvelopedData` object created by this function.
pEnvelopedLen	On return, pointer to length of `EnvelopedData` object, `ppEnveloped`.

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.

pkcs7.h

◆ PKCS7_GetCertificates()

MOC_EXTERN MSTATUS PKCS7_GetCertificates	(	struct ASN1_ITEM *	pRootItem,
		CStream	s,
		struct ASN1_ITEM **	ppFirstCertificate
	)

This function determines whether a given CStream contains a PKCS #7 SignedData object, and if so, returns a pointer through the ppFirstCertificate parameter to the address of an ASN1_ITEM structure for the first certificate in the SignedData object.

Note: This function can be useful in a PKCS7_GetCertificate() callback function. After calling PKCS7_GetCertificates() on the input CStream, you can then use PKCS7_FindCertificate() to locate specific certificates.

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS7__

pkcs7.h

Parameters

pRootItem	Pointer to root of the given `CStream`, `s`, containing the `SignedData` object to search. To obtain this root item pointer, call the ASN1_Parse() function for the `CStream`, `s`. For more information about setting up the `CStream` and getting the root, see the "Setting up a CStream and Getting the ASN1_ITEM for the Root ASN.1 Object" information in the overview for the pkcs7.c file.
s	Pointer to the `CStream` containig the `SignedData` from which to get the first certificate.
ppFirstCertificate	On return, pointer to address of the `ASN1_ITEM` structure for the first certificate in `s`.

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.

pkcs7.h

◆ PKCS7_GetSignerDigestAlgo()

MOC_EXTERN MSTATUS PKCS7_GetSignerDigestAlgo	(	struct ASN1_ITEM *	pSignerInfo,
		CStream	cs,
		ubyte *	hashAlgoId
	)

This function gets a SignerInfo object's digest hash function identifier.

RFC 2315 defines the SignerInfo object as follows:

    SignerInfo ::= SEQUENCE {
        version Version,
        issuerAndSerialNumber IssuerAndSerialNumber,
        digestAlgorithm DigestAlgorithmIdentifier,
        authenticatedAttributes
            [0] IMPLICIT Attributes OPTIONAL,
        digestEncryptionAlgorithm DigestEncryptionAlgorithmIdentifier,
        encryptedDigest EncryptedDigest,
        unauthenticatedAttributes
           [1] IMPLICIT Attributes OPTIONAL }

       EncryptedDigest ::= OCTET STRING

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS7__

pkcs7.h

Parameters

pSignerInfo	ASN1_ITEMPTR pointer to the `SignerInfo` object from which to get its digest algorithm. How to get this ASN1_ITEMPTR depends on the type of ASN.1 object that contains the `SignerInfo` object of interest. If you know the the object's ASN.1 definition, you can use ASN1_GetNthChild() and other functions from src/asn1/parseasn1.c to navigate a DER-encoded, ASN.1 object.
cs	Pointer to `CStream` that contains the `SignerInfo` object of interest, `pSignerInfo`.
hashAlgoId	On return, pointer to hash function specified in the `SignerInfo` object's `digestAlgorithm`; typically any of the following enum values from src/crypto/crypto.h: `ht_md2` `ht_md4` `ht_md5` `ht_sha1` `ht_sha256` `ht_sha384` `ht_sha512` `ht_sha224`

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.

pkcs7.h

◆ PKCS7_GetSignerSignatureAlgo()

MOC_EXTERN MSTATUS PKCS7_GetSignerSignatureAlgo	(	struct ASN1_ITEM *	pSignerInfo,
		CStream	cs,
		ubyte *	pubKeyAlgoId
	)

This function gets a SignerInfo object's digest encryption algorithm identifier (the child digestEncryptionAlgorithm object).

RFC 2315 defines the SignerInfo object as follows:

    SignerInfo ::= SEQUENCE {
        version Version,
        issuerAndSerialNumber IssuerAndSerialNumber,
        digestAlgorithm DigestAlgorithmIdentifier,
        authenticatedAttributes
            [0] IMPLICIT Attributes OPTIONAL,
        digestEncryptionAlgorithm DigestEncryptionAlgorithmIdentifier,
        encryptedDigest EncryptedDigest,
        unauthenticatedAttributes
           [1] IMPLICIT Attributes OPTIONAL }

       EncryptedDigest ::= OCTET STRING

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS7__

pkcs7.h

Parameters

pSignerInfo	ASN1_ITEMPTR pointer to the `SignerInfo` object from which to get its encryption algorithm. How to get this ASN1_ITEMPTR depends on the type of ASN.1 object that contains the `SignerInfo` object of interest. If you know the the object's ASN.1 definition, you can use ASN1_GetNthChild() and other functions from src/asn1/parseasn1.c to navigate a DER-encoded, ASN.1 object.
cs	Pointer to `CStream` that contains the `SignerInfo` object of interest, `pSignerInfo`.
pubKeyType	On return, pointer to encryption algorithm specified in the `SignerInfo` object's `digestEncryptionAlgorithm`; typically any of the following enum values from ca_mgmt.h: `akt_rsa` `akt_ecc` `akt_dsa`

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.

pkcs7.h

◆ PKCS7_GetSignerSignedAttributes()

MOC_EXTERN MSTATUS PKCS7_GetSignerSignedAttributes	(	struct ASN1_ITEM *	pSignerInfo,
		struct ASN1_ITEM **	ppFirstSignedAttribute
	)

This function gets the first signed attribute in a DER-encoded, ASN.1 SignerInfo object.

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS7__

pkcs7.h

Parameters

pSignerInfo	ASN1_ITEMPTR pointer to the `SignerInfo` object from which to get its first signed attribute. How to get this ASN1_ITEMPTR depends on the type of ASN.1 object that contains the `SignerInfo` object of interest. If you know the the object's ASN.1 definition, you can use ASN1_GetNthChild() and other functions from src/asn1/parseasn1.c to navigate a DER-encoded, ASN.1 object.
ppFirstSignedAttribute	On return, pointer to the address of an ASN1_ITEMPTR for the first signed attribute in the `SignerInfo` object, `pSignerInfo`. The referenced `ASN1_ITEM` structure does not contain data from the `SignerInfo` object; it contains the offsets and length values that you can use to find data within the `CStream` that contains the `SignerInfo` object.

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.

pkcs7.h

◆ PKCS7_GetSignerUnsignedAttributes()

MOC_EXTERN MSTATUS PKCS7_GetSignerUnsignedAttributes	(	struct ASN1_ITEM *	pSignerInfo,
		struct ASN1_ITEM **	ppFirstUnsignedAttribute
	)

This function gets the first unsigned attribute in a DER-encoded, ASN.1 SignerInfo object.

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS7__

pkcs7.h

Parameters

pSignerInfo	ASN1_ITEMPTR pointer to the `SignerInfo` object from which to get its first unsigned attribute. How to get this ASN1_ITEMPTR depends on the type of ASN.1 object that contains the `SignerInfo` object of interest. If you know the the object's ASN.1 definition, you can use ASN1_GetNthChild() and other functions from src/asn1/parseasn1.c to navigate a DER-encoded, ASN.1 object.
ppFirstUnsignedAttribute	On return, pointer to the address of an ASN1_ITEMPTR for the first unsigned attribute in the `SignerInfo` object, `pSignerInfo`. The referenced `ASN1_ITEM` structure does not contain data from the `SignerInfo` object; it contains the offsets and length values that you can use to find data within the `CStream` that contains the `SignerInfo` object.

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.

pkcs7.h

◆ PKCS7_SignData()

MOC_EXTERN MSTATUS PKCS7_SignData	(	MOC_ASYM(hwAccelDescr hwAccelCtx) ubyte4	flags,
		struct DER_ITEM *	pStart,
		struct DER_ITEM *	pParent,
		struct ASN1_ITEM *	pCACertificatesParseRoots[],
		CStream	pCAStreams[],
		sbyte4	numCACerts,
		struct ASN1_ITEM *	pCrlsParseRoots[],
		CStream	pCrlStreams[],
		sbyte4	numCrls,
		signerInfoPtr *	pSignerInfos,
		ubyte4	numSigners,
		const ubyte *	payLoadType,
		const ubyte *	pPayLoad,
		ubyte4	payLoadLen,
		RNGFun	rngFun,
		void *	rngFunArg,
		ubyte **	ppSigned,
		ubyte4 *	pSignedLen
	)

This function creates a DER-encoded, version 1, ASN.1 SignedData object for the data internal or external to the SignedData object.

RFC 2315 defines the SignedData object as follows:

    SignedData ::= SEQUENCE {
        version Version,
        digestAlgorithms DigestAlgorithmIdentifiers,
        contentInfo ContentInfo,
        certificates [0] IMPLICIT ExtendedCertificatesAndCertificates OPTIONAL,
        crls [1] IMPLICIT CertificateRevocationLists OPTIONAL,
        signerInfos SignerInfos }

    DigestAlgorithmIdentifiers ::=

        SET OF DigestAlgorithmIdentifier

        SignerInfos ::= SET OF SignerInfo

        SignerInfo ::= SEQUENCE {
            version Version,
            issuerAndSerialNumber IssuerAndSerialNumber,
            digestAlgorithm DigestAlgorithmIdentifier,
            authenticatedAttributes [0] IMPLICIT Attributes OPTIONAL,
            digestEncryptionAlgorithm DigestEncryptionAlgorithmIdentifier,
            encryptedDigest EncryptedDigest,
            unauthenticatedAttributes [1] IMPLICIT Attributes OPTIONAL }

       EncryptedDigest ::= OCTET STRING

If you use this function to create an unsigned SignedData object, the resulting object is referred to as degenerate. RFC 2315 says you can use degenerate objects to distribute certificates and certificate revocation lists.

As required by RFC 2315, you can create a SignedData object that does not contain all the certificates needed to verify all the signatures, so long as the SignedData object is expected to have access to a certificate store contaiing the required signatures.

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS7__

pkcs7.h

Parameters

flags	Zero (0) or bitmask combination (created by `OR`ing definitions together) specifying which signing elements to include.
pStart	NULL to not encapsulate the generated `SignedData` object in a `ContentInfo` object; otherwise `DER_ITEMPTR` whose referenced structure contains the (mostly empty) ASN.1 DER-encoded `ContentInfo` object that serves as a container for the `SignedData` object to create. (For details about the `ContentInfo` object and how to populate it, see the "About RFC 2315 Objects" writeup for pkcs7.dxd.)
pParent	NULL if the `pStart` parameter is NULL; otherwise \ DER_ITEMPTR for the `pStart` parameter's referenced `ContentInfo` object. In the code snippet for populating a `ContentType` object with a `SignedData` object, shown in the "About RFC 2315 Objects" writeup for pkcs7.dxd, this would be the `pSignedData` object.
pCACertificatesParseRoots	NULL to exclude certificates from the resultant `SignedData` object; otherwise array of `ASN1_ITEMPTR` pointers. The first array element references the first certificate in the `CStream`, `pCAStreams`, that contains the certificates to include in the resultant `SignedData` object. To get this `ASN1_ITEMPTR`, submit the `pCAStreams` to ASN1_Parse().
pCAStreams	NULL to exclude certificates from the resultant `SignedData` object; otherwise array of `CStream` objects containing the certificates to include in the resultant `SignedData` object.
numCACerts	Number of certificates in `pCAStreams`.
pCrlsParseRoots	NULL to exclude CRLs from the resultant `SignedData` object; otherwise array of `ASN1_ITEMPTR` pointers. The first array element references the first CRL in the `CStream`, `pCrlStreams`, that contains the CRLs to include in the resultant `SignedDat` object. To get this `ASN1_ITEMPTR`, submit the `pCrlStreams` to ASN1_Parse().
pCrlStreams	NULL to exclude CRLs from the resultant `SignedData` object; otherwise array of `CStream` objects containing the CRLs to include in the resultant `SignedData` object.
numCrls	Number of CRLs in `pCrlStreams`.
pSignerInfos	NULL to create an unsigned (degenerate) `SignedData` object; otherwise pointer to array of `signerInfo` structures, each of which contains the signing information for a single signer. For details about populating this structure, see signerInfo.
numSigners	0 (zero) if `pSignerInfos` is NULL; otherwise nubmer of elements in the `pSignerInfos` array.
payLoadType	Pointer to an OID describing the data in `pPayLoad`; typically `pkcs7_data_OID`, but can be any of the following OID type constant arrays from src/asn1/oiddefs.c: pkcs7_data_OID pkcs7_signedData_OID pkcs7_envelopedData_OID pkcs7_signedAndEnvelopedData_OID pkcs7_digestedData_OID pkcs7_encryptedData_OID
pPayLoad	Pointer to data for which to create signatures.
payLoadLen	Pointer to length of payload, `pPayLoad`.
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().
ppSigned	On return, if `pStart` = NULL, pointer to the address of a DER-encoded, version 1, ASN.1 `SignedData` object; otherwise, pointer to a DER-encoded ASN.1 `ContentInfo` structure that contains the `SignedData` object created by this function.
pSignedLen	On return, pointer to length of the `SignedData` object, `ppSigned`.

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.

pkcs7.h

◆ PKCS7_VerifySignedData()

MOC_EXTERN MSTATUS PKCS7_VerifySignedData	(	MOC_ASYM(hwAccelDescr hwAccelCtx) struct ASN1_ITEM *	pSignedData,
		CStream	s,
		const void *	callbackArg,
		PKCS7_GetCertificate	getCertFun,
		PKCS7_ValidateRootCertificate	valCertFun,
		const ubyte *	payLoad,
		ubyte4	payLoadLen,
		sbyte4 *	numKnownSigners
	)

This function verifies the signature of a PKCS #7 DER-encoded ASN.1 SignedData object that contains the signature; that is, the signature is not detached.

Note: To verify the signature of SignedData object that has a detached signature, call the PKCS7_VerifySignedDataEx() function.

Information about the signers and their hash values is extracted from the SignerInfo objects in the SignedData object. If the getCertFun parameter is NULL, this function searches the SignedData object directly for certificates that match the IssuerName and SerialNumber for each signer in the SignedData object.

If the getCertFun parameter contains a callback function that conforms to the PKCS7_GetCertificate typedef, this function does not search the SignedData object directly for matching certificates, but passes the CStream containing the SignedData object to the callback, which performs the search.

This supports the RFC 2315 requirement that the SignedData object does not need to include all of the certificates needed to verify all signatures. In this case, it is assumed that the recipient of the SignedData object can obtain the additional certificates from an external source.

After finding a certificate for a signer of the SignedData object, this function uses the callback specified by the valCertFun parameter to validate the certificate. If the certificate is expired, recalled, or otherwise compromised, this function will not verify the signature.

If the certificate is valid, this function uses it to verify the signature of the SignedData object's signed data.

On return, this function uses the numKnownSigners parameter to provide a count of the signatures that it was able to verify. A value of 0 (zero) indicates that this function could not verify any of the signatures.

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_PKCS7__

pkcs7.h

Parameters

pSignedData	Pointer to `ASN1_ITEM` structure containing the root of the DER-encoded ASN.1 `ContentInfo` object (PKCS #7 message) that contains the `SignedData` object for which to verify the signature(s).
s	`CStream` containing the `ContentInfo` object (PKCS #7 message) that contains a `SignedData` object. For more information about setting up the `CStream` and getting the root, see the "Setting up a CStream and Getting the ASN1_ITEM for the Root ASN.1 Object" information in the overview information for the pkcs7.dxd file.
callbackArg	Pointer to arguments that are required by the function referenced in `getCertFun`.
getCertFun	NULL if the `SignedData` object contains all the certificates needed to verify all of the signatures of the `SignedData` object. Otherwise, pointer to a callback function conforming to the typedef, PKCS7_GetCertificate(), which searches an external `CStream` store of certificates for a matching certificate.
valCertFun	Pointer to a callback function conforming to the PKCS7_ValidateRootCertificate() typedef, validates certificates in the `SignedData` object or from an external source.
payLoad	NULL if the `SignedData` object contains the signed data; otherwise (for detached signatures) pointer to external data for which the signature(s) were generated.
payLoadLen	Length of payload parameter, `payLoad`.
numKnownSigners	On return, pointer to number of recognized signers.

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.

pkcs7.h

◆ PKCS8_decodePrivateKeyDER()

MOC_EXTERN MSTATUS PKCS8_decodePrivateKeyDER	(	const ubyte *	pFileDerPkcs8,
		ubyte4	fileSizeDerPkcs8,
		ubyte **	ppRsaKeyBlob,
		ubyte4 *	pRsaKeyBlobLength
	)

This function extracts a private key from a DER-encoded PKCS #8 object.

To enable this function, the following flags must be defined in moptions.h:

__ENABLE_MOCANA_PKCS8__
__ENABLE_MOCANA_DER_CONVERSION__

pkcs8.h

Parameters

pFileDerPkcs8	Pointer to the name of the file containing the DER-encoded PKCS #8 object.
fileSizeDerPkcs8	Number of bytes in the DER-encoded object file, `pFileDerPkcs8`.
ppRsaKeyBlob	On return, pointer to address of buffer containing the private key (in Digicert SoT Platform keyblob format) extracted from the DER-encoded PKCS #8 object.
pRsaKeyBlobLength	On return, pointer to length of the extracted key, `ppRsaKeyBlob`.

ubyte* keyBlob = NULL;
ubyte4 keyBlobLen;
if (OK > (status =
    PKCS8_decodePrivateKeyDER(
        (ubyte*)content, contentLen, &keyBlob, &keyBlobLen)))
    goto exit;

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.

pkcs8.h

◆ PKCS8_decodePrivateKeyPEM()

MOC_EXTERN MSTATUS PKCS8_decodePrivateKeyPEM	(	const ubyte *	pFilePemPkcs8,
		ubyte4	fileSizePemPkcs8,
		ubyte **	ppRsaKeyBlob,
		ubyte4 *	pRsaKeyBlobLength
	)

This function extracts a private key from a PEM-encoded PKCS #8 object.

To enable this function, the following flags must be defined in moptions.h:

__ENABLE_MOCANA_PKCS8__
__ENABLE_MOCANA_PEM_CONVERSION__

pkcs8.h

Parameters

pFilePemPkcs8	Pointer to the name of the file containing the PEM-encoded PKCS #8 object.
fileSizePemPkcs8	Number of bytes in the PEM-encoded object file, `pFilePemPkcs8`.
ppRsaKeyBlob	On return, pointer to address of buffer containing the private key (in Digicert SoT Platform keyblob format) extracted from the PEM-encoded PKCS #8 object.
pRsaKeyBlobLength	On return, pointer to length of the extracted key, `ppRsaKeyBlob`.

ubyte* keyBlob = NULL;
ubyte4 keyBlobLen;
if (OK > (status =
    PKCS8_decodePrivateKeyPEM(
        (ubyte*)content, contentLen, &keyBlob, &keyBlobLen)))
    goto exit;

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.

pkcs8.h

◆ PKCS_getPKCS8Key()

MOC_EXTERN MSTATUS PKCS_getPKCS8Key	(	MOC_ASYM(hwAccelDescr hwAccelCtx) const ubyte *	pPKCS8DER,
		ubyte4	pkcs8DERLen,
		AsymmetricKey *	pKey
	)

This function extracts an SoT Platform-formatted key from an unencrypted PKCS #8 DER file.

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_CERTIFICATE_PARSING__

pkcs_key.h

Parameters

hwAccelCtx	For future use.
pPKCS8DER	Pointer to buffer containing PKCS #8 DER file contents.
pkcs8DERLen	Number of bytes in PKCS #8 DER file (`pPKCS8DER`).
pKey	On return, pointer to Mocana-formatted 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.

pkcs_key.h

◆ PKCS_getPKCS8KeyEx()

MOC_EXTERN MSTATUS PKCS_getPKCS8KeyEx	(	MOC_HW(hwAccelDescr hwAccelCtx) const ubyte *	pPKCS8DER,
		ubyte4	pkcs8DERLen,
		const ubyte *	password,
		ubyte4	passwordLen,
		AsymmetricKey *	pKey
	)

This function extracts an SoT Platform-formatted key from a PKCS #8 DER file (which can be encrypted or unencrypted).

To enable this function, the following flag must #not# be defined:

__DISABLE_MOCANA_CERTIFICATE_PARSING__

pkcs_key.h

Parameters

hwAccelCtx	For future use.
pPKCS8DER	Pointer to buffer containing PKCS #8 DER file contents.
pkcs8DERLen	Number of bytes in PKCS #8 DER file (`pPKCS8DER`).
password	For an encrypted file, pointer to buffer contaning password; otherwise NULL.
passwordLen	For an encrypted file, number of bytes in the password (`password`); otherwise not used.
pKey	On return, pointer to Digicert SoT Platform-formatted 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.

pkcs_key.h

Functions

Detailed Description

Function Documentation

◆ CMC_SignData()

◆ PKCS10_CertReqToCSR()

◆ PKCS10_GenerateCertReqFromASN1Name()

◆ PKCS10_GenerateCertReqFromDN()

◆ PKCS10_GenerateCertReqFromDNEx()

◆ PKCS12_decrypt()

◆ PKCS12_DecryptPFXPduPwMode()

◆ PKCS12_encrypt()

◆ PKCS12_EncryptPFXPdu()

◆ PKCS12_EncryptPFXPduCertMode()

◆ PKCS12_EncryptPFXPduPwMode()

◆ PKCS12_ExtractInfo()

◆ PKCS12_GetEncryptionAlgo()

Using CreateBulkCtxFunc typedef

Using CipherFunc typedef

Using DeleteBulkCtxFunc

Generating Initialization Vectors

Padding

◆ PKCS5_CreateKey_PBKDF1()

◆ PKCS5_CreateKey_PBKDF2()

◆ PKCS5_decrypt()

◆ PKCS5_decryptV2()

◆ PKCS5_encryptV1()

◆ PKCS5_encryptV2()

◆ PKCS7_DecryptEnvelopedData()

◆ PKCS7_DecryptEnvelopedDataAux()

◆ PKCS7_DigestData()

◆ PKCS7_EnvelopData()

◆ PKCS7_EnvelopDataWoaep()

◆ PKCS7_GetCertificates()

◆ PKCS7_GetSignerDigestAlgo()

◆ PKCS7_GetSignerSignatureAlgo()

◆ PKCS7_GetSignerSignedAttributes()

◆ PKCS7_GetSignerUnsignedAttributes()

◆ PKCS7_SignData()

◆ PKCS7_VerifySignedData()

◆ PKCS8_decodePrivateKeyDER()

◆ PKCS8_decodePrivateKeyPEM()

◆ PKCS_getPKCS8Key()

◆ PKCS_getPKCS8KeyEx()

Using `CreateBulkCtxFunc` typedef

Using `CipherFunc` typedef