CMS_QueryEnvData

CryptoSys PKI Toolkit Manual

CMS_QueryEnvData

Queries a CMS enveloped-data object file for selected information.

VB6/VBA Syntax


Public Declare Function CMS_QueryEnvData Lib "diCrPKI.dll" 
    (ByVal strDataOut As String, ByVal nDataLen As Long, 
    ByVal strFileIn As String, ByVal strQuery As String, ByVal nOptions As Long) As Long

nRet = CMS_QueryEnvData(strDataOut, nDataLen, strFileIn, strQuery, nOptions) As Long

Parameters

strDataOut: [out] String to receive the output.
nDataLen: [in] Long specifying the length of the output string.
strFileIn: [in] String with name of signed-data CMS object file or the data as a base64 or PEM string.
strQuery: [in] String specifying the query (see Remarks below).
nOptions: [in] Long option flags:
PKI_DEFAULT (0) for default options
PKI_CMS_FORMAT_BASE64 to read base64-encoded input (default expected BER-encoded binary) [not required in v3.5 and above]
PKI_QUERY_GETTYPE to return the type of data returned for a given query.

C/C++ Syntax


long _stdcall CMS_QueryEnvData(char *szDataOut, long nDataOutLen, const char *szFileIn,
	const char *szQuery, long nOptions);

Returns (VB6/C)

Long: If successful, the return value is a positive integer indicating either the result itself (if the result is a number) or the number of characters in the output string (if the query is looking for a string). If the item queried cannot be found, the return value is zero. If there is an error (e.g. an invalid signed-data file), it returns a negative error code.

.NET Equivalent

Cms.QueryEnvData Method

Remarks

This function queries a given EnvelopedData file for selected information. If the result data type is a number then it returns the value directly. If the result is a string, then it sets strDataOut and returns the number of characters in the string. Note the difference in behaviour depending on the data type of the result for the VB/C functions. However, the C#/VB.NET methods always return a string. The query string is case-insensitive, so "version", "Version" and "VeRsIoN" are all valid. Only version 0 enveloped-data objects with version 0 recipientInfos are fully supported. The function will attempt to query other versions but may not succeed.

Valid queries are:

Query String	Searches for	Data Type
`version`	envelopedData CMSVersion value	Number
`countOfRecipientInfos`	Number of RecipientInfos included in the data	Number
`contentEncryptionAlgorithm`	contentEncryptionAlgorithm, e.g. `"des-EDE3-CBC"`	String
`sizeofEncryptedContent`	Size (in bytes) of the EncryptedContent	Number
`recipientInfoVersion`	recipientInfo version (riVer) value	Number
`keyEncryptionAlgorithm`	keyEncryptionAlgorithm, e.g. `"rsaEncryption"`	String
`keyEncryptionFlags`	Bit flags used for the key encryption algorithm	Number
`sizeofEncryptedKey`	Size (in bytes) of the EncryptedKey	Number
`recipientIssuerName`	Distinguished Name of recipient's certificate issuer	String
`recipientSerialNumber`	serialNumber of recipient's certificate in hex format	String

By default, the function queries the first recipientInfo in the file. To query the nth recipientInfo append "/n" to the query string, e.g. "recipientInfoVersion/2" to find the version number of the second recipientInfo in the file.

The query keyEncryptionFlags returns the bit flags used for the key encryption algorithm. In C#/VB.NET this will be a decimal number string that should be converted to an integer. For rsaEncryption this number will be zero. For RSA-KEM, you should be able to AND this number with the various flags for block cipher and hash algorithms to determine the parameters used for the key encapsulation mechanism.

To find out the type of data returned for a given query, use the PKI_QUERY_GETTYPE option. The function will return either PKI_QUERY_NUMBER (1) or PKI_QUERY_STRING (2), or a negative "invalid query" error. For example

nRet = CMS_QueryEnvData("", 0, "", "version", PKI_QUERY_GETTYPE)

Example

This example queries information from various sample files.

Dim strCmsFile As String
Dim nRet As Long
Dim strOutput As String
Dim strQuery As String

' Pre-dimension output string
strOutput = String(64, " ")

strCmsFile = "C:\Test\5.1.bin"
Debug.Print "File " & strCmsFile & "..."
strQuery = "version"
nRet = CMS_QueryEnvData(vbNullString, 0, strCmsFile, strQuery, 0)
Debug.Print strQuery & "=" & nRet
strQuery = "contentEncryptionAlgorithm"
nRet = CMS_QueryEnvData(strOutput, Len(strOutput), strCmsFile, strQuery, 0)
If nRet > 0 Then
    Debug.Print strQuery & "=" & Left$(strOutput, nRet)
End If
strQuery = "sizeofEncryptedContent"
nRet = CMS_QueryEnvData(vbNullString, 0, strCmsFile, strQuery, 0)
Debug.Print strQuery & "=" & nRet
strQuery = "countOfRecipientInfos"
nRet = CMS_QueryEnvData(vbNullString, 0, strCmsFile, strQuery, 0)
Debug.Print strQuery & "=" & nRet
strQuery = "keyEncryptionAlgorithm"
nRet = CMS_QueryEnvData(strOutput, Len(strOutput), strCmsFile, strQuery, 0)
If nRet > 0 Then
    Debug.Print strQuery & "=" & Left$(strOutput, nRet)
End If
strQuery = "sizeofEncryptedKey"
nRet = CMS_QueryEnvData(vbNullString, 0, strCmsFile, strQuery, 0)
Debug.Print strQuery & "=" & nRet

strCmsFile = "C:\Test\5.2.bin"
Debug.Print "File " & strCmsFile & "..."
nRet = CMS_QueryEnvData(strOutput, Len(strOutput), strCmsFile, "version", 0)
Debug.Print "Version=" & nRet
nRet = CMS_QueryEnvData(strOutput, Len(strOutput), strCmsFile, "contentEncryptionAlgorithm", 0)
If nRet > 0 Then
    Debug.Print "contentEncryptionAlgorithm=" & Left$(strOutput, nRet)
End If

In this example, file 5.1.bin is CMS Version 0 with content encryption algorithm des_EDE3-CBC, and file 5.2.bin is CMSVersion 2 with content encryption algorithm rc2CBC.

File C:\Test\5.1.bin...
version=0
contentEncryptionAlgorithm=des-EDE3-CBC
sizeofEncryptedContent=32
countOfRecipientInfos=1
keyEncryptionAlgorithm=rsaEncryption
sizeofEncryptedKey=128
File C:\Test\5.2.bin...
Version=2
contentEncryptionAlgorithm=rc2CBC