ECC_QueryKey

CryptoSys PKI Pro Manual

ECC_QueryKey

Queries an EC key string for selected information.

VBA/VB6 Syntax


Public Declare Function ECC_QueryKey Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strIntKeyString As String, ByVal strQuery As String, ByVal nOptions As Long) As Long

nRet = ECC_QueryKey(strOutput, Len(strOutput), strIntKeyString, strQuery, nOptions)

C/C++ Syntax


long __stdcall ECC_QueryKey(char *szOutput, long nOutChars, const char *szIntKeyString, const char *szQuery, long nOptions);

Parameters

szOutput: [out] string of sufficient length to receive the output.
nOutChars: [in] specifying the maximum number of characters to be received.
szIntKeyString: [in] containing the key as an internal key string.
szQuery: [in] specifying the query (see Remarks below).
nOptions: [in] not used in this release. Specify zero.

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. invalid input), it returns a negative error code.

VBA Wrapper Syntax

Public Function eccQueryKey (szIntKeyString As String, szQuery As String, Optional nOptions As Long = 0) As String

.NET Equivalent

Ecc.QueryKey Method

C++ (STL) Equivalent

static std::string dipki::Ecc::QueryKey (std::string internalKey, std::string query)

Python Equivalent

static Ecc.query_key(intkeystr, query)

Remarks

Valid queries are (case-insensitive):

Query String	Returns	Data Type
`curveName`	Name of the curve	String
`keyBits`	Number of bits in the key	Number
`isPrivate`	1 if the key is a private key; 0 if not	Number
`isValid`	1 if the key is valid; 0 if not	Number
`privateKey`	Value of the private key in hex format	String
`publicKey`	Value of the public key in hex format	String

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.

Example (VBA core function)

Dim nRet As Long
Dim nChars As Long
Dim strIntKey As String
Dim strKeyFile As String
Dim strQuery As String
Dim strBuffer As String
Dim strPassword As String

strKeyFile = "myeckeyp256.p8"
strPassword = "password"

Debug.Print "FILE: " & strKeyFile
' Find required length of internal key string
nChars = ECC_ReadPrivateKey("", 0, strKeyFile, strPassword, 0)
Debug.Print "ECC_ReadPrivateKey returns " & nChars & " (expected +ve)"
' Dimension the string to receive output
strIntKey = String(nChars, " ")
' Read into an ephemeral internal key string
nChars = ECC_ReadPrivateKey(strIntKey, Len(strIntKey), strKeyFile, strPassword, 0)
' Find the curve name (output as a string)
strBuffer = String(32, " ")
strQuery = "curveName"
nChars = ECC_QueryKey(strBuffer, Len(strBuffer), strIntKey, strQuery, 0)
If nChars > 0 Then Debug.Print "ECC_QueryKey('" & strQuery & "')=[" & Left(strBuffer, nChars) & "]"
' Find the key size in bits (NB returned directly)
strQuery = "keyBits"
nRet = ECC_QueryKey("", 0, strIntKey, strQuery, 0)
Debug.Print "ECC_QueryKey('" & strQuery & "')=" & nRet & " (expected +ve)"
' Is it a private or public key?
strQuery = "isPrivate"
nRet = ECC_QueryKey("", 0, strIntKey, strQuery, 0)
Debug.Print "ECC_QueryKey('" & strQuery & "')=" & nRet & " (expected 1 = True)"
' Extract the private key in hex form
strQuery = "privateKey"
' Get required length of output string
nChars = ECC_QueryKey("", 0, strIntKey, strQuery, 0)
strBuffer = String(nChars, " ")
nChars = ECC_QueryKey(strBuffer, Len(strBuffer), strIntKey, strQuery, 0)
Debug.Print "ECC_QueryKey('" & strQuery & "')="
If nChars > 0 Then Debug.Print "[" & Left(strBuffer, nChars) & "]"
' Extract the public key in hex form
strQuery = "publicKey"
nChars = ECC_QueryKey("", 0, strIntKey, strQuery, 0)
strBuffer = String(nChars, " ")
nChars = ECC_QueryKey(strBuffer, Len(strBuffer), strIntKey, strQuery, 0)
Debug.Print "ECC_QueryKey('" & strQuery & "')="
If nChars > 0 Then Debug.Print "[" & Left(strBuffer, nChars) & "]"

FILE: myeckeyp256.p8
ECC_ReadPrivateKey returns 100 (expected +ve)
ECC_QueryKey('curveName')=[secp256r1]
ECC_QueryKey('keyBits')=256 (expected +ve)
ECC_QueryKey('isPrivate')=1 (expected 1 = True)
ECC_QueryKey('privateKey')=
[0955cc9904330205fa00559dbcae5c978c42a2f96fc1d661b66f617331ef0738]
ECC_QueryKey('publicKey')=
[0403af975e940d6db5184576a81fe50914579c7d777bfc70725b24505e03e49a9e004025069f3e8981d45027c953d57818a2b212ec7d1bfcfac0ea645dff81ed6b]

Example (VBA wrapper function)

Dim curveName As String
Dim alicePrivateKeyHex As String
Dim ourPrivateKey As String

curveName = "X25519"
alicePrivateKeyHex = "77076d0a7318a57d3c16c17251b26645df4c2f87ebc0992ab177fba51db92c2a"

ourPrivateKey = eccReadKeyByCurve(alicePrivateKeyHex, curveName, PKI_ECC_PRIVATE_KEY)
Debug.Assert Len(ourPrivateKey) > 0
Debug.Print "Key curve=" & eccQueryKey(ourPrivateKey, "curveName", 0) & " keyBits=" & eccQueryKey(ourPrivateKey, "keyBits", 0)

ECC_QueryKey

VBA/VB6 Syntax

C/C++ Syntax

Parameters

Returns (VBA/C)

VBA Wrapper Syntax

.NET Equivalent

C++ (STL) Equivalent

Python Equivalent

Remarks

Example (VBA core function)

Example (VBA wrapper function)

See Also