How to: Sign XML Documents with Digital Signatures

Article
09/15/2021

You can use the classes in the System.Security.Cryptography.Xml namespace to sign an XML document or part of an XML document with a digital signature. XML digital signatures (XMLDSIG) allow you to verify that data was not altered after it was signed. For more information about the XMLDSIG standard, see the World Wide Web Consortium (W3C) recommendation XML Signature Syntax and Processing.

Note

The code in this article applies to Windows.

The code example in this procedure demonstrates how to digitally sign an entire XML document and attach the signature to the document in a <Signature> element. The example creates an RSA signing key, adds the key to a secure key container, and then uses the key to digitally sign an XML document. The key can then be retrieved to verify the XML digital signature, or can be used to sign another XML document.

For information about how to verify an XML digital signature that was created using this procedure, see How to: Verify the Digital Signatures of XML Documents.

To digitally sign an XML document

Create a CspParameters object and specify the name of the key container.

CspParameters cspParams = new()
{
    KeyContainerName = "XML_DSIG_RSA_KEY"
};

Dim cspParams As New CspParameters With {
    .KeyContainerName = "XML_DSIG_RSA_KEY"
}

Generate an asymmetric key using the RSACryptoServiceProvider class. The key is automatically saved to the key container when you pass the CspParameters object to the constructor of the RSACryptoServiceProvider class. This key will be used to sign the XML document.
```
RSACryptoServiceProvider rsaKey = new(cspParams);
```
```
Dim rsaKey As New RSACryptoServiceProvider(cspParams)
```

Create an XmlDocument object by loading an XML file from disk. The XmlDocument object contains the XML element to encrypt.

XmlDocument xmlDoc = new()
{
    // Load an XML file into the XmlDocument object.
    PreserveWhitespace = true
};
xmlDoc.Load("test.xml");

' Load an XML file into the XmlDocument object.
Dim xmlDoc As New XmlDocument With {
    .PreserveWhitespace = True
}
xmlDoc.Load("test.xml")

Create a new SignedXml object and pass the XmlDocument object to it.

SignedXml signedXml = new(xmlDoc)
{

Dim signedXml As New SignedXml(xmlDoc)

Add the signing RSA key to the SignedXml object.

    SigningKey = rsaKey
};

signedXml.SigningKey = rsaKey

Create a Reference object that describes what to sign. To sign the entire document, set the Uri property to "".

// Create a reference to be signed.
Reference reference = new()
{
    Uri = ""
};

' Create a reference to be signed.
Dim reference As New Reference()
reference.Uri = ""

Add an XmlDsigEnvelopedSignatureTransform object to the Reference object. A transformation allows the verifier to represent the XML data in the identical manner that the signer used. XML data can be represented in different ways, so this step is vital to verification.
```
XmlDsigEnvelopedSignatureTransform env = new();
reference.AddTransform(env);
```
```
Dim env As New XmlDsigEnvelopedSignatureTransform()
reference.AddTransform(env)
```

Add the Reference object to the SignedXml object.

signedXml.AddReference(reference);

signedXml.AddReference(reference)

Compute the signature by calling the ComputeSignature method.

signedXml.ComputeSignature();

signedXml.ComputeSignature()

Retrieve the XML representation of the signature (a <Signature> element) and save it to a new XmlElement object.

XmlElement xmlDigitalSignature = signedXml.GetXml();

Dim xmlDigitalSignature As XmlElement = signedXml.GetXml()

Append the element to the XmlDocument object.

xmlDoc.DocumentElement?.AppendChild(xmlDoc.ImportNode(xmlDigitalSignature, true));

xmlDoc.DocumentElement.AppendChild(xmlDoc.ImportNode(xmlDigitalSignature, True))

Save the document.

xmlDoc.Save("test.xml");

xmlDoc.Save("test.xml")

Example

This example assumes that a file named test.xml exists in the same directory as the compiled program. You can place the following XML into a file called test.xml and use it with this example.

<root>  
    <creditcard>  
        <number>19834209</number>  
        <expiry>02/02/2002</expiry>  
    </creditcard>  
</root>

using System;
using System.Runtime.Versioning;
using System.Security.Cryptography;
using System.Security.Cryptography.Xml;
using System.Xml;

[SupportedOSPlatform("Windows")]
public class SignXML
{
    public static void Main(String[] args)
    {
        try
        {
            // Create a new CspParameters object to specify
            // a key container.
            CspParameters cspParams = new()
            {
                KeyContainerName = "XML_DSIG_RSA_KEY"
            };

            // Create a new RSA signing key and save it in the container.
            RSACryptoServiceProvider rsaKey = new(cspParams);

            // Create a new XML document.
            XmlDocument xmlDoc = new()
            {
                // Load an XML file into the XmlDocument object.
                PreserveWhitespace = true
            };
            xmlDoc.Load("test.xml");

            // Sign the XML document.
            SignXml(xmlDoc, rsaKey);

            Console.WriteLine("XML file signed.");

            // Save the document.
            xmlDoc.Save("test.xml");
        }
        catch (Exception e)
        {
            Console.WriteLine(e.Message);
        }
    }

    // Sign an XML file.
    // This document cannot be verified unless the verifying
    // code has the key with which it was signed.
    public static void SignXml(XmlDocument xmlDoc, RSA rsaKey)
    {
        // Check arguments.
        if (xmlDoc == null)
            throw new ArgumentException(null, nameof(xmlDoc));
        if (rsaKey == null)
            throw new ArgumentException(null, nameof(rsaKey));

        // Create a SignedXml object.
        SignedXml signedXml = new(xmlDoc)
        {

            // Add the key to the SignedXml document.
            SigningKey = rsaKey
        };

        // Create a reference to be signed.
        Reference reference = new()
        {
            Uri = ""
        };

        // Add an enveloped transformation to the reference.
        XmlDsigEnvelopedSignatureTransform env = new();
        reference.AddTransform(env);

        // Add the reference to the SignedXml object.
        signedXml.AddReference(reference);

        // Compute the signature.
        signedXml.ComputeSignature();

        // Get the XML representation of the signature and save
        // it to an XmlElement object.
        XmlElement xmlDigitalSignature = signedXml.GetXml();

        // Append the element to the XML document.
        xmlDoc.DocumentElement?.AppendChild(xmlDoc.ImportNode(xmlDigitalSignature, true));
    }
}

Imports System.Security.Cryptography
Imports System.Security.Cryptography.Xml
Imports System.Xml

Module SignXML
    Sub Main(ByVal args() As String)
        Try
            ' Create a new CspParameters object to specify
            ' a key container.
            Dim cspParams As New CspParameters With {
                .KeyContainerName = "XML_DSIG_RSA_KEY"
            }
            ' Create a new RSA signing key and save it in the container. 
            Dim rsaKey As New RSACryptoServiceProvider(cspParams)
            ' Create a new XML document.
            ' Load an XML file into the XmlDocument object.
            Dim xmlDoc As New XmlDocument With {
                .PreserveWhitespace = True
            }
            xmlDoc.Load("test.xml")
            ' Sign the XML document. 
            SignXml(xmlDoc, rsaKey)

            Console.WriteLine("XML file signed.")

            ' Save the document.
            xmlDoc.Save("test.xml")
        Catch e As Exception
            Console.WriteLine(e.Message)
        End Try
    End Sub

    ' Sign an XML file. 
    ' This document cannot be verified unless the verifying 
    ' code has the key with which it was signed.
    Sub SignXml(ByVal xmlDoc As XmlDocument, ByVal rsaKey As RSA)
        ' Check arguments.
        If xmlDoc Is Nothing Then
            Throw New ArgumentException(
                "The XML doc cannot be nothing.", NameOf(xmlDoc))
        End If
        If rsaKey Is Nothing Then
            Throw New ArgumentException(
                "The RSA key cannot be nothing.", NameOf(rsaKey))
        End If
        ' Create a SignedXml object.
        Dim signedXml As New SignedXml(xmlDoc)
        ' Add the key to the SignedXml document.
        signedXml.SigningKey = rsaKey
        ' Create a reference to be signed.
        Dim reference As New Reference()
        reference.Uri = ""
        ' Add an enveloped transformation to the reference.
        Dim env As New XmlDsigEnvelopedSignatureTransform()
        reference.AddTransform(env)
        ' Add the reference to the SignedXml object.
        signedXml.AddReference(reference)
        ' Compute the signature.
        signedXml.ComputeSignature()
        ' Get the XML representation of the signature and save
        ' it to an XmlElement object.
        Dim xmlDigitalSignature As XmlElement = signedXml.GetXml()
        ' Append the element to the XML document.
        xmlDoc.DocumentElement.AppendChild(xmlDoc.ImportNode(xmlDigitalSignature, True))
    End Sub
End Module

Compiling the Code

In a project that targets .NET Framework, include a reference to System.Security.dll.
In a project that targets .NET Core or .NET 5, install NuGet package System.Security.Cryptography.Xml.
Include the following namespaces: System.Xml, System.Security.Cryptography, and System.Security.Cryptography.Xml.

.NET Security

Never store or transfer the private key of an asymmetric key pair in plaintext. For more information about symmetric and asymmetric cryptographic keys, see Generating Keys for Encryption and Decryption.

Never embed a private key directly into your source code. Embedded keys can be easily read from an assembly using the Ildasm.exe (IL Disassembler) or by opening the assembly in a text editor such as Notepad.

How to: Sign XML Documents with Digital Signatures

To digitally sign an XML document

Example

Compiling the Code

.NET Security

See also

Feedback

Additional resources