RSA_ToXMLString

Creates an XML string representation of an RSA internal key string.

VBA/VB6 Syntax

nRet = RSA_ToXMLString(strOutput, nOutChars, strKeyString, nOptions) As Long

C/C++ Syntax

Parameters

szOutput

[out] to receive XML data.

nOutChars

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

szKeyString

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

nOptions

[in] option flags: Select and combine:
PKI_DEFAULT (0) to output in appropriate W3C standard format (RSAKeyValue for public key and RSAKeyPair for private key)
PKI_XML_RSAKEYVALUE to force private key output as .NET-compatible RSAKeyValue format (instead of W3C RSAKeyPair)
PKI_XML_EXCLPRIVATE to exclude the private key (use to get a public key RSAKeyValue from a private key)
PKI_XML_HEXBINARY to output with data in non-conforming hexBinary format

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.ToXMLString Method (String, Rsa.XmlOptions)

C++ (STL) 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.

Both public and private key data can be output. The key must have been read first into an internal key string using one of the other RSA key input functions in this toolkit.

If the internal key is a public key, or if the PKI_XML_EXCLPRIVATE option is used with a private key, the output will always be a RSAKeyValue element containing just <Modulus> and <Exponent> elements as per [XMLDSIG].

If the internal key is a private key and the PKI_XML_EXCLPRIVATE option is not used, the default output will be a a XKMS-conforming RSAKeyPair element with the private key parameters included. Including the PKI_XML_RSAKEYVALUE option will force a .NET-compatible RSAKeyValue element instead. The only difference between RSAKeyPair and RSAKeyValue is in the name of the outer XML element. The default behaviour is to comply with the W3C standards [XKMS] and [XMLDSIG]. Users who wish to export a private key to use in the .NET world will probably want to use the PKI_XML_RSAKEYVALUE option.

The PKI_XML_HEXBINARY option will output the binary data in hexBinary encoding format instead of base64. This latter format is not in conformance with any W3C standard, but is provided to allow users to see the data in more readable hex format. Such a format can be read by this toolkit's RSA_FromXMLString() function, but don't try using it anywhere else.

Example (VBA core function)

This example reads in a private key from a encrypted private key file and then converts to an XML string in the .NET-compatible format.

    Dim strEPKFile As String
    Dim strPassword As String
    Dim strPrivateKey As String
    Dim strXML As String
    Dim nLen As Long

    strEPKFile = "AlicePrivRSASign.p8e"
    strPassword = "password"
    
    ' Read in the deciphered private key string in our internal format
    strPrivateKey = rsaReadPrivateKey(strEPKFile, strPassword)
    If Len(strPrivateKey) = 0 Then
        MsgBox "Unable to retrieve private key"
        Exit Function
    End If
    Debug.Print "INTKEY=" & strPrivateKey
    
    ' Convert to XML
    nLen = RSA_ToXMLString("", 0, strPrivateKey, PKI_XML_RSAKEYVALUE)
    ' pre-dimension first
    strXML = String(nLen, " ")
    nLen = RSA_ToXMLString(strXML, Len(strXML), strPrivateKey, PKI_XML_RSAKEYVALUE)
    strXML = Left(strXML, nLen)    
    Debug.Print "XML=" & strXML

The output should look like this (only longer):

INTKEY=MIICXAIBAAKBgQDgiXM5jdj19eiHdjl/ ...
XML=<RSAKeyValue><Modulus>4IlzOY3Y9fXoh ... +yRRKt/IQ==</D></RSAKeyValue>

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_FromXMLString

[Contents] [Index]