.NET Security Blog : XML

XML Digital Signature Verification with Unknown URI Schemes

shawnfa — Thu, 12 Oct 2006 19:07:00 GMT

A few years back, there was a discussion thread on one of my XML digital signature posts about verifying an XML digital signature which had references to a URI prefixed with cid:. Recently Mattias Lindberg ran into this problem as well, and devised a clever solution to it.

Mattias realized that SignedXml uses WebRequest.Create to help resolve what the reference points to. And since WebRequest is extensible, he registered a custom class to handle cid URLs. Although his specific example is for cid, this technique will work for any other protocol that the .NET Framework does not know how to handle out of the box.

Adding SignatureProperties to SignedXml

shawnfa — Thu, 03 Nov 2005 23:48:00 GMT

One of the optional portions of the W3C XML digital signature specification allows for a set of SignatureProperties to be assigned to a signature. SignatureProperties allow the signer to place some metadata into the signature itself, such as the time the signature was created and the name of the person creating the signature. Since the XML digital signature specification does not lay out specific properties, you are free to create as many domain specific properties as you'd like. Although the SignedXml class does not support this feature, it's easy enough to add on your own by deriving from the default SignedXml implementation.

Signature properties exist as a SignatureProperties element in the signature itself, embedded as a DataObject. The signature's references contain a pointer to this element with a Type of "http://www.w3.org/2000/02/xmldsig#SignatureProperty", as specified in the W3C spec. The SignatureProperties element will contain as many SignatureProperty elements as needed. Each SignatureProperty will have a Target pointing to the signature that we're creating and will contain arbitrary XML (which should be in a different namespace to be valid).

In order to implement this, we'll first create a SignaturePropertiesSignedXml class which derives from SignedXml and takes the typical XmlDocument constructor parameter, as well as an ID for the signature (which is needed for the SignatureProperty Target attribute), and the ID of the SignatureProperties element itself (which is needed for the reference to work). We then use this information to create the SignatureProperties element, and place it into a DataObject. Finally we create and add the reference to the SignatureProperties element:

/// <summary>
/// XML signature class which enables SignatureProperties
/// </summary>
public sealed class SignaturePropertiesSignedXml : SignedXml
{
    private XmlDocument doc = null;
    private XmlElement signaturePropertiesRoot = null;
    
    /// <summary>
    /// Create a SignedXml class which can have SignatureProperties
    /// </summary>
    /// <param name="doc">XML document the signature belongs in</param>
    /// <param name="signatureId">ID of the signature to create</param>
    /// <param name="propertiesId">ID of the SignatureProperties to create</param>
    public SignaturePropertiesSignedXml(XmlDocument doc, string signatureId, string propertiesId) : base(doc)
    {
        if(String.IsNullOrEmpty(signatureId))
            throw new ArgumentException("signatureId cannot be empty", "signatureId");
        if(String.IsNullOrEmpty(propertiesId))
            throw new ArgumentException("propertiesId cannot be empty", "propertiesId");
        
        this.doc = doc;
        Signature.Id = signatureId;
        
        // create a root element to hold the properties
        signaturePropertiesRoot = doc.CreateElement("SignatureProperties", XmlDsigNamespaceUrl);
        signaturePropertiesRoot.SetAttribute("Id", propertiesId);
        
        // create a data object for the properties to go into
        DataObject signatureProperties = new DataObject();
        signatureProperties.Data = signaturePropertiesRoot.SelectNodes(".");
        AddObject(signatureProperties);

        // and add a reference to the data object
        Reference propertiesRef = new Reference("#" + propertiesId);
        propertiesRef.Type = "http://www.w3.org/2000/02/xmldsig#SignatureProperty";
        AddReference(propertiesRef);
        
        return;
    }

Now that the constructor has done the work of setting up the signature properties, we'll need a simple method to add individual properties. This is easily accomplished by taking the XML content of the property, creating a SignatureProperty element with a Target of the containing signature, and adding the input XML to the SignatureProperty:

    /// <summary>
    /// Add a signature property to the document
    /// </summary>
    /// <param name="content">XML contents of the property</param>
    public void AddProperty(XmlElement content)
    {
        if(content == null)
            throw new ArgumentNullException("content");
        if(String.Compare(content.NamespaceURI, XmlDsigNamespaceUrl) == 0)
            throw new InvalidOperationException("Signature properties must not be in the XML Digital Signature namespace");

        // wrap the content in a SignatureProperty element
        XmlElement property = doc.CreateElement("SignatureProperty", XmlDsigNamespaceUrl);
        property.SetAttribute("Target", "#" + Signature.Id);
        property.AppendChild(content);

        signaturePropertiesRoot.AppendChild(property);
        return;
    }

Finally, we need to override GetIdElement (see my previous post on doing this for more information), since the default GetIdElement implementation does not search DataObjects and we have a reference that points to our SignatureProperties which is contained within a DataObject. In the override, we just check to see if we're searching for the signature properties, and if not fall back to default behavior.

    /// <summary>
    /// Get an element refered to by its ID
    /// </summary>
    /// <param name="doc">XML document to search for the element in</param>
    /// <param name="id">element to search for</param>
    /// <returns>Element with the given ID, null if it could not be found</returns>
    public override XmlElement GetIdElement(XmlDocument doc, string id)
    {
        if(id == null)
            return null;
        
        // see if this is the signature properties being referenced, otherwise fall back to default behavior
        if(String.Compare(id, signaturePropertiesRoot.GetAttribute("Id"), StringComparison.OrdinalIgnoreCase) == 0)
            return signaturePropertiesRoot;
        else
            return base.GetIdElement(doc, id);
    }

And that's it! We can now pretty easily use this class to add metadata to the signature. For example:

        XmlDocument doc = new XmlDocument();
        doc.Load("order.xml");
        SignaturePropertiesSignedXml signer = new SignaturePropertiesSignedXml(doc, "orderSignature", "signatureProperties");

        RSA key = new RSACryptoServiceProvider();
        signer.SigningKey = key;

        // create a timestamp property
        XmlElement timestamp = doc.CreateElement("TimeStamp", "http://www.example.org/#signatureProperties");
        timestamp.InnerText = DateTime.Now.ToUniversalTime().ToString();
        signer.AddProperty(timestamp);

        // create a signed by property
        XmlElement signedBy = doc.CreateElement("SignedBy", "http://www.example.org/#signatureProperties");
        signedBy.InnerText = new WindowsPrincipal(WindowsIdentity.GetCurrent()).Identity.Name;
        signer.AddProperty(signedBy);

