CMS_ReadEnvDataToBytes

CryptoSys PKI Pro Manual

CMS_ReadEnvDataToBytes

Reads and decrypts CMS enveloped-data object using the recipient's private key writing the plaintext data directly into a byte array.

VBA/VB6 Syntax


Public Declare Function CMS_ReadEnvDataToBytes Lib "diCrPKI.dll" (ByRef lpOutput As Byte, ByVal nOutBytes As Long, ByVal strFileIn As String, ByVal strCertFile As String, ByVal strPrivateKey As String, ByVal nOptions As Long) As Long

nRet = CMS_ReadEnvDataToBytes(lpOutput(0), nOutBytes, strFileIn, strCertFile, strPrivateKey, nOptions) As Long

C/C++ Syntax


long __stdcall CMS_ReadEnvDataToBytes(unsigned char *lpOutput, long nOutBytes, const char *szFileIn, const char *szCertFile, const char *szPrivateKey, long nOptions);

Parameters

lpOutput: [out] buffer to receive output plaintext.
nOutBytes: [in] length in bytes of the output buffer.
szFileIn: [in] name of file containing input data (binary or base64-encoded) or the data as a base64 or PEM string.
szCertFile: [in] (optional) filename of the recipient's X.509 certificate.
szPrivateKey: [in] recipient's private key in internal string format.
nOptions: [in] option flags:
PKI_DEFAULT (0) for default options

Returns (VBA/C)

If successful, the return value is the number of bytes in the decrypted plaintext; otherwise it returns a negative error code.

VBA Wrapper Syntax

Public Function cmsReadEnvDataToBytes (szFileIn As String, szCertFile As String, szPrivateKey As String, Optional nOptions As Long = 0) As Byte()

.NET Equivalent

Cms.ReadEnvDataToBytes Method

C++ (STL) Equivalent

static bvec_t dipki::Cms::ReadEnvDataToBytes (const std::string &inputFile, const std::string &privateKey, const std::string &certFile="")

Python Equivalent

static Cms.read_envdata_to_bytes(inputfile, prikeystr, certfile="")

Remarks

See the remarks for CMS_ReadEnvData() above. Call the function with a NULL lpOutput or zero nOutBytes parameter to find out the required length of the output buffer. Alternatively, use the CMS_QueryEnvData() function with the query "sizeofEncryptedContent". This will return an upper bound on the length of the decrypted plaintext, at most 16 bytes too long. Calling CMS_ReadEnvDataToString() with a properly-sized output buffer will return the exact size of the recovered plaintext. The buffer must be large enough to receive the entire output or a SHORT_BUF_ERROR error will result.

Use this function if the output plaintext is known to contain non-ASCII characters such as UTF-8 encoded.

Example (VBA core function)

The following example reads the file created with CMS_MakeEnvDataFromBytes above. Bob's private key needs to be read into a string first (see RSA_ReadAnyPrivateKey). The UTF-8-encoded output is written into a byte array, then converted to a VB Unicode string.

    Dim strEnvDataFile As String
    Dim strData As String
    Dim abData() As Byte
    Dim nBytes As Long
    Dim strPrivateKey As String
    Dim nChars As Long
    
    ' Read encrypted content from file
    strEnvDataFile = "cmsalice2bob_utf8.p7m"
    
    '  Read in Bob's encrypted private key
    strPrivateKey = rsaReadPrivateKey("BobPrivRSAEncrypt.p8e", "password")
    If Len(strPrivateKey) = 0 Then
        MsgBox "Cannot read private key"
        Exit Sub
    End If

    ' Find required length
    nBytes = CMS_ReadEnvDataToBytes(ByVal 0&, 0, strEnvDataFile, "", strPrivateKey, 0)
    Debug.Print "CMS_ReadEnvDataToBytes returns " & nBytes
    If nBytes <= 0 Then
        MsgBox "CMS_ReadEnvDataToBytes FAILED"
        GoTo CleanUp
    End If
    ' Dimension byte array to receive data
    ReDim abData(nBytes - 1)
    ' Extract the plaintext data
    nBytes = CMS_ReadEnvDataToBytes(abData(0), nBytes, strEnvDataFile, "", strPrivateKey, 0)
    Debug.Print "HEX(PT)=" & cnvHexStrFromBytes(abData)
    ' Convert from UTF-8 to VB Unicode string
    nChars = CNV_Latin1FromUTF8Bytes(0, 0, abData(0), nBytes)
     If nChars <= 0 Then
        MsgBox "CNV_Latin1FromUTF8Bytes FAILED"
        GoTo CleanUp
    End If
    strData = String(nChars, " ")
    nChars = CNV_Latin1FromUTF8Bytes(strData, nChars, abData(0), nBytes)
    Debug.Print "PT=" & strData
    
CleanUp:
    wipeString strPrivateKey

CMS_ReadEnvDataToBytes returns 38
HEX(PT)=3C646F633E3C6E616D6520633D276573273EC38DC3B169676F3C2F6E616D653E3C2F646F633E
PT=<doc><name c='es'>Íñigo</name></doc>

Example (VBA wrapper function)

Dim strPrivateKey As String
Dim lpData() As Byte
Dim strData As String

' Read in private key to internal key string
strPrivateKey = rsaReadPrivateKey("BobPrivRSAEncrypt.p8e", "password")
Debug.Assert Len(strPrivateKey) > 0

' 1. Decrypted content is UTF-8 encoded
lpData = cmsReadEnvDataToBytes("cmsalice2bob_utf8.p7m", "", strPrivateKey, 0)
Debug.Assert cnvBytesLen(lpData) > 0
Debug.Print "HEX(PT)=" & cnvHexStrFromBytes(lpData)
' Convert from UTF-8-encoded bytes to VB Unicode string
strData = cnvLatin1FromUTF8Bytes(lpData)
Debug.Print "PT=" & strData

' 2. Decrypted content is plain ANSI string
strData = cmsReadEnvDataToString("cms2bobandcarl.p7m", "", strPrivateKey, 0)
Debug.Print "PT=" & strData

' Clean up
strPrivateKey = wipeString(strPrivateKey)