CryptoSys PKI Pro Manual

CMS_QuerySigData

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

VBA/VB6 Syntax

Public Declare Function CMS_QuerySigData 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_QuerySigData(strDataOut, nDataLen, strFileIn, strQuery, nOptions) As Long

C/C++ Syntax

long __stdcall CMS_QuerySigData(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 cmsQuerySigData (szFileIn As String, szQuery As String, Optional nOptions As Long = 0) As String

.NET Equivalent

Cms.QuerySigData Method

C++ (STL) Equivalent

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

Python Equivalent

static Cms.query_sigdata(cmsfile, query)

Remarks

This function queries a given SignedData file for selected information. Only version 1 signed-data objects are fully supported. The function will attempt to query other versions but may not succeed. Note that this function does not verify any data, including the messageDigest attribute, it just returns what it finds. The query string is case-insensitive, so "version", "Version" and "VeRsIoN" are all valid.

Valid queries are (case-insensitive):

Query StringReturnsData Type
versionsignedData version (sdVer) valueNumber
eContentTypeContentType of the EncapsulatedContentInfo, e.g. "data"String
HASeContent1 if eContent is present; 0 if notNumber
CountOfCertificatesNumber of certificates in the SignedDataNumber
CountOfSignerInfosNumber of SignerInfos in the SignedDataNumber
CountOfDigestAlgsNumber of DigestAlgorithmIdentifiers in the SignedData [New in v23.0]Number
certificate/NNth certificate encoded in base64 [New in v23.0]String
signerInfoVersionsignerInfo version (siVer) valueNumber
digestAlgorithmdigestAlgorithm, e.g. "sha1"String
signatureAlgorithmsignatureAlgorithm, e.g. "rsaEncryption"String
signatureValueSignature value encoded in hexString
HASsignedAttributes1 if signedAttributes (authenticatedAttributes) are present; 0 if notNumber
DigestOfSignedAttrsComputed digest over signed attributes, if present, using digestAlgorithmString
DigestOfeContentComputed digest over eContent, if present, using digestAlgorithmString
signingTimesigningTime attribute in format "2005-12-31 23:30:59"String
messageDigestmessageDigest attribute in hexadecimal format, if presentString
pssParamsParameters used for RSA-PSS (if applicable).String
HASsigningCertificate1 if an ESS signingCertificate is present; 0 if not.Number
signingCertHashcertHash value of ESS signing certificate, if present, encoded in hexString
HASalgorithmProtection1 if a cmsAlgorithmProtection attribute is present; 0 if not.Number
HASsubjectKeyIdentifier1 if signerIdentifier is the CHOICE subjectKeyIdentifier; 0 if issuerAndSerialNumber [New in v23.0]Number
signerIdentifiersignerIdentifier value encoded in hex [New in v23.0]String

By default, the function queries the first signerInfo in the file. To query the Nth signerInfo append "/N" to the query string, e.g. "signerInfoVersion/2" to find the version number of the second signerInfo in the file.

[New in v23.0] The query "certificate/N" will output the Nth certificate in the CertificateSet (default N = 1) encoded in base64. Note that the length of an X.509 certificate is typically several hundred bytes.

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 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_QuerySigData("", 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

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

strCMSFile = "4.6.bin"
nRet = CMS_QuerySigData(strOutput, Len(strOutput), strCMSFile, "version", 0)
Debug.Print "Version=" & nRet

strCMSFile = "4.7.bin"
nRet = CMS_QuerySigData(strOutput, Len(strOutput), strCMSFile, "version", 0)
Debug.Print "Version=" & nRet
nRet = CMS_QuerySigData(strOutput, Len(strOutput), strCMSFile, "signingTime", 0)
If nRet > 0 Then
    Debug.Print "signingTime=" & Left$(strOutput, nRet)
Else
    Debug.Print "ERROR=" & nRet
End If

strCMSFile = "BasicSignByAlice_attr.bin"
nRet = CMS_QuerySigData(strOutput, Len(strOutput), strCMSFile, "signingTime", 0)
If nRet > 0 Then
    Debug.Print "signingTime=" & Left$(strOutput, nRet)
Else
    Debug.Print "ERROR=" & nRet
End If

In this example, file 4.6.bin is CMS Version 1, file 4.7.bin is CMS Version 3 with no signingTime attribute (if not present, it returns error code zero), and the file BasicSignByAlice_attr.bin was signed at 7:31 a.m. on 25th February 2006:

Version=1
Version=3
ERROR=0
signingTime=2006-02-25 07:31:01

Example (VBA wrapper function)

Dim strCMSFile As String
Dim strQuery As String
Dim strOutput As String

strCMSFile = "4.6.bin"
Debug.Print "FILE: " & strCMSFile
strQuery = "version"
strOutput = cmsQuerySigData(strCMSFile, strQuery)
Debug.Print strQuery & " ==> [" & strOutput & "]"
strQuery = "digestAlgorithm"
strOutput = cmsQuerySigData(strCMSFile, strQuery)
Debug.Print strQuery & " ==> [" & strOutput & "]"

strCMSFile = "4.7.bin"
Debug.Print "FILE: " & strCMSFile
strQuery = "version"
strOutput = cmsQuerySigData(strCMSFile, strQuery)
Debug.Print strQuery & " ==> [" & strOutput & "]"
strQuery = "signatureAlgorithm"
strOutput = cmsQuerySigData(strCMSFile, strQuery)
Debug.Print strQuery & " ==> [" & strOutput & "]"

strCMSFile = "BasicSignByAlice_attr.bin"
Debug.Print "FILE: " & strCMSFile
strQuery = "signingTime"
strOutput = cmsQuerySigData(strCMSFile, strQuery)
Debug.Print strQuery & " ==> [" & strOutput & "]"

See Also

CMS_ReadSigData CMS_GetSigDataDigest

[Contents] [Index]

[PREV: CMS_QueryEnvData...]   [Contents]   [Index]   
   [NEXT: CMS_ReadComprData...]

Copyright © 2004-24 D.I. Management Services Pty Ltd. All rights reserved. Generated 2024-09-23T07:52:09Z.