        Reference orderRef = new Reference("");
        orderRef.AddTransform(new XmlDsigEnvelopedSignatureTransform());
        signer.AddReference(orderRef);

        signer.ComputeSignature();
        doc.DocumentElement.AppendChild(signer.GetXml());
        doc.Save("order-signed.xml");

Will produce a signature that contains the time and person who signed the document:

  <Signature Id="orderSignature" xmlns="http://www.w3.org/2000/09/xmldsig#">
    <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
      <Reference URI="#signatureProperties" Type="http://www.w3.org/2000/02/xmldsig#SignatureProperty">
        <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <DigestValue>KfpRjNAGP47ZKX/RZ9hFEpKo9u8=</DigestValue>
      </Reference>
      <Reference URI="">
        <Transforms>
          <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
        </Transforms>
        <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <DigestValue>BPoz+CmKZyTATOhskqke3iOXmvA=</DigestValue>
      </Reference>
    </SignedInfo>
    <SignatureValue>CmMm ... JKU=</SignatureValue>
    <Object>
      <SignatureProperties Id="signatureProperties">
        <SignatureProperty Target="#orderSignature">
          <TimeStamp xmlns="http://www.example.org/#signatureProperties">11/3/2005 9:35:37 PM</TimeStamp>
        </SignatureProperty>
        <SignatureProperty Target="#orderSignature">
          <SignedBy xmlns="http://www.example.org/#signatureProperties">REDMOND\ShawnFa</SignedBy>
        </SignatureProperty>
      </SignatureProperties>
    </Object>
  </Signature>

To verify this signature you don't even have to use the custom SignaturePropertiesSignedXml class -- since the SignatureProperties element is now a child of the XML document (since we made this an enveloped signature), the standard SignedXml class will be able to find it to verify the signature.

Hitting the Mailbag

shawnfa — Tue, 14 Dec 2004 21:27:00 GMT

I've gotten quite a few questions from this blog over the past several months. And although I can't answer all of them, here's some quick answers to some of the more common ones. If you do have more questions, its usually best to post them in the comments here or in the microsoft.public.dotnet.security newsgroup. That way if I don't get to them, somebody else may see it and have an answer for you. (It also prevents my spam filter from snagging them).

Anyway, on to the questions:

Hi,

I just wanted to know what is the purpose of FirstMatchCodeGroup?

For instance one could have guessed that all_code from machine security level would be FirstMatchCodeGroup, but it is not the case.

The FirstMatchCodeGroup is different from the standard UnionCodeGroup (which is what the default policy uses) in how it deals with child code groups. UnionCodeGroup will merge the permission set associated with itself with the permission sets returned by all of its children code groups. FirstMatchCodeGroup on the other hand merges its permission set with only the first child code group that matches the evidence being evaluated.

Since FirstMatchCodeGroup stops evaluating its children code groups after it finds one that matches the evidence, it's not what we would want to use for the default policy, where we want all the code groups to have a chance at determining the final permission grant.

My question is how can I sign an assembly I compile myself using the Microsoft.CSharp.Compiler? In an IDE situation, this would obviously be done with the AssemblyInfo.cs file.

I realize I could use CompileAssemblyFromFileBatch and create essentially an AssemblyInfo.cs on the fly. This seems a bit cheesy, and I'd prefer a cleaner way if there is one.

Well, the easiest answer to this is to emit a System.Reflection.AssemblyKeyFileAttribute or System.Reflection.AssemblyKeyNameAttribute into the class you're compiling. On Whidbey, this will give you warning CS1699, which can be avoided by using the /keyfile or /keycontainer options in the CompilerParameters object you pass to the C# CodeDOM compiler.

Now, that being said, if you're signing assemblies on the fly you'll need access to a private key on the machine. And if you're making security decisions based entirely upon that key, you're opening a security hole since any other application could also potentially find that key and sign themselves with it. Once they've done that, they'll match your code groups and get any permissions you grant to that key.

I am trying hard to understand how to sign an xml file using a private key file. I have the private key on windows certificate store but I don't want to use the private key from the store. I can export it as pfx. But I don't know what to do next. Can you assist me on this?

If you need to do this on v1.1 of the framework, you'll need to P/Invoke to the Windows Cryptography API in order to load your certificate back into a cert store, and create an RSACryptoServiceProvider object around it by passing in CspParameters to the constructor which point to the correct key container. Since you said you already have the key in the store it might be easier to just do this without exporting to PFX first.

With Whidbey, we've enhanced the X.509 certificate support available in the framework, and you can now open an X.509 certificate stored in a file into an X509Certificate2 object directly by passing in the path to the PFX file and a SecureString as a password. Then you'll be able to use the PrivateKey property of the certificate to get the signing key. For a sample of what this might look like, check out the section on X.509 Support in the article Mike Downen and I wrote for November's MSDN magazine.

I've just found a very interesting blog post of yours: "Generating a Key from a Password" which is all about PasswordDeriveBytes and CryptDeriveKey.

I'm trying to use this class, but there isn't any support for RipeMD-160 hash algorithm which I have to use in case to decrypt an 2-Key TripleDES encrypted message (the key has been derived from password with RipeMD-160).

My question:
How can I set directly the key for TripleDESCryptoServiceProvider without using the PasswordDeriveBytes class?

The blog post mentioned in the question shows how to use two built in helper classes to generate a key from a password. PasswordDeriveBytes uses the CryptDeriveKey algorithm exposed by CAPI or PBKDF1. Whidbey introduces Rfc2898DeriveBytes, which uses PBKDF2 to generate a key from a password.

However, there are other ways to go about generating a key, and if you need to use RIPEMD-160, then you'll find that Whidbey also introduces support for the RIPEMD160 hash algorithm. Depending on how you're key is to be generated, you'll probably have to do some variation of PBKDF2 substituting HMACRIPEMD160 for HMACSHA1.

Once you've done that, you'll have a byte array to use as a key. You can then just set the Key property of TripleDESCryptoServiceProvider in order to decrypt your ciphertext.

I'm Published!

shawnfa — Tue, 19 Oct 2004 16:34:00 GMT

The November 2004 issue of MSDN magazine is available online now, and it includes the first article I've ever had published. I co-authored this month's Trustworthy Code article, Exchange Data More Securely with XML Digital Signatures and Encryption with Mike Downen, the CLR Security PM. Time to head out to the local bookstore and pick up a stack of these ... :-)

.NET 1.0 SP 3 and .NET 1.1 SP 1 Released

shawnfa — Thu, 02 Sep 2004 21:26:00 GMT

Today we pushed .NET 1.0 SP3 and .NET 1.1 SP1 onto Windows Update as a Critical Update. You can also download the service packs from the MSDN download center. Here's a brief review of what's new for security in each service pack:

