RSA_FromXMLString

Creates an RSA key string in internal format from an XML string.

VBA/VB6 Syntax

nRet = RSA_FromXMLString(strOutput, nOutChars, strXmlString, nOptions) As Long

C/C++ Syntax

Parameters

szOutput

[out] to receive key data either public or private.

nOutChars

[in] specifying the maximum number of characters to be received.

szXmlString

[in] containing the RSA public or private key in XML format

nOptions

[in] option flags:
PKI_DEFAULT (0) to include the private key, if present (default)
PKI_XML_EXCLPRIVATE to exclude the private key even if present
PKI_XML_REQPRIVATE to require the private key to exist in the XML input or fail

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

.NET Equivalent

Rsa.FromXMLString Method (String)
Rsa.FromXMLString Method (String, Rsa.XmlOptions)
Rsa.FromXMLString Method (String, Boolean)

C++ (STL) Equivalent

Python Equivalent

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.

A key string created with this function can be used in the other RSA functions in this toolkit that require a key in "internal" format. Use this function to import an RSA key from another application. Only US-ASCII characters are supported. The XML data should be well formed and must contain either an RSAKeyValue or RSAKeyPair element according to [XMLDSIG] or [XKMS2]. The parser has been designed to be pretty forgiving but don't push it too far. The first such valid element found in the string will be converted and other data will be ignored. If the XML data only contains the public key elements, the resulting internal string will contain a public key and can be used in the functions in this toolkit that require a public key string. If the XML data contains all the private key elements, the internal string will contain a private key unless the PKI_XML_EXCLPRIVATE option is used. To convert a private key, all components of the key pair must be present; namely, the <Modulus>, <Exponent>, <D>, <P>, <Q>, <DP>, <DQ>, and <InverseQ> elements as specified in [XKMS2]. To allow compatibility with older versions of XKMS out there, the deprecated elements <QINV>, <PublicExponent> and <PrivateExponent> will be accepted.

[New in v20.0] Element names with a prefix, e.g. <ds:Modulus>, are now accepted.

To make life easier to import RSA key data that exists in hexadecimal format, the user can force the function to decode the data in hexadecimal format instead of base64 by adding an attribute with the value "hexBinary" to each of the component elements of the RSAKeyValue. For example

<Exponent EncodingType="hexBinary">010001</Exponent>

The attribute name is not important. This practice is not in conformance with any existing W3C standard (that we're aware of, anyway) but is included for convenience where the user is creating the XML file by hand using hex data.

Example (VBA core function)

This example converts an XML string into an internal public key that can be used in the other public key functions in this toolkit.

    Dim strInternalKey As String
    Dim strXML As String
    Dim nLen As Long
    Dim nRet As Long
    
    strXML = "<RSAKeyValue>" _
& "<Modulus>CmZ5HcaYgWjeerd0Gbt/sMABxicQJwB1FClC4ZqNjFH" _
& "QU7PjeCod5dxa9OvplGgXARSh3+Z83Jqa9V1lViC7qw==</Modulus>" _
& "<Exponent>AQAB</Exponent>" _
& "</RSAKeyValue>"

    nLen = RSA_FromXMLString("", 0, strXML, 0)
    If nLen <= 0 Then
        MsgBox ("Error: " & nLen)
        Exit Function
    End If
    strInternalKey = String(nLen, " ")
    nLen = RSA_FromXMLString(strInternalKey, Len(strInternalKey), strXML, 0)
    strInternalKey = Left(strInternalKey, nLen)
    
    Debug.Print "INTKEY=" & strInternalKey
    
    nRet = RSA_CheckKey(strInternalKey, 0)
    Debug.Print "RSA_CheckKey returns " & nRet

The second example is the same as the first except the XML data is in hexadecimal format.

    Dim strInternalKey As String
    Dim strXML As String
    Dim nLen As Long
    Dim nRet As Long
    
    strXML = "<RSAKeyValue>" _
    & "<Modulus EncodingType='hexBinary'>0A66791D" _
    & "C6988168DE7AB77419BB7FB0C001C627102700751429" _
    & "42E19A8D8C51D053B3E3782A1DE5DC5AF4EBE9946817" _
    & "0114A1DFE67CDC9A9AF55D655620BBAB</Modulus>" _
    & "<Exponent EncodingType='hexBinary'>010001</Exponent>" _
    & "</RSAKeyValue>"

    nLen = RSA_FromXMLString("", 0, strXML, 0)
    If nLen <= 0 Then
        MsgBox ("Error: " & nLen)
        Exit Function
    End If
    strInternalKey = String(nLen, " ")
    nLen = RSA_FromXMLString(strInternalKey, Len(strInternalKey), strXML, 0)
    strInternalKey = Left(strInternalKey, nLen)
    
    Debug.Print "INTKEY=" & strInternalKey
    
    nRet = RSA_CheckKey(strInternalKey, 0)
    Debug.Print "RSA_CheckKey returns " & nRet

Both examples should produce the output (shortened here):

INTKEY=MEcCQApmeR3...yamvVdZVYgu6sCAwEAAQ==
RSA_CheckKey returns 1

Example (VBA wrapper function)

Dim strPrivateKey As String
strPrivateKey = rsaReadPrivateKey("AlicePrivRSASign.p8e", "password")
Debug.Print rsaToXMLString(strPrivateKey, 0)
Debug.Print rsaToXMLString(strPrivateKey, PKI_XML_EXCLPRIVATE Or PKI_XML_HEXBINARY)
Debug.Print rsaToXMLStringEx(strPrivateKey, "ds", PKI_XML_EXCLPRIVATE)
' Now derive internal private key string from XML
Dim strXML As String
Dim strKey As String
strXML = rsaToXMLString(strPrivateKey)
strKey = rsaFromXMLString(strXML)
Debug.Print "Key length = " & RSA_KeyBits(strKey) & " bits"

See Also

RSA_ToXMLString

[Contents] [Index]