CMS_MakeEnvDataFromString

CryptoSys PKI Pro Manual

CMS_MakeEnvDataFromString

Create a CMS enveloped-data object from an ASCII string.

VBA/VB6 Syntax


Public Declare Function CMS_MakeEnvDataFromString Lib "diCrPKI.dll" 
    (ByVal strFileOut As String, ByVal strDataIn As String, 
    ByVal strCertList As String, ByVal strKeyString As String, ByVal nCount As Long, 
    ByVal nOptions As Long) As Long

nRet = CMS_MakeEnvDataFromString(strFileOut, strDataIn, strCertList, strKeyString, nCount, nOptions) As Long

C/C++ Syntax


long __stdcall CMS_MakeEnvDataFromString(const char *szFileOut, const char *szDataIn, const char *szCertList, const char *szKeyString, long nCount, long nOptions);

Parameters

szFileOut: [in] name of output file to be created.
szDataIn: [in] string containing 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.
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 cmsMakeEnvDataFromString (szFileOut As String, szInput As String, szCertList As String, Optional szKeyString As String = "", Optional nOptions As Long = 0, Optional nCount As Long = 0) As Long

.NET Equivalent

Cms.MakeEnvDataFromString Method (String, String, String, CipherAlgorithm, Cms.EnvDataOptions)
Cms.MakeEnvDataFromString Method (String, String, String, CipherAlgorithm, Cms.KeyEncrAlgorithm, HashAlgorithm, Cms.EnvDataOptions, Kdf.KdfAlg, Kdf.KeyWrapAlg, String, Int32, Cms.ContentEncrAlg)

C++ (STL) Equivalent

static int dipki::Cms::MakeEnvDataFromString (const std::string &outputFile, const std::string &inputStr, 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_string(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 an ASCII string instead of a file. See the remarks for CMS_MakeEnvData() above. Use this function only when the plaintext is only plain ASCII text, otherwise use CMS_MakeEnvDataFromBytes.

Example

The following example reproduces example 5.2 from SMIME-EX (as far as it can, because of the different random values used each time) passing the input data as a string. The output is always a new file.

' This should return 1 (indicating one successful recipient)
nRet = CMS_MakeEnvDataFromString("cmsalice2bob1.p7m", _
    "This is some sample content.", "BobRSASignByCarl.cer", "", 0, 0)
Debug.Print "CMS_MakeEnvDataFromString returns " & nRet

Example (VBA wrapper function)

Dim strCertList As String
Dim strCmsFile As String
Dim nRet As Long
Dim strQuery As String

' Use Dana's X22519 certificate
strCmsFile = "dana_alice_hkdf.p7m"
strCertList = "lamps-dana.encrypt.crt"
' Use AES256 for content encryption and Ephemeral-Static ECDH key agreement using HKDF key derivation function with SHA-256 and aes256-wrap
nRet = cmsMakeEnvDataFromString(strCmsFile, "This is some sample content.", strCertList, "", PKI_BC_AES256 Or PKI_HASH_SHA256 Or PKI_KDF_HKDF Or PKI_KWRAP_AES256)
Debug.Print "cmsMakeEnvDataFromString returns " & nRet & " (expecting 1)"
' Query EnvelopedData file
Debug.Print "FILE: " & strCmsFile
strQuery = "contentEncryptionAlgorithm"
Debug.Print "QueryEnvData('" & strQuery & "')=" & cmsQueryEnvData(strCmsFile, strQuery)
strQuery = "keyEncryptionAlgorithm"
Debug.Print "QueryEnvData('" & strQuery & "')=" & cmsQueryEnvData(strCmsFile, strQuery)
strQuery = "keyWrapAlgorithm"
Debug.Print "QueryEnvData('" & strQuery & "')=" & cmsQueryEnvData(strCmsFile, strQuery)

cmsMakeEnvDataFromString returns 1 (expecting 1)
FILE: dana_alice_hkdf.p7m
QueryEnvData('contentEncryptionAlgorithm')=aes256-CBC
QueryEnvData('keyEncryptionAlgorithm')=ecdhHKDF-SHA256
QueryEnvData('keyWrapAlgorithm')=aes256-wrap