CMS_QueryEnvData

CryptoSys PKI Pro Manual

CMS_QueryEnvData

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

VBA/VB6 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

C/C++ Syntax


long __stdcall CMS_QueryEnvData(char *szOutput, long nOutChars, const char *szFileIn, const char *szQuery, long nOptions);

Parameters

szOutput: [out] to receive the output.
nOutChars: [in] specifying the length of the output string.
szFileIn: [in] with name of signed-data CMS object file or the data as a base64 or PEM string.
szQuery: [in] specifying the query (see Remarks below).
nOptions: [in] option flags:
PKI_DEFAULT (0) for default options
PKI_QUERY_GETTYPE to return the type of data returned for a given query.

Returns (VBA/C)

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.

VBA Wrapper Syntax

Public Function cmsQueryEnvData (szFileIn As String, szQuery As String, Optional nOptions As Long = 0) As String

.NET Equivalent

Cms.QueryEnvData Method

C++ (STL) Equivalent

static std::string dipki::Cms::QueryEnvData (const std::string &inputFile, const std::string &query)

Python Equivalent

static Cms.query_envdata(cmsfile, query)

Remarks

This function queries a given EnvelopedData file for selected information. The query string is case-insensitive, so "version", "VERSION" and "VeRsIoN" are all valid.

Valid queries are (case-insensitive):

Query String	Returns	Data Type
`version`	envelopedData CMSVersion (`edVer`) value	Number
`recipientInfoVersion`	recipientInfo version (`riVer`) value	Number
`recipientInfoType`	Type of recipientInfo: `ktri`, `kari`, `kekri`, `pwri`, `ori`	String
`CountOfRecipientInfos`	Number of RecipientInfos included in the data	Number
`recipientIssuerName`	Distinguished Name of recipient's certificate issuer	String
`recipientSerialNumber`	serialNumber of recipient's certificate in hex format	String
`keyEncryptionAlgorithm`	keyEncryptionAlgorithm, e.g. `"rsaEncryption"`	String
`keyEncryptionFlags`	Bit flags used for the key encryption algorithm (ktri only)	Number
`SizeOfEncryptedKey`	Size (in bytes) of the EncryptedKey	Number
`encryptedKey`	EncryptedKey value encoded in hex	String
`oaepParams`	Parameters used for RSA-OAEP (if applicable).	String
`kemParams`	Parameters used for RSA-KEM (if applicable) [New in v23.0]	String
`keyWrapAlgorithm`	Key wrap algorithm, e.g. `"aes128-wrap"` (kari and kekri only)	String
`originatorKeyAlgorithm`	OriginatorPublicKey algorithm, e.g. `"ecPublicKey"` (kari only)	String
`originatorPublicKey`	OriginatorPublicKey publicKey value encoded in hex (kari only)	String
`keyid`	keyIdentifier for KEKRecipientInfo (kekri) type	String
`ukm`	User Keying Material (if applicable) [New in v23.0]	String
`contentEncryptionAlgorithm`	contentEncryptionAlgorithm, e.g. `"des-EDE3-CBC"`	String
`SizeOfEncryptedContent`	Size (in bytes) of the EncryptedContent	Number
`encryptedContent`	EncryptedContent encoded in hex	String
`iv`	Initialization vector for encrypted content encoded in hex	String
`HASsubjectKeyIdentifier`	1 if recipientIdentifier is the CHOICE subjectKeyIdentifier; 0 if issuerAndSerialNumber [New in v23.0]	Number
`recipientIdentifier`	recipientIdentifier value encoded in hex [New in v23.0]	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 encryptedContent may be slow to respond if the file is large.

The "raw" VBA/C function behaves differently depending on whether the output is a string or a number. If the result data type is a number then it returns the value directly. If the result is a string, then it sets szOutput and returns the number of characters in the string. The required number of characters can be found by passing zero for nOutChars or a null string for szOutput. ANSI C users must add one to this value when allocating memory.

Note that the VBA wrapper function and the C#/VB.NET and C++ (STL) methods always return a string, which is different from the behaviour of the raw VB6/C function.

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);

will return PKI_QUERY_NUMBER.

Example (VBA core function)

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 = "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 = "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 5.1.bin...
version=0
contentEncryptionAlgorithm=des-EDE3-CBC
sizeofEncryptedContent=32
countOfRecipientInfos=1
keyEncryptionAlgorithm=rsaEncryption
sizeofEncryptedKey=128
File 5.2.bin...
Version=2
contentEncryptionAlgorithm=rc2CBC

Example (VBA wrapper function)

Dim strQuery As String
Dim strOutput As String
Dim strEnvDataFile As String

strEnvDataFile = "5.1.bin"
Debug.Print "FILE: " & strEnvDataFile
strQuery = "keyEncryptionAlgorithm"
strOutput = cmsQueryEnvData(strEnvDataFile, strQuery, 0)
Debug.Print strQuery & " ==> " & strOutput
strQuery = "contentEncryptionAlgorithm"
strOutput = cmsQueryEnvData(strEnvDataFile, strQuery, 0)
Debug.Print strQuery & " ==> " & strOutput
strQuery = "sizeofEncryptedContent"
strOutput = cmsQueryEnvData(strEnvDataFile, strQuery, 0)
Debug.Print strQuery & " ==> " & strOutput