CMS_ReadEnvDataToString

CryptoSys PKI Pro Manual

CMS_ReadEnvDataToString

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

VBA/VB6 Syntax


Public Declare Function CMS_ReadEnvDataToString Lib "diCrPKI.dll" 
    (ByVal strDataOut As String, ByVal nDataLen As Long, 
    ByVal strFileIn As String, ByVal strCertFile As String, 
    ByVal strPrivateKey As String, ByVal nOptions As Long) As Long

nRet = CMS_ReadEnvDataToString(strDataOut, nDataLen, strFileIn, strCertFile, strPrivateKey, nOptions) As Long

C/C++ Syntax


long __stdcall CMS_ReadEnvDataToString(char *szOutput, long nOutChars, const char *szFileIn, const char *szCertFile, const char *szPrivateKey, long nOptions);

Parameters

szOutput: [out] buffer to receive output plaintext.
nOutChars: [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 cmsReadEnvDataToString (szFileIn As String, szCertFile As String, szPrivateKey As String, Optional nOptions As Long = 0) As String

.NET Equivalent

Cms.ReadEnvDataToString Method

Python Equivalent

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

Remarks

For the "raw" VBA/C function, the user must allocate an output string buffer szOutput of the required length. Specify a zero nOutChars or an empty string for szOutput to find the required length. ANSI C users must add one to this value when allocating memory.

See the remarks for CMS_ReadEnvData() above. 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 only if the output plaintext is known to be plain ASCII text with no embedded NUL (zero) characters, otherwise use CMS_ReadEnvDataToBytes.

Example (VBA core function)

The following example reads the file created with CMS_MakeEnvData above. Bob's private key needs to be read into a string first (see RSA_ReadAnyPrivateKey). The output is written into a string.

    Dim strPrivateKey As String
    Dim strFileIn As String
    Dim strDataOut As String
    Dim nLen As Long
    Dim strCertFile As String
    
    strFileIn = "cms2bobandcarl.p7m"
    
    ' First, Bob reads his private key into a string
    strPrivateKey = rsaReadPrivateKey("BobPrivRSAEncrypt.p8e", "password")
    If Len(strPrivateKey) = 0 Then
        MsgBox "Cannot read private key"
        Exit Sub
    End If
    
    ' Query the size of encrypted content (no need for an output buffer)
    nLen = CMS_QueryEnvData("", 0, strFileIn, "sizeofEncryptedContent", 0)
    Debug.Print "CMS_QueryEnvData returns " & nLen
    
    If nLen <= 0 Then
        GoTo CleanUp
    End If
    
    ' Pre-dimension string and read in the plaintext
    ' The final plaintext will always be shorter than the encrypted content.
    strDataOut = String(nLen, " ")
    nLen = CMS_ReadEnvDataToString(strDataOut, nLen, _
        strFileIn, "", strPrivateKey, 0)
    Debug.Print "CMS_ReadEnvDataToString returns " & nLen
    If nLen > 0 Then
        ' Fix correct size for final, unpadded plaintext
        strDataOut = Left(strDataOut, nLen)
        Debug.Print "Plaintext is '" & strDataOut & "'"
    End If
    
CleanUp:
    WIPE_String strPrivateKey, Len(strPrivateKey)
    strPrivateKey = ""

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)