cmsMakeEnvData

Create a CMS enveloped-data object for one or more recipients.

Syntax

Public Function cmsMakeEnvData ( _
    szFileOut As String, _
    szFileIn As String, _
    szCertList As String, _
    Optional szKeyString As String = "", _
    Optional nOptions As Long = 0, _
    Optional nCount As Long = 0 _
) As Long

Parameters

szFileOut

Name of output file to be created.

szFileIn

Name of file containing input data.

szCertList

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

(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, e.g. "abc" or use the format "#x<hex-digits>" to pass a string of arbitrary octet values, e.g. "#xdeadbeef01" to pass the 5 bytes 0xde,0xad,0xbe,0xef,0x01. Required for pwri and kekri types.

nOptions

Select the content encryption algorithm from:

PKI_BC_3DES (default)
PKI_BC_AES128
PKI_BC_AES192
PKI_BC_AES256
PKI_AEAD_AES_128_GCM
PKI_AEAD_AES_192_GCM
PKI_AEAD_AES_256_GCM
PKI_AEAD_CHACHA20_POLY1305

To set the key transport scheme (where applicable), use one of

PKI_KT_RSAES_PKCS (default)
PKI_KT_RSAES_OAEP

If you have selected PKI_KT_RSAES_OAEP then, optionally, add

PKI_MGF_MGF1SHA1

Select one hash algorithm for RSAES-OAEP or ECDH KDF or pwri PBKDF2:

PKI_HASH_SHA1 (default)
PKI_HASH_SHA224
PKI_HASH_SHA256
PKI_HASH_SHA384
PKI_HASH_SHA512

To set the key derivation function (KDF) for the ECDH key agreement scheme (where applicable), add one of:

PKI_KDF_X963 (default)
PKI_KDF_HKDF

add one key wrap algorithm for the ECDH key agreement scheme or the kekri key encryption algorithm (default=match content encryption algorithm):

PKI_KWRAP_3DES (allowed only if Triple DES is used for content encryption)
PKI_KWRAP_AES128
PKI_KWRAP_AES192
PKI_KWRAP_AES256

Optionally, add any of the bitflags:

PKI_CMS_FORMAT_BASE64 (default=binary)
PKI_CMS_ALT_ALGID
PKI_CMS_BIGFILE (binary file to binary file only)

nCount

Use to pass the iteration count for a pwri type (default=4096) or tag length for AuthEnvelopedData (in range 12-16, default=16). Otherwise ignored.

Return Value

Remarks

Example

' Create an enveloped CMS object (ktri type) to Bob using Bob's RSA key...
n = cmsMakeEnvData("cms2bob_aes128.p7m", "excontent.txt", "BobRSASignByCarl.cer", "", PKI_BC_AES128 Or PKI_KT_RSAES_OAEP)
' Same but using authenticated encryption and creating an authEnvelopedData object...
n = cmsMakeEnvData("cms2bob_aes128auth.p7m", "excontent.txt", "BobRSASignByCarl.cer", "", PKI_AEAD_AES_128_GCM Or PKI_KT_RSAES_OAEP)
' Create an enveloped CMS object (kari type) to Dana using Dana's ECC key...
n = cmsMakeEnvData("cms2dana_hkdf.p7m", "excontent.txt", "lamps-dana.encrypt.crt", "", PKI_BC_AES256 Or PKI_HASH_SHA256 Or PKI_KDF_HKDF Or PKI_KWRAP_AES256)
' Create an enveloped CMS object (kekri type) using a previously distributed symmetric key-encryption key (KEK)...
n = cmsMakeEnvData("cms_envdata_kekri.p7m", "excontent.txt", "type=@kekri,keyid=ourcommonkey", "#x0123456789ABCDEFF0E1D2C3B4A59687", PKI_BC_AES256 Or PKI_HASH_SHA256 Or PKI_KWRAP_AES128)
' Create an enveloped CMS object (pwri type) using password-based key management...
n = cmsMakeEnvData("cms_envdata_pwri.p7m", "excontent.txt", "type=@pwri", "password12345", PKI_BC_AES192)