RSA_ReadAnyPrivateKey

CryptoSys PKI Pro Manual

RSA_ReadAnyPrivateKey

Reads from a file or string containing a private key into an "internal" private key string.

VBA/VB6 Syntax


Public Declare Function RSA_ReadAnyPrivateKey Lib "diCrPKI.dll" (ByVal strOutput As String, ByVal nOutChars As Long, ByVal strKeyFileOrString As String, ByVal strPassword As String, ByVal nOptions As Long) As Long

nRet = RSA_ReadAnyPrivateKey(strOutput, nOutChars, strKeyFileOrString, strPassword, nOptions) As Long

C/C++ Syntax


long __stdcall RSA_ReadAnyPrivateKey(char *szOutput, long nOutChars, const char *szKeyFileOrString, const char *szPassword, long nOptions);

Parameters

szOutput: [out] to receive encoded private key data in "internal" format.
nOutChars: [in] specifying the maximum number of characters to be received.
szKeyFileOrString: [in] specifying either the name of file containing the private key or a string containing the key in PEM format or XML format.
szPassword: [in] containing the password, if the key is encrypted, or "" if not encrypted.
nOptions: [in] not used in this release. Specify zero.

Returns (VBA/C)

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

VBA Wrapper Syntax

Public Function rsaReadAnyPrivateKey (szKeyFileOrString As String, Optional szPassword As String = "", Optional nOptions As Long = 0) As String
Public Function rsaReadPrivateKey (szKeyFileOrString As String, Optional szPassword As String = "", Optional nOptions As Long = 0) As String

.NET Equivalent

Rsa.ReadPrivateKey Method

C++ (STL) Equivalent

static std::string dipki::Rsa::ReadPrivateKey (const std::string &keyFileOrString, const std::string &password="")

Python Equivalent

static Rsa.read_private_key(keyfileorstr, password="")

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.

This function will attempt to read the private key from "any" supported format. The output will be an ephemeral "internal" key string suitable for the current session only.

Supported formats are:

Encrypted or unencrypted PKCS#8 private key (.p8e, .p8) file in either binary DER format or text PEM format
PKCS#12 (.p12, .pfx) file containing a PKCSShroudedKeyBag. [v20.5] Added support for AES256-SHA256 encryption.
OpenSSL-compatible PKCS#1 RSA private key file in either binary DER format or text PEM format
String containing contents of any of the above files in text form as a PEM string
XML file or string containing an XKMS-conforming RSAKeyPair element
JSON file or string containing a plaintext RSA private key represented in JSON Web Key (JWK) format.

This supersedes the following functions:

RSA_ReadEncPrivateKey
RSA_ReadPrivateKeyInfo
RSA_ReadPrivateKeyFromPFX

Example (VBA core function)

This VB6/VBA wrapper function returns the "internal" private key string given the filename and password

Public Function rsaReadPrivateKey(strKeyFileOrString As String, strPassword As String) As String
' Reads the private key from any supported private key file or PEM string
' Returns the key as an ephemeral base64 string or an empty string on error
    Dim nChars As Long
    ' How long is PrivateKey string?
    nChars = RSA_ReadAnyPrivateKey("", 0, strKeyFileOrString, strPassword, 0)
    If nChars <= 0 Then
        Exit Function
    End If
    ' Pre-dimension the string to receive data
    rsaReadPrivateKey = String(nChars, " ")
    ' Read in the Private Key
    nChars = RSA_ReadAnyPrivateKey(rsaReadPrivateKey, nChars, strKeyFileOrString, strPassword, 0)
End Function

Example (VBA wrapper function)

Dim strIntKey As String

strIntKey = rsaReadAnyPrivateKey("AlicePrivRSASign.p8e", "password")
Debug.Print strIntKey
Debug.Print "KeyHashCode=0x" & Hex(RSA_KeyHashCode(strIntKey))
' Unencrypted key
strIntKey = rsaReadAnyPrivateKey("AlicePrivRSASign.pri", "")
Debug.Print strIntKey
Debug.Print "KeyHashCode=0x" & Hex(RSA_KeyHashCode(strIntKey))
' Key in XML form
strIntKey = rsaReadAnyPrivateKey("alice-pri.xml", "")
Debug.Print strIntKey
Debug.Print "KeyHashCode=0x" & Hex(RSA_KeyHashCode(strIntKey))