.NET 1.0 SP3 (v1.0.3705.6018) [download | complete changelist]

323683: NTLM authentication is lost on every call
321562: FIX: Role-based authentication fails for users who belong to many groups

and these security related fixes that weren't from the CLR security team:

324488: Forms authentication and view state fail intermittently under heavy load
327132: FIX: PassportIdentity does not require secure PIN when security-enhanced authentication is requested
327523: Users can open Web pages without the correct NTFS permissions

.NET 1.1 SP1 (v1.1.4322.2032) [download | Windows 2003 download | complete changelist]

836989: FIX: A user receives a "security exception" error message while running user code that is based on the .NET Framework 1.1 in a partial trust environment
828295: FIX: Error Message: Security Exception: PermissionToken Index Does Not Match Index into m_unrestrictedPermSet
839289: FIX: The GC heap becomes corrupted when you use the .NET Framework System.Security.Cryptography.RSACryptoServiceProvider class

Using DecryptDocument with Super-Encrypted Data

shawnfa — Wed, 21 Jul 2004 18:31:00 GMT

The EncryptedXml class comes with a nice utility method called DecryptDocument (For more information about using DecryptDocument check out my previous post introducing XML Encryption). This method will decrypt all the EncryptedData elements it finds, assuming that it is able to figure out what key to use to perform the decryption with. However, what happens if you use this method with some super encrypted data?

Super encryption is defined in the XML Encryption standard as encrypting an EncryptedData element (providing that you encrypt the entirety of the element). In other words, it's encrypting already encrypted data.

The DecryptDocument method will decrypt all top-level EncryptedData elements, however if they are super-encrypted, it will not continue to loop over the document to decrypt the resulting EncryptedData. If you want to fully decrypt a document containing super-encrypted data, you'll need to do this looping yourself. (Or if you want to be sure that you've fully decrypted a document, and you can't be sure if it contains super encrypted data or not).

The code to do this is very simple, you just need to keep calling DecryptDocument while EncryptedData elements still exist.

while(doc.GetElementsByTagName("EncryptedData", EncryptedXml.XmlEncNamespaceUrl).Count > 0 )
    exml.DecryptDocument();

Using the XSLT Transform with XML Signatures

shawnfa — Wed, 19 May 2004 19:33:00 GMT

One of the transforms that ships with the .Net framework is the XmlDsigXsltTransform, which implements the XSLT transform specified in the W3C recommendation. A few people have asked me to write a bit on how to use this transform, so here's a brief explanation and some sample code. This transform basically applies an XSL transform to the XML that will be signed, before the signature is computed, but after the reference has been resolved.

To clarify that last point, lets say I want to sign some XML with an id of "myxml". Currently no elements in the XML I want to sign have this ID, but I do have some XSL that will transform the input XML into some output that contains a node with the myxml id. This won't work, because the Reference will search my document for the element with the myxml id before the transform is applied. Since it won't find it, the transform will never be applied. (Something like the above scenario could be accomplished by creating a reference to the entire document, then applying a transform chain that first included the XSLT transform followed by an XPath one.)

One of the quirks of the XmlDsigXsltTransform class is that there is no easy way to programmatically set the XSL you'd like the transform to use. In order to create XSLT transforms, I use the following utility function, which takes as input the XSL you'd like the transform to apply.

/// <summary>
/// Utility method to create an XSLT transform from a string of XSL
/// </summary>
/// <param name='xsl'>XSL to use in the transform</param>
/// <returns>An XmlDsigXsltTransform that will apply the given XSL transform before signing</returns>
public static XmlDsigXsltTransform CreateXsltTransform(string xsl)
{
    XmlDocument doc = new XmlDocument();
    doc.LoadXml(xsl);

    XmlDsigXsltTransform xform = new XmlDsigXsltTransform();
    xform.LoadInnerXml(doc.ChildNodes);
    
    return xform;
} 

This method is easy to use. Simply pass it the XSL you want in your transform, and it will return you an XmlDsigXsltTransform object containing this XSL. It works by turning the XSL string into an XmlNodeList, and then calling LoadInnerXml on XmlDsigXsltTranform with this node list.

Using the transform is done in the same manner as the other transforms. First you create a reference to the XML you wish to sign. Then attach the transform object to that reference's transform chain. Verification code is unchanged from the standard verification code, since the transform will be embedded in the signature that is produced. Here's some sample code that signs a simple XML document using a basic XSL transform

// transform that will be used before signing the document

string xsl = @"

    <xs:transform xmlns:xs='http://www.w3.org/1999/XSL/Transform' version='1.0'>

        <xs:template match='/'>

            <xs:apply-templates/>

        </xs:template>

        <xs:template match='elementToTransform'>


            <transformedElement/>

        </xs:template>

    </xs:transform>";

// XML document to sign
string xml = @"

    <xml>

        <elementToTranform/>

    </xml>";
XmlDocument doc = new XmlDocument();
doc.LoadXml(xml);

// setup the signature as usual -- generally you'd have a known key
// to sign with instead of producing a random one.
RSA signingKey = new RSACryptoServiceProvider();
SignedXml signer = new SignedXml(doc);
signer.SigningKey = signingKey;

// create a reference to the entire document
Reference r = new Reference("");
r.AddTransform(new XmlDsigEnvelopedSignatureTransform());
r.AddTransform(CreateXsltTransform(xsl));
signer.AddReference(r);

// signature computation works as usual
signer.ComputeSignature();
doc.DocumentElement.AppendChild(signer.GetXml());

After running this code, the signed XML looks like this:

<xml>
  <elementToTransform />
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
      <Reference URI="">
        <Transforms>
          <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
          <Transform Algorithm="http://www.w3.org/TR/1999/REC-xslt-19991116">
            <xs:transform xmlns:xs="http://www.w3.org/1999/XSL/Transform" version="1.0">
              <xs:template match="/">
                <xs:apply-templates />
              </xs:template>
            <xs:template match="elementToTransform">
                <transformedElement xmlns="" />
              </xs:template>
            </xs:transform>
          </Transform>
        </Transforms>
        <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <DigestValue>lqgLQKa0...e66pmKI=</DigestValue>
      </Reference>
    </SignedInfo>
    <SignatureValue>juQQvRyG...E7r1Y0E=</SignatureValue>
  </Signature>
</xml>

