X509_QueryCert

Queries an X.509 certificate file for selected information.

VBA/VB6 Syntax

nRet = X509_QueryCert(strDataOut, nOutChars, strFileIn, strQuery, nOptions) As Long

C/C++ Syntax

Parameters

szOutput

[out] to receive the output.

nOutChars

[in] specifying the length of the output string.

szCertFile

[in] with name of X.509 certificate file (or base64 representation).

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.
PKI_X509_LATIN1 to try and convert Unicode/UTF-8/T.61 attribute strings to Latin-1 (ISO-8859-1)
PKI_X509_UTF8 to output attribute strings encoded in UTF-8 [New in v20.3]
PKI_X509_LDAP to output the distinguished name in LDAP string representation (for queries "issuerName" and "subjectName" only)
PKI_X509_DECIMAL to output the serial number in decimal format instead of hex (for query "serialNumber" only)

Returns (VBA/C)

If successful, the return value is a positive integer giving 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 is not present, the return value is zero. If there is an error (e.g. a missing or invalid certificate file), it returns a negative error code.

VBA Wrapper Syntax

.NET Equivalent

X509.QueryCert Method

C++ (STL) Equivalent

Python Equivalent

Remarks

Valid queries are (case-insenitive):

Some of these queries duplicate or complement existing functions:

• "notBefore" = X509_CertIssuedOn()
• "notAfter" = X509_CertExpiresOn()
• "serialNumber" = X509_CertSerialNumber()
• "subjectName" = X509_CertSubjectName()
• "issuerName" = X509_CertIssuerName()

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 = X509_QueryCert("", 0, "", "version", PKI_QUERY_GETTYPE);

will return PKI_QUERY_NUMBER.

If an attribute value is encoded in a multi-byte-character string format (such as UTF8String or BMPString), the value will be expressed as a hexadecimal-encoded string [NB changed in v3.9] preceded by the hash symbol ('#' U+0023), e.g.

"C=TW;O=E8 A1 8C E6 94 BF E9 99 A2" (v3.8 and earlier)
"C=TW;O=#E8A18CE694BFE999A2" (v3.9 and later)

Use the PKI_X509_LATIN1 option to return the string encoded in Latin-1, if possible, to help with display issues.

The output from the queries "issuerName" and "subjectName" using the PKI_X509_LDAP option are suitable as content for the <X509IssuerName> and <X509SubjectName> nodes, respectively, in the <X509Data> node of an XML-DSIG document.

Example (VBA core function)

This example queries information from a sample X.509 certificate file.

Dim nRet As Long
Dim strOutput As String
Dim strQuery As String
Dim strCertFile As String

strCertFile = "CarlRSASelf.cer"

' Make a large buffer to receive output
strOutput = String(512, " ")

strQuery = "version"
nRet = X509_QueryCert(strOutput, Len(strOutput), strCertFile, strQuery, 0)
Debug.Print strQuery & "=" & nRet

strQuery = "serialNumber"
nRet = X509_QueryCert(strOutput, Len(strOutput), strCertFile, strQuery, 0)
If nRet <= 0 Then Exit Sub  ' catch error
Debug.Print strQuery & "=" & Left(strOutput, nRet)

strQuery = "signatureAlgorithm"
nRet = X509_QueryCert(strOutput, Len(strOutput), strCertFile, strQuery, 0)
If nRet <= 0 Then Exit Sub  ' catch error
Debug.Print strQuery & "=" & Left(strOutput, nRet)

strQuery = "notAfter"
nRet = X509_QueryCert(strOutput, Len(strOutput), strCertFile, strQuery, 0)
If nRet <= 0 Then Exit Sub  ' catch error
Debug.Print strQuery & "=" & Left(strOutput, nRet)

For the S/MIME test file CarlRSASelf.cer, the output is as follows

version=3
serialNumber=46346bc7800056bc11d36e2e9ff25020
signatureAlgorithm=sha1WithRSAEncryption
notAfter=2039-12-31T23:59:59Z

To query the type of data returned for a given query.

Dim nRet As Long
Dim strQuery As String

' Find out the data type for a given query
strQuery = "version"
nRet = X509_QueryCert("", 0, "", strQuery, PKI_QUERY_GETTYPE)
Debug.Print "Type(" & strQuery & ")=" & nRet

strQuery = "serialNumber"
nRet = X509_QueryCert("", 0, "", strQuery, PKI_QUERY_GETTYPE)
Debug.Print "Type(" & strQuery & ")=" & nRet

strQuery = "NotAValidQuery"
nRet = X509_QueryCert("", 0, "", strQuery, PKI_QUERY_GETTYPE)
Debug.Print "Type(" & strQuery & ")=" & nRet

This should produce output

Type(version)=1
Type(serialNumber)=2
Type(NotAValidQuery)=-29

where 1 (PKI_QUERY_NUMBER) indicates a number, 2 (PKI_QUERY_STRING) indicates a string, and -29 (BAD_QUERY_ERROR) indicates an invalid query.

Example (VBA wrapper function)

Debug.Print x509TextDumpToString("AliceRSASignByCarl.cer")
Debug.Print x509QueryCert("AliceRSASignByCarl.cer", "subjectName")
Debug.Print asn1TextDumpToString("AliceRSASignByCarl.cer")

See Also

X509_KeyUsageFlags X509_CertSubjectName

[Contents] [Index]