ASN1_TextDumpToString

CryptoSys PKI Pro Manual

ASN1_TextDumpToString

Dumps details of ASN.1 formatted data to a string.

VBA/VB6 Syntax


Public Declare Function ASN1_TextDumpToString Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strFileOrPEMString As String, ByVal strDirName As String, ByVal nOptions As Long) As Long

nRet = ASN1_TextDumpToString(strOutput, nOutChars, strFileOrPEMString, nOptions)

C/C++ Syntax


long __stdcall ASN1_TextDumpToString(char *szOutput, long nOutChars, const char *szFileOrPEMString, const char *szDirName, long nOptions);

Parameters

szOutput: [out] String buffer to receive output.
nOutChars: [in] Maximum number of characters to be received.
szFileOrPEMString: [in] Filename of ASN.1 formatted data file to be analyzed (or its base64 representation or PEM string).
szDirName: [in] Directory in which to create a temporary file. Specify "" for default = system TEMP directory.
nOptions: [in] option flags:
PKI_ASN1_NOCOMMENTS to hide the comments
PKI_ASN1_ADDLEVELS to show level numbers

Returns (VBA/C)

If successful, the return value is the number of characters in or required for the output string; otherwise it returns a nonzero error code.

VBA Wrapper Syntax

Public Function asn1TextDumpToString (szFileOrPEMString As String, Optional nOptions As Long = 0, Optional szDirName As String = "") As String

.NET Equivalent

Asn1.TextDumpToString Method

C++ (STL) Equivalent

static std::string dipki::Asn1::TextDumpToString (const std::string &asn1File, Opts opts=Opts::None)

Python Equivalent

static Asn1.text_dump_tostring(asn1file, opts=0)

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.

The input may be a binary file in BER/DER format or a text file in PEM or base64-encoded format, or may be passed as a base64 string or as a PEM string. Only data with an outer SEQUENCE is accepted, which is the rule for all common PKI-related ASN.1 files.

The output is a text file showing the structure of the ASN.1 formatted data. All the bytes in the input are printed in hexadecimal form laid out to show the nested structure of the ASN.1 formatted data together with comments beginning with "--" that give further details about the elements. The length of each object is shown in bytes, for example

30 81 e0  --SEQUENCE/224 bytes

shows the tag (30) and length bytes (81 e0) which begin a SEQUENCE of length 224 bytes, equal to hexadecimal E0 bytes. Use the PKI_ASN1_NOCOMMENTS option to hide the comments: the resulting hexadecimal output without comments should decode back directly to the original binary file.

This function creates a temporary file, by default in the system TEMP directory. This file is locked and is automatically deleted after use. The user can specify a particular directory known to be secure if required. If the specified directory does not exist, the system TEMP directory will be used.

Example (VBA core function)

Dim strInputFile As String
Dim strBuffer As String
Dim nChars As Long

' Pass input as a string
strInputFile = "MAQwAgUA"
Debug.Print "Input: " & strInputFile
' Query for required length
nChars = ASN1_TextDumpToString("", 0, strInputFile, "", 0)
Debug.Print "ASN1_TextDumpToString returns " & nChars
' Dimension output buffer
strBuffer = String(nChars, " ")
nChars = ASN1_TextDumpToString(strBuffer, Len(strBuffer), strInputFile, "", 0)
Debug.Print strBuffer
' Again with no comments
strBuffer = String(nChars, " ")
nChars = ASN1_TextDumpToString(strBuffer, Len(strBuffer), strInputFile, "", PKI_ASN1_NOCOMMENTS)
Debug.Print "ASN1_TextDumpToString returns " & nChars
Debug.Print Left(strBuffer, nChars)

Input: MAQwAgUA
ASN1_TextDumpToString returns 95
30 04  --SEQUENCE/4 bytes
   30 02  --SEQUENCE/2 bytes
      05 00  --NULL/0 bytes
--(6 bytes)

ASN1_TextDumpToString returns 30
30 04 
   30 02 
      05 00

Example (VBA wrapper function)

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

Dim strInput As String
Dim strOutput As String
strInput = "MAQwAgUA"
Debug.Print "Input: " & strInput
strOutput = asn1TextDumpToString(strInput)
Debug.Print strOutput
Debug.Print asn1TextDumpToString(strInput, PKI_ASN1_NOCOMMENTS)