CMS_MakeEnvDataFromBytes

CryptoSys PKI Pro Manual

CMS_MakeEnvDataFromBytes

Create a CMS enveloped-data object from data in a byte array.

VBA/VB6 Syntax


Public Declare Function CMS_MakeEnvDataFromBytes Lib "diCrPKI.dll" (ByVal strFileOut As String, ByRef lpInput As Byte, ByVal nInputLen As Long, ByVal strCertList As String, ByVal strKeyString As String, ByVal nCount As Long, ByVal nOptions As Long) As Long

nRet = CMS_MakeEnvDataFromBytes(strFileOut, lpInput(0), nInputLen, strCertList, strKeyString, nCount, nOptions) As Long

C/C++ Syntax


long __stdcall CMS_MakeEnvDataFromBytes(const char *szFileOut, const unsigned char *lpInput, long nInputLen, const char *szCertList, const char *szKeyString, long nCount, long nOptions);

Parameters

szFileOut: [in] name of output file to be created.
lpInput: [in] byte array containing the input data.
nInputLen: [in] length in bytes of input data.
szCertList: [in] list of one or more recipient X.509 certificate filenames, separated by semicolons (;). A certificate's representation in base64 or as a PEM string may be used instead of a filename. Alternatively, specify a single PKCS#7 certificate chain file (.p7c/.p7b).
Special cases: Set as "type=@pwri" to create a single recipientInfo of the PasswordRecipientInfo (pwri) type; or set as "type=@kekri,keyid=<string>" to create a single recipientInfo of the KEKRecipientInfo (kekri) type. See Remarks.
szKeyString: [in] (formerly szSeed) Use to pass optional additional user key material (ukm) for KDF where KeyAgreement (kari) type is used. Or use to pass the password for a pwri type or the key encryption key (KEK) for a kekri type. Either pass a plain ASCII string or use the format "#x<hex-digits>" to pass a string of arbitrary octet values. Required for pwri and kekri types.
Examples: "abc" will pass the 3 bytes (0x61, 0x62, 0x63); "#xdeadbeef01" will pass the 5 bytes (0xde, 0xad, 0xbe, 0xef, 0x01).
nCount: [in] (formerly nSeedLen) Optional iteration count for KDF in pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored.
nSeedLen: [in] formerly used for length of the seed string. No longer used. [IGNORED!]
nOptions: [in] option flags: see the options in CMS_MakeEnvData.

Returns (VBA/C)

If successful, the return value is the number of successful recipients; otherwise it returns a negative error code.

VBA Wrapper Syntax

Public Function cmsMakeEnvDataFromBytes (szFileOut As String, lpInput() As Byte, szCertList As String, Optional szKeyString As String = "", Optional nOptions As Long = 0, Optional nCount As Long = 0) As Long

.NET Equivalent

Cms.MakeEnvDataFromBytes Method

C++ (STL) Equivalent

static int dipki::Cms::MakeEnvDataFromBytes (const std::string &outputFile, const dipki::bvec_t &data, const std::string &certList, CipherAlg cipherAlg=CipherAlg::Default, KeyEncrAlg keyEncrAlg=KeyEncrAlg::Default, HashAlg hashAlg=HashAlg::Default, EnvDataOptions advOpts=EnvDataOptions::Default_EnvDataOpt, Format format=Format::Default, Kdf::KdfAlg kdfAlg=Kdf::KdfAlg::X963, Kdf::KeyWrapAlg keyWrapAlg=Kdf::KeyWrapAlg::Default, const std::string &ukmString="")

Python Equivalent

static Cms.make_envdata_from_bytes(outputfile, inputdata, certlist, cipheralg=ContentEncrAlg.DEFAULT, keyencralg=KeyEncrAlg.DEFAULT, hashalg=0, opts=EnvDataOpts.DEFAULT, kdfalg=Kdf.KdfAlg.X963, keywrapalg=0, keyString="", count=0)

Remarks

This function is the same as CMS_MakeEnvData except the input data is in a byte array instead of a file. See the remarks for CMS_MakeEnvData() above.

Use this function if the plaintext contains non-ASCII characters such as UTF-8 encoded.

Example

This example creates an enveloped-data object in a file 'cmsalice2bob_utf8.p7m'. The input is UTF-8-encoded data with some non-ASCII characters that encode to more than one byte. See CMS_ReadEnvDataToBytes for example code to read it.

Dim nRet As Long
Dim strEnvDataFile As String
Dim strData As String
Dim abData() As Byte
Dim nBytes As Long

' Input contains two non-ASCII characters:
'   U+00CD Latin capital letter I with acute, encodes as (0x) C3 8D
'   U+00F1 Latin small letter N with tilde, encodes as (0x) C3 B1
strData = "<doc><name c='es'>Íñigo</name></doc>"
' Convert Unicode string to UTF-8-encoded byte array
nBytes = CNV_UTF8BytesFromLatin1(ByVal 0&, 0, strData)
ReDim abData(nBytes - 1)
nBytes = CNV_UTF8BytesFromLatin1(abData(0), nBytes, strData)
Debug.Print "INPUT STR=""" & strData & """" & " (" & Len(strData) & " chars)"
Debug.Print "HEX(UTF8)=" & cnvHexStrFromBytes(abData) & " (" & UBound(abData) + 1 & " bytes)"

' Create a CMS enveloped-data object using RSA-OAEP and AES-128 for content encryption
strEnvDataFile = "cmsalice2bob_utf8.p7m"
nRet = CMS_MakeEnvDataFromBytes(strEnvDataFile, _
	abData(0), nBytes, "BobRSASignByCarl.cer", "", 0, PKI_KT_RSAES_OAEP Or PKI_BC_AES128)
' This should return 1 (indicating one successful recipient)
Debug.Print "CMS_MakeEnvDataFromBytes returns " & nRet & " (= # recipients)"
Debug.Assert nRet > 0
Debug.Print "Created enveloped-data file '" & strEnvDataFile & "'"

INPUT STR="<doc><name c='es'>Íñigo</name></doc>" (36 chars)
HEX(UTF8)=3C646F633E3C6E616D6520633D276573273EC38DC3B169676F3C2F6E616D653E3C2F646F633E (38 bytes)
CMS_MakeEnvDataFromBytes returns 1 (= # recipients)
Created enveloped-data file 'cmsalice2bob_utf8.p7m'