CMS_MakeEnvData

Creates an encrypted CMS enveloped-data object for one or more recipients using their x.509 certificates.

VB6/VBA Syntax

nRet = CMS_MakeEnvData(strFileOut, strFileIn, strCertList, strSeed, nSeedLen, nOptions) As Long

Parameters

strFileOut

[in] String with name of output file to be created.

strFileIn

[in] String with name of file containing input data.

strCertList

[in] String containing a list of files that contain the certificates of recipients separated by semi-colons(;)

strSeed

[in] String containing a user-specified seed to be used by the random number generator. Specify an empty string ("") to ignore.

nSeedLen

[in] Long specifying the length of the seed string.

nOptions

[in] Long option flags:
PKI_DEFAULT (0) for default options (rsaEncryption, des-EDE3-CBC, binary output).
PKI_CMS_FORMAT_BASE64 to format the output with base64 encoding (default output is binary)
PKI_CMS_BIGFILE to speed up the encryption of large files [new in v3.7]
PKI_CMS_ALT_ALGID to use specialist alternative encryption algorithm identifier (see Remarks)
plus, optionally, one of the following:
PKI_BC_AES128 to use aes128-CBC for content encryption
PKI_BC_AES192 to use aes192-CBC for content encryption
PKI_BC_AES256 to use aes256-CBC for content encryption
PKI_BC_3DES to use des-ede3-cbc for content encryption

C/C++ Syntax

Returns (VB6/C)

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

.NET Equivalent

Cms.MakeEnvData Method
Cms.MakeEnvData Method

Remarks

The output is always a CMS EnvelopedData file which can be sent as part of an S/MIME message. Multiple recipients are supported provided their X.509 certificates are available. No checks are made on the validity period of the recipients' X.509 certificates. Only CMS Version 0 enveloped-data objects using the key transport technique are supported. The RecipientIdentifier must be issuerAndSerialNumber. The optional fields OriginatorInfo and UnprotectedAttrs are not supported.

[New in v3.7] As of v3.7, it is an error if any specified certificate files in strCertList are missing or corrupted. Call PKI_LastError() to find more details of the errors that occurred. (Earlier versions would have indicated success if at least one certificate in the list was OK. The new requirement is that all specified certificates must be OK or an error occurs.)

[New in v3.7] Use the PKI_CMS_BIGFILE option flag to handle large files more efficiently. This results in improvements of speed typically of 30% and enables, in theory, unlimited sizes of enveloped files (subject, of course, to your level of boredom in waiting for the output).

[Specialist Option] If the PKI_CMS_ALT_ALGID option flag is present, an alternative Content Encryption Algorithm Identifier will be used as follows:

This alternative TeleTrusT algorithm identifier was added for compatibility with certain German profiles. It is not an S/MIME-compliant OID. We were initially told it was required by the German Health System PKI, but apparently not so. It is only needed for backwards compatibility. Anyway, it's there if you need it.

The RSA-KEM key encryption algorithm added provisionally in v3.2 has been withdrawn in v3.4. It is unlikely to be put back.

Example

The following example reproduces example 5.1 from [SMIME-EX]. It creates an EnvelopedData CMS object for Bob from the data file C:\test\excontent.txt using Bob's X.509 certificate BobRSASignByCarl.cer.

Dim nRet As Long
Dim strOutputFile As String
Dim strInputFile As String
Dim strCertFile As String

strOutputFile = "C:\test\cmsalice2bob.p7m"
strInputFile = "C:\test\excontent.txt"
strCertFile = "C:\test\BobRSASignByCarl.cer"
' This should return 1 (indicating one successful recipient)
nRet = CMS_MakeEnvData(strOutputFile, strInputFile, strCertFile, "", 0, 0)
Debug.Print "CMS_MakeEnvData returns " & nRet

Note that the output file will always be different from the smime-example because the content-encryption key, IV and the encrypted-content will be different each time.

The next example does the same except for two recipients: Bob and Carl.

' This should return 2 (indicating two successful recipients)
nRet = CMS_MakeEnvData("C:\test\cms2bobandcarl.p7m", "C:\test\excontent.txt", _
    "C:\test\BobRSASignByCarl.cer;C:\test\CarlRSASelf.cer", "", 0, 0)
Debug.Print "CMS_MakeEnvData returns " & nRet

The third example is the same as the first, except it uses AES-128 instead of Triple-DES to encrypt the content.

nRet = CMS_MakeEnvData("C:\test\cms2bob_aes128.p7m", "C:\test\excontent.txt", _
    "C:\test\BobRSASignByCarl.cer", "", 0, PKI_BC_AES128)
Debug.Print "CMS_MakeEnvData returns " & nRet

This example shows how to use the PKI_CMS_BIGFILE option.

Dim nRet As Long
Dim strEnvDataFile As String
Dim strInputFile As String
Dim strCheckFile As String
strEnvDataFile = "envbig.p7m"
strInputFile = "bigfile.txt"
Debug.Print "File " & strInputFile & "=" & FileLen(strInputFile) & " bytes"
' Make enveloped-data file: this should return 1 (indicating one successful recipient)
nRet = CMS_MakeEnvData(strEnvDataFile, strInputFile, "bob.cer;", "", 0, PKI_CMS_BIGFILE)
Debug.Print "CMS_MakeEnvData returns " & nRet & " (expected 1 => # recipients)"
' Now decrypt using Bob's private key
Dim strPrivateKey As String
strPrivateKey = rsaReadPrivateKey("bob.epk", "password")
strCheckFile = strEnvDataFile & ".out.txt"
nRet = CMS_ReadEnvData(strCheckFile & ".out.txt", strEnvDataFile, "", strPrivateKey, PKI_CMS_BIGFILE)
Debug.Print "CMS_ReadEnvData returns " & nRet & " (expected 0 => success)"
' Check file length
Debug.Print "File " & strCheckFile & "=" & FileLen(strCheckFile) & " bytes"

File bigfile.txt=10485700 bytes
CMS_MakeEnvData returns 1 (expected 1 => # recipients)
CMS_ReadEnvData returns 0 (expected 0 => success)
File envbig.p7m.out.txt=10485700 bytes

See Also

CMS_MakeEnvDataFromString CMS_ReadEnvData CMS_ReadEnvDataToString

[Contents] [Index]