One thing to notice here is that the output XML contains the original XML, not the version that would be produced when transformed by the XSL. Since the output also contains your XSL, whoever is verifying the signature can recompute the output. This is convenient, sine it means that your XSL doesn't have to produce XML (for instance, it could create HTML). However, if you don't want to share your XSL, then this may not be the transform for you. Instead, you might want to apply your XSL before computing the signature, in which case the XSL you use will not be available for anyone to see.

xml:id and SignedXml

shawnfa — Tue, 27 Apr 2004 21:53:00 GMT

A few weeks back, I posted about customizing how SignedXml searches for XML elements identified by a reference to an ID. By default, SignedXml searches for elements with an attribute named Id that has the given value.

Recently, the W3C has come up with a working draft for xml:id version 1.0. xml:id is meant to be a uniform way for XML elements to be uniquely identified. How it works is relatively simple. Elements simply add an attribute named id, with a namespace prefix of xml, and give it a unique value. For instance:

The xml prefix is a special prefix, and it should be mapped to the URI http://www.w3.org/XML/1998/namespace, according to the Namespaces in XML recommendation. Before xml:id, the only attributes defined in the xml namespace were xml:lang, xml:space, and xml:base.

As a more realistic example than the one I posted in my earlier blog entry, I've written an extension to the SignedXml class which allows for nodes to be signed given their xml:id. I've also made the complete source code to the XmlIdSignedXml class available. (With the standard disclaimers that Microsoft is not responsible if this code destroys your data, eats your dinner, or kicks your puppy when you're not looking.)

The class is pretty simple, providing only one new property to the SignedXml class. This property, a boolean called Strict, allows you to specify what the class should do if there's not a valid xml:id available. If Strict is set to true, then the search will fail. However, if Strict is set to false, then the default SignedXml id search is done. In either case, xml:id's trump the default search. XmlIdSignedXml also provides a constant that specifies the namespace URI that the xml prefix should map to. (Although you'll never need this, since the System.Xml classes will provide this mapping for you).

All of the interesting code is found in the GetIdElement override. After validating its parameters, this method sets up an XmlNamespaceManager that maps the xml prefix to the URI specified in the W3C's specs. Then the value to search for is quoted, in single quotes if it contains a double quote, and in double quotes if it contains a single quote. Searching for an id that contains both single and double quotes is forbidden.

The XPath query //*[@xml:id='idValue'] is used to get all the nodes that match the given xml id. Since the xml:id recommendation specifically requires that ID's be unique within the document, matching more than one node will cause XmlIdSignedXml to throw an InvalidOperationException. Assuming it finds only one match, this is returned as the result. If no matches are found, then the behavior depends on the setting of the Strict property. By default, Strict is set to false, so XmlIdSignedXml will revert back to the SignedXml semantics.

Signing with this code works exactly the same as signing with a standard SignedXml object. Remember that when validating documents signed by reference to xml:id, you must use an instance of the XmlIdSignedXml class, otherwise the validation will fail. If you'd like some sample code to perform the signing / verification, check out my previous post on Searching for Custom IDs, or More Secure XML Digital Signatures.

When using this class, XML that looks like this:

<xml>
  <signed xml:id='tag1'>Signed Data</signed>
  <unsigned xml:id='tag2'>Unsigned Data</unsigned>
  <signed xml:id='tag3'>More Signed Data</signed>
  <signed id='tag4'>Signed with default processing</signed>
</xml>

Will create a signature similar to the following:

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
  <SignedInfo>
    <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
    <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
    <Reference URI="#tag1">
      <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <DigestValue>feqM2k2kXyxPyXsKDgV8dsh74fE=</DigestValue>
    </Reference>
    <Reference URI="#tag3">
      <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <DigestValue>VjjjaTwSg/OU6z3wOHoTa7gEnFM=</DigestValue>
    </Reference>
    <Reference URI="#tag4">
      <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <DigestValue>bbKNmp7e3JFUDLpNdNGucke/g6o=</DigestValue>
    </Reference>
  </SignedInfo>
  <SignatureValue>KAtTJfRQ ... hQUGA+Y=</SignatureValue>
</Signature>

Using XPath to Sign Specific XML

shawnfa — Thu, 08 Apr 2004 00:25:00 GMT

In my last posting, I promised to write about a more general purpose way of selecting specific XML to sign. Although the technique I presented in the last post will work, it requires a custom class derived from SignedXml, and will not work unless both the signer and the verifier have access to, and use, that class. In order to have signatures validate by users who don't have your implementation of SignedXml (or don't even use the .NET XML digital signature mechanism at all), XPath is a better choice when initially signing a document.

Using XPath to sign specific parts of the XML document involves adding an XPath transform to a reference in your signature. In .NET, the XPath transform is represented by the XmlDsigXPathTransform class. This transform will take an XPath expression, and act as a filter, selecting the nodes you want to sign while removing the others.

The XPath transform works a little differently than you might expect. Instead of specifying an XPath expression that will result in the nodes you wish to sign, you specify a filter. Internally, the transform first takes the document that the reference points to and runs the following XPath expression on it:

(//. | //@* | //namespace::*)

This selects all of the nodes in the reference, and gets them into a node list. Each element in this node list is then evaluated against the XPath expression specified in the transform. If the result is true, the node is included in the signature, false excludes it.

When working with the XmlDsigXPathTransform, I use a utility method that creates the transform for me. The reason is that the class does not actually contain a way to programmaticly set the XPath that will be used. Instead, the only way to accomplish this is to create the XML form of the transform and load it into the object. The utility method is shown here.

/// <summary>
/// Create an XPath transform
/// </summary>
/// <param name='xpath'>XPath expression for the transform</param>
/// <returns>XPath transform that filters according to the given XPath expression</returns>
private static XmlDsigXPathTransform CreateXPathTransform(string xpath)
{
    // create the XML that represents the transform
    XmlDocument doc = new XmlDocument();
    XmlElement xpathElem = doc.CreateElement("XPath");
    xpathElem.InnerText = xpath;
        
    XmlDsigXPathTransform xform = new XmlDsigXPathTransform();
    xform.LoadInnerXml(xpathElem.SelectNodes("."));
            
    return xform;
} 

In order to use this transform, first create a reference to the entire document being signed (by passing in an empty string). Then call AddTransform on the reference, passing in the XPath transform. The following sample signs nodes named "signed", and ignores all others. Note the use of the ancestor-or-self:: axis in the query. If this weren't used, than any nodes that were children of the signed nodes wouldn't be signed. Most times this isn't the intention of the signer, and could lead to security holes.

// load the XML that will be signed
XmlDocument doc = new XmlDocument();
doc.LoadXml(xml);
    
SignedXml signer = new SignedXml(doc);

// create a reference to the whole document
// but sign only tags named signed
Reference r = new Reference("");
r.AddTransform(CreateXPathTransform("ancestor-or-self::signed"));
signer.AddReference(r);

signer.SigningKey = new RSACryptoServiceProvider();
signer.ComputeSignature(); 

In order to sign a document similar to the one from yesterday's post (where I'm signing based on "_Id" attributes, I would use code similar to this:

Reference r = new Reference("");
r.AddTransform(CreateXPathTransform("ancestor-or-self::*[@_Id=signme'"));
signer.AddReference(r); 

Applying a signature containing that reference to this XML:

<xml>

  <unimportant>Unsigned Data</unimportant>

  <important _Id='signme'>Signed Data</important>

  <vital _Id='signme'>More Signed Data</vital>

  <interesting>More Unsigned Data</interesting>

</xml>

Will result in a signature similar to the following:

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
  <SignedInfo>
    <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
    <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
    <Reference URI="">
      <Transforms>
        <Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
          <XPath>ancestor-or-self::*[@_Id='signme']</XPath>
        </Transform>
      </Transforms>
      <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <DigestValue>zGdeF6BumSVUfORJxKHfXvNQyG8=</DigestValue>
    </Reference>
  </SignedInfo>
  <SignatureValue>meG/yZGO . . . vkjbOIU=</SignatureValue>
</Signature>

The code to verify this signature is exactly the same as the code to verify a standard signature. You'll notice that the output XML contains both the transform itself and the XPath used in the transform. This lets the validating code reconstruct the transform object without any special instructions from you.

One note on using this to sign multiple nodes. If you need to use more than one XPath expression, then you need to use more than one reference. Adding multiple transforms to the same reference will actually just chain them together, making the second one filter the results of the first one. Two XPath transforms on separate references will work as expected, with each transform having access to all of the nodes in the document.

Searching for Custom ID Tags With Signed XML

shawnfa — Tue, 06 Apr 2004 00:56:00 GMT

Last week, I blogged about using references to sign only specific parts of an XML document. The biggest limitation with doing this is that you must refer to the nodes that are being signed by ID, which for v1.1 and 1.0 of the framework was given by an attribute named "Id". The problem there is that the Id attribute may already have another use in your schema, and you cannot reuse them for creating node names. Another problem that may come up is that the XML being signed may be generated by a tool or program, and it's not possible for you to add Id tags. Whidbey reduces this limitation somewhat by also allowing "id" and "ID", but the fundamental problem still exists.

Recently, this problem cropped for one of our customers who was having a problem getting signed XML to work in his environment. Their application was trying to sign XML generated by a Java program. The Java application had generated ids by using "_Id" attributes, making it impossible to sign with an id based reference. If the only problem was creating a signature, then there would be an easy workaround. However, the C# portion of the program was trying to verify the signature that the Java application had created, and could not resolve references to the _id elements.

So, how did we solve this problem? Actually with a very clever solution from one of the other members of the security team. Nodes that are being referred to by ID are resolved in the GetIdElement method of the SignedXml class. By subclassing SignedXml and overriding this method, its possible to create your own id node resolver. I'll show a sample here that allows ids prefixed with underscores to be resolved by XML signature engine.

Although this sample relies on a similar ID attribute mechanism for identifying nodes, there's nothing stopping you from creating a fancier system. Just as long as you always return exactly one XmlElement representing the specified node, or null if the node could not be found. The best use of this technique is to enable interop scenarios. If you're trying to do this simply to have more fine-grained control over which nodes your reference identifies, I'll show a better technique later this week.

Implementation

The only method that I'll need to override is the GetIdElement method. In addition, I'll provide a constructor that takes an XmlDocument, and passes it along to the SignedXml constructor. I've also defined an array of strings, which represent the attributes that I'll allow to identify nodes. Here's the code:

public class CustomIdSignedXml : SignedXml
{
    private static readonly string[] idAttrs = new string[]
    {
        "_id",
        "_Id",
        "_ID"
    };

    public CustomIdSignedXml(XmlDocument doc) : base(doc)
    {
        return;
    }
    
    public override XmlElement GetIdElement(XmlDocument doc, string id)
    {
        // check to see if it's a standard ID reference
        XmlElement idElem = base.GetIdElement(doc, id);
        if(idElem != null)
            return idElem;

        // if not, search for custom ids
        foreach(string idAttr in idAttrs)
        {
            idElem = doc.SelectSingleNode("//*[@" + idAttr + "=\"" + id + "\"]") as XmlElement;
            if(idElem != null)
                break;
        }

        return idElem;
    }
} 

So what's going on here? At the beginning of the method, I call the default GetIdElement, and if that found a match, return that node. This allows my resolver to continue working with "Id" nodes. Since I do this at the beginning of the method, it also makes it so that nodes with the standard id attributes take precedence over nodes with my custom attributes. Next, I loop over my custom attributes, and perform an XPath query, looking for the first node that has a custom attribute with the correct value. Since I quit searching for nodes as soon as I find a match, the order that the attributes appear in the idAttrs array is also the order of precedence. For instance a reference to #idnode when run over the following XML,

<root>
  <node1 _id='idnode'/>
  <node2 Id='idnode'/>
  <node3 _ID='idnode'/>
  <node4 _ID='otherref'/>
  <node5 _id='otherref'/>
  <node6 _id='otherref'/>
</root> 

will match node2, since IDs found by the SignedXml class have the highest precedence. A reference to #otheref will match node5, since _id occurs before _ID in my search and only the first match is returned.

Searching for the id nodes is done with the SelectSingleNode method, passing an XPath query customized for the name of the id attribute and the ID I'm looking for. For instance, when searching for nodes with an _ID attribute that would match a reference to #myref, the XPath would be:

//*[@_Id="myref"]

Signing With Custom IDs

Creating a signature that would use the custom id resolver is done in exactly the same way that normal signatures containing id references are done. The only difference is that instead of creating a SignedXml object, you create an instance of the custom ID resolver. Since GetIdElement is virtual, you can even assign the instance into a SignedXml object, and everything will still work as expected. This helps to enable scenarios where the code that actually computes signatures lives in a different method that you don't control, however you do have write access to the SignedXml object they use.

Enough talk, here's some sample code showing a signature being created with my custom _Id resolver. The XML that I'm going to sign is:

<xml>
  <tag Id='tag1'/>
  <tag _Id='tag2'/>
</xml> 

And the code that computes the signature is:

XmlDocument doc = new XmlDocument();
doc.LoadXml(xml);

SignedXml signer = new CustomIdSignedXml(doc);
signer.AddReference(new Reference("#tag1"));
signer.AddReference(new Reference("#tag2"));
        
signer.SigningKey = new RSACryptoServiceProvider();
signer.ComputeSignature();
Console.WriteLine(signer.GetXml().OuterXml) 

This produces a signature similar to the following:

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
  <SignedInfo>
    <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
    <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
    <Reference URI="#tag1">
      <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <DigestValue>/dsJPkLT3QydsHQ1dpmMLPEIbRo=</DigestValue>
    </Reference>
    <Reference URI="#tag2">
      <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <DigestValue>AWY9mgt5Z+jRSS+CevluG77gFC8=</DigestValue>
    </Reference>
  </SignedInfo>
  <SignatureValue>JVXWblnT . . . 55rZ7zc=</SignatureValue>
</Signature> 

Verifying the Signature

Remember that since the standard SignedXml class will have no idea how to resolve references to custom ID nodes, so verification will also need an instance of the custom signed xml class. However, aside from this difference verification works exactly as you would expect

SignedXml verifier = new CustomIdSignedXml(doc);
verifier.LoadXml(signer.GetXml());
if(verifier.CheckSignature(signer.SigningKey))
    Console.WriteLine("Signature verified");
else
    Console.WriteLine("Invalid signature");

Signing Specific XML With References

shawnfa — Wed, 31 Mar 2004 23:15:00 GMT

I've previously blogged about creating XML digital signatures using the .NET framework, but today I'd like to write about a more advanced technique using these signatures. My previous post signed an entire XML document, however, this is not always necessary or even desirable. For instance, if a particular XML document was being authored by several people, you might only want to sign the portions that you worked on.

In this post, I'm going to work with the following XML, signing the elements named signed, but not providing a signature for the unsigned element.

<xml>
  <signed id='tag1'>Signed Data</signed>
  <unsigned id='tag2'>Unsigned Data</unsigned>
  <signed id='tag3'>More Signed Data</signed>
</xml>

Previous signatures I've shown have all contained only one reference, which referred to the entire document. In order to sign more specific portions of the document, you can sign elements by id. An element's id is any element that contains an 'id', 'Id', or 'ID' attribute. Its important to keep in mind that signing an element will also sign any sub elements.

In order to refer to an element by ID, the reference must be created by passing a string of the form "#id". Here's some sample code that will create references to the signed data from above.

XmlDocument doc = new XmlDocument();
doc.LoadXml(xml);

SignedXml signer = new SignedXml(doc);
signer.AddReference(new Reference("#tag1"));
signer.AddReference(new Reference("#tag3"));

Notice that its perfectly legal to use multiple references in the same signature. This allows me to sign multiple portions of the document with my key. The process of actually signing the document is the same as it was with only one reference. Of course, in reality I would not be generating a random key to sign with, but I would use a key pair that was available for interested parties to find, so that they could verify the signature.

signer.SigningKey = new RSACryptoServiceProvider();
signer.ComputeSignature(); 

This produces signed XML that looks like the following:

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
  <SignedInfo>
    <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
    <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
    <Reference URI="#tag1">
      <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <DigestValue>6kGyfacrtc02JR23FNmcoR+OKzc=</DigestValue>
    </Reference>
    <Reference URI="#tag3">
      <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <DigestValue>DtoiDLz3qs7wLwN8Y9A8J5Qpb/I=</DigestValue>
    </Reference>
  </SignedInfo>
  <SignatureValue>SQN+6HlM . . . NqvsN04=</SignatureValue>
</Signature>

Verifying this signature works exactly the same as verifying the signature over an entire document. You'll also notice that even if you modify the value of the unsigned element, the signature still verifies.

// modify the unsigned element -- the signature should still verify
XmlElement unsignedElem = doc.SelectSingleNode("//xml/unsigned") as XmlElement;
unsignedElem.InnerText = "Modified Data";

SignedXml verifier = new SignedXml(doc);
verifier.LoadXml(signer.GetXml());

if(verifier.CheckSignature(signer.SigningKey)))
    Console.WriteLine("Pass");
else
    Console.WriteLine("Fail"); 

Updated: I needed to be more clear above. "id" and "ID" only work on Whidbey. If you're using v1.0 or 1.1 of the framework, you'll need to use "Id" attributes.

What's New in XML For Whidbey

shawnfa — Wed, 31 Mar 2004 02:17:00 GMT

The new XML Developer Center on MSDN has a nice article about the new XML features in Whidbey. The top 10 list is:

Creating a SecurityElement from XML

shawnfa — Wed, 25 Feb 2004 02:25:00 GMT

Most of the .NET security system can be serialized out to XML, and knows how to deserialize itself from an XML stream. This would seem to make it easy to create security objects (such as PermissionSet's) from XML documents, or maybe use an XPath query or XSLT transform on one of these objects. However, instead of using standard System.Xml classes to represent our XML data, the security system uses its own XML class, System.Security.SecurityElement.

There are several reasons for this, including the fact that security code must execute very quickly, and is executed quite frequently. The overhead of a full-fledged XML parser would be too much. Even if you accept the fact that we need a lightweight security XML object, we can't even provide utility methods on SecurityElement to convert back and forth System.Xml objects, since the CAS code lives in mscorlib.dll, and mscorlib cannot take a dependency on external DLL's. (Think of what would happen if mscorlib depended on System.Xml.dll, and System.Xml.dll depended on mscorlib ...). As if this weren't enough, there are at least 3 distinct XML parsers in v1.1 of the framework (System.Xml, SecurityElement, and a lightweight parser in mscoree.dll which handles parsing .config files ... this was actually optimized to be able to fit into no more than two pages of memory). Whidbey will be adding yet another parser to handle parsing ClickOnce manifests.

With all these different XML representations, commonly people need to convert between them. Since you'll most likely never be handling the mscoree representation, I'll show some sample code for converting between System.Xml and SecurityElement.

Converting SecurityElement to XmlElement

Going from SecurityElement to XmlElement is relatively easy, since everything expressable within the SecurityElement object model is also available in System.Xml. All that needs to be done is to make a new XmlElement with a tag matching the SecurityElement, create any XmlAttributes on the element, and copy over any inner text that might exist. This needs to be done recursively for each child node of the SecurityElement.

/// <summary>
/// Convert a security element XML tree into an System.Xml XML tree
/// </summary>
/// <param name="se">security element at the root of the tree</param>
/// <returns>an XML Node at the root of the System.Xml Tree</returns>
public static XmlNode SecurityElementToXml(SecurityElement se)
{
    return SecurityElementToXmlInternal(se, new XmlDocument());
}

/// <summary>
/// Convert a security element XML tree into an System.Xml XML tree
/// </summary>
/// <param name="se">security element at the root of the tree</param>
/// <param name="doc">XML Document context to create new XML nodes from</param>
/// <returns>an XML Node at the root of the System.Xml Tree</returns>
private static XmlNode SecurityElementToXmlInternal(SecurityElement se, XmlDocument doc)
{
    XmlNode root = doc.CreateElement(se.Tag);

    if(se.Text != null)
      root.AppendChild(doc.CreateTextNode(se.Text));

    if(se.Attributes != null)
    {
      foreach(string attr in se.Attributes.Keys)
      {
        XmlAttribute xmlAttr = doc.CreateAttribute(attr);
        xmlAttr.Value = (string)se.Attributes[attr];
        root.Attributes.Append(xmlAttr);
      }
    }

    if(se.Children != null)
      foreach(SecurityElement child in se.Children)
        root.AppendChild(SecurityElementToXmlInternal(child, doc));

    return root;
}

Converting from XmlElement to SecurityElement

Going from System.Xml to SecurityElement is a little more tricky, since SecurityElement cannot express every bit of valid XML. The only XML nodes in the SecurityElement object model are elements, attributes, and text, so anything in an XmlDocument that does not fall into one of these three categories cannot be converted. The following code performs the conversion by looking at each child of the XmlElement, and deciding what to do based on its type. If the child is an XmlElement, it recursively calls itself and appends the child node to the new SecurityElement's children. If it's an attribute, the attribute is added to the security element, and text is added as the inner text of the new SecurityElement. Comments are skipped over, and an InvalidOperationException is thrown if any other type of element is discovered.

/// <summary>
/// Convert an XML Element into a SecurityElement
/// </summary>
/// <remarks>
///  Throws an InvalidOperationException if there are nodes that are not
/// of type XmlElement, XmlAttribute or XmlText in the tree.
/// </remarks>
/// <param name="xml">xml element to convert</param>
/// <returns>SecurityElement representation</returns>
public static SecurityElement XmlToSecurityElement(XmlNode xml)
{
    SecurityElement root = new SecurityElement(xml.Name);
    foreach(XmlNode node in xml.ChildNodes)
    {
      if(node is XmlElement)
        root.AddChild(XmlToSecurityElement((XmlElement)node));
      else if(node is XmlText)
        root.Text = ((XmlText)node).Value;
      else if(node is XmlComment)
        continue;
      else
        throw new InvalidOperationException("Cannot convert XML with nodes of type " + node.GetType());
    }
    foreach(XmlAttribute attr in xml.Attributes)
      root.AddAttribute(attr.Name, attr.Value);

    return root;
}

Given this function, one nice piece of utility code to convert a string of XML into a SecurityElement (which is not possible with the current object model) is:

/// <summary>
/// Convert an XML string to a security element
/// </summary>
/// <param name="xml">string of XML to convert</param>
/// <returns>SecurityElement that the string represents</returns>
public static SecurityElement StringToSecurityElement(string xml)
{
    XmlDocument doc = new XmlDocument();
    doc.LoadXml(xml);

    return XmlToSecurityElement(doc.DocumentElement);
}

Using XML Encryption With CipherReferences, Part 2 - Remote Data

shawnfa — Wed, 18 Feb 2004 22:30:00 GMT

Earlier this week, I posted about using cipher references to refer to data stored in the same document. Today I'll use the same technique, but instead of storing the encrypted data elsewhere in the document, I'm going to store it on a seperate server. Of course, I'll be using the familiar order.xml sample to work with. The samples all assume that I have a webserver with a shared root folder on \\webserver\wwwroot, which is accessed at http://webserver.

Encrypting the data

Encrypting the data to store on a server is very similar to the encryption step for storing locally. However, since my data will be in a seperate file, and not embedded in XML, I've decided to not base64 encode it. Instead, I'll just write the bytes out to a binary file.

// load the data
XmlDocument doc = new XmlDocument();
doc.Load("order.xml");
XmlElement paymentElem = doc.SelectSingleNode("/order/payment") as XmlElement;

// encrypt
SymmetricAlgorithm key = new RijndaelManaged();
byte[] cryptData = new EncryptedXml().EncryptData(Encoding.UTF8.GetBytes(paymentElem.OuterXml), key);

// store the encrypted data on a web server
using(FileStream writer = new FileStream(@"\\webserver\wwwroot\orders\order.bin", FileMode.Create))
{
    writer.Write(cryptData, 0, cryptData.Length);
    writer.Close();
}

Creating the EncryptedData

Creating a cipher reference for this data will be much easier than it was when I was referencing the local data. Since the local data was base64 encoded, and stored within an XML element, I needed to apply a transform chain. However, the data this time is stored as raw bytes, so no transforms are needed. This means I can just use the CipherReference constructor to point to the URI where the data is stored, without having to hand-craft the CipherReference XML myself. Once I have the CipherReference, setting up the EncryptedData object is relativly straight forward, and very similar to the standard XML encryption case.

// create a cipher reference to the stored data, and setup the encrypted data
CipherReference cr = new CipherReference("http://webserver/orders/order.bin");
EncryptedData encrypted = new EncryptedData();
encrypted.CipherData = new CipherData(cr);
encrypted.KeyInfo.AddClause(new KeyInfoName("key"));
encrypted.EncryptionMethod = new EncryptionMethod(EncryptedXml.XmlEncAES256Url);
EncryptedXml.ReplaceElement(paymentElem, encrypted, false);

This creates the following XML:

<order>
  <purchase>
    <item quantity="1">Def Leppard: Pyromania</item>
    <item quantity="1">Ozzy Osbourne: Goodbye to Romance</item>
  </purchase>
  <shipping>
    <to>Shawn Farkas</to>
    <street>5 21st Street</street>
    <city>Seattle</city>
    <state>WA</state>
    <zip>98000</zip>
  </shipping>
  <EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#">
    <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc" />
    <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
      <KeyName>key</KeyName>
    </KeyInfo>
    <CipherData>
      <CipherReference URI="http://webserver/orders/order.bin" />
    </CipherData>
  </EncryptedData>
</order>

Decrypting

Decrypting this document works almost exactly the same as with standard XML encryption, however there is one difference. Since the XML decryption engine will have to go to an arbitrary website and download some data, this could expose a security hole (depending on how much you trust the XML document). In order to establish the trust-level for the specific document, there is a property, DocumentEvidence, on the EncryptedXml class which represents the evidence for this document. It is up to you to set this property properly. For instance, if the document came from the internet, you might add Zone evidence for the Internet zone, and perhaps some site evidence for the site it came from. Under the default security policy, that would restrict the document from getting data from any website but the same one it came from. In this instance, since http://webserver looks like an intranet site, I'm going to setup LocalIntranet and Site evidence.

EncryptedXml decryptXml = new EncryptedXml(doc);
decryptXml.DocumentEvidence = new Evidence();
decryptXml.DocumentEvidence.AddHost(new Zone(SecurityZone.Intranet));
decryptXml.DocumentEvidence.AddHost(new Site("webserver"));
decryptXml.AddKeyNameMapping("key", key);
decryptXml.DecryptDocument();

Once again, after this is run, the XML document contained in the doc variable is exactly the same as the original order XML.

Using XML Encryption With CipherReferences, Part 1 - Local Data

shawnfa — Tue, 17 Feb 2004 00:30:00 GMT

Most users of encrypted XML will encrypt their data and embed the resulting cipher value directly into the EncryptedData element, using a CipherValue tag. However, XML encryption also supports the use of CipherReferences, which allow you to place the encrypted XML outside of the EncryptedData element, or even outside of the current document. Getting this to work is a little tricky, so I'll provide an example here of referring to encrypted data that is stored elsewhere in the current document. Once again, I'll be using my order XML to work with.

Encrypting the data

The first step is to encrypt the data into an array of bytes. This is easily accomplished in the same way as I showed in my previous discussion of XML Encryption.

// load the data
XmlDocument doc = new XmlDocument();
doc.Load("order.xml");
XmlElement paymentElem = doc.SelectSingleNode("/order/payment") as XmlElement;

// encrypt
SymmetricAlgorithm key = new RijndaelManaged();
byte[] cryptData = new EncryptedXml().EncryptData(Encoding.UTF8.GetBytes(paymentElem.OuterXml), key);

Now that the data is encrypted, it must be inserted into the document. To do this, I will create a new XML node (called encrypted), with a specific ID (payment), that I will use in the cipher reference to poin the XML decryption engine to the correct location. In order to store the binary data in XML, I must first transform it into a base64 string.

// setup the element pointed to by the ciper reference
XmlElement cryptElem = doc.CreateElement("encrypted");
cryptElem.InnerText = Convert.ToBase64String(cryptData);
XmlAttribute idAttr = doc.CreateAttribute("id");
idAttr.Value = "payment";
cryptElem.Attributes.Append(idAttr);
doc.DocumentElement.AppendChild(cryptElem);

Creating the CipherReference

Unfortunately, there is no easy way to create a cipher reference programatically. In order to create the cipher reference, you must first create the XML that represents the reference, and then load that XML into a CipherReference object. There are a couple of things to look out for when creating this XML. You must include a transform chain that takes as input the node that the reference points to, and returns as output the byte array of encrypted data. In the above example, I transformed the byte array into a base 64 string, then placed it into the body of an XML element. In order to convert this back into a byte array, I must first use an XPath expression to get the value out of the XML element, and then use a base64 transform to convert the string into raw bytes. This transform chain is shown in the given XML. The other interesting part of the CipherReference XML is that the URI must be set to "#id", where id is the ID given to the XML element holding the encrypted data (in this case "payment").

// Create a CipherReference to refer to the data in the /order/encrypted element
CipherReference cr = new CipherReference();
XmlDocument reference = new XmlDocument();

// note: make sure the appropriate transforms are added to convert the encrypted data back to bytes
reference.LoadXml(
    @"<CipherReference URI='#payment'> 
  <Transforms xmlns='http://www.w3.org/2001/04/xmlenc#'>
   <Transform xmlns='http://www.w3.org/2000/09/xmldsig#'
     Algorithm='http://www.w3.org/TR/1999/REC-xpath-19991116'>
    <XPath>self::text()</XPath>
   </Transform>
   <Transform xmlns='http://www.w3.org/2000/09/xmldsig#'
     Algorithm='http://www.w3.org/2000/09/xmldsig#base64'/>
  </Transforms>
    </CipherReference>");
cr.LoadXml(reference.DocumentElement);

Creating an EncryptedData object from the CipherReference

Next, an EncryptedData object must be created from the CipherReference. This step is very similar to the standard XML encryption. The only notable difference is that CipherData is created with a CipherReference instead of a CipherValue. Note that the encryption key and method must still be setup properly. Once I've constructed the EncryptedXml object, I replace the payment element with it.

// Create the EncryptedData object from the cipher reference
EncryptedData encrypted = new EncryptedData();
encrypted.CipherData = new CipherData(cr);
encrypted.KeyInfo.AddClause(new KeyInfoName("key"));
encrypted.EncryptionMethod = new EncryptionMethod(EncryptedXml.XmlEncAES256Url);
EncryptedXml.ReplaceElement(paymentElem, encrypted, false);

This creates XML that looks like:

<order>
  <purchase>
    <item quantity="1">Def Leppard: Pyromania</item>
    <item quantity="1">Ozzy Osbourne: Goodbye to Romance</item>
  </purchase>
  <shipping>
    <to>Shawn Farkas</to>
    <street>5 21st Street</street>
    <city>Seattle</city>
    <state>WA</state>
    <zip>98000</zip>
  </shipping>
  <EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#">
    <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc" />
    <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
      <KeyName>key</KeyName>
    </KeyInfo>
    <CipherData>
      <CipherReference URI="#payment">
        <Transforms>
          <Transform
              Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116"
              xmlns="http://www.w3.org/2000/09/xmldsig#">
            <XPath>self::text()</XPath>
          </Transform>
          <Transform
              Algorithm="http://www.w3.org/2000/09/xmldsig#base64"
              xmlns="http://www.w3.org/2000/09/xmldsig#" />
        </Transforms>
      </CipherReference>
    </CipherData>
  </EncryptedData>
  <encrypted id="payment">65ZxnnE3 ... wRtm+A==</encrypted>
</order>

Decrypting

Decrypting a document with a cipher reference works exactly the same as decrypting the document with the cipher value embedded in the encrypted data. All that has to be done is create an EncryptedXml object for the document, setup the key name, and call DecryptDocument. I also remove the cipher data from the resulting document, since DecryptDocument will only remove the EncryptedData.

EncryptedXml decryptXml = new EncryptedXml(doc);
decryptXml.AddKeyNameMapping("key", key);
decryptXml.DecryptDocument();
doc.DocumentElement.RemoveChild(doc.SelectSingleNode("/order/encrypted[@id='payment']"));

After running the decryption code over the encrypted XML, the resulting XML is exactly the same as the original, unencrypted order.xml. In my next post, I'll show how to use CipherReferences to refer to encrypted data not even in the same document as the EncryptedData tag.