Concepts

Now let’s look at the concepts in the various W3C recommendations that are implemented by XML Security. We’ll look at XML Canonicalization first, because both XML Signature and XML Encryption use it. Then we’ll look at XML Signature and XML Encryption.

Canonicalization

When there are multiple representations for a piece of data, we often pick one representative to be the most desirable to work on. What it means to be desirable often depends on the kind of work we want to do. This selected form is sometimes known as a canonical form. Usually canonical forms are picked so they’re simple and easy to work with. In the case of XML, the canonical form of an XML document obeys a set of rules regarding its structure but is still equivalent to the original XML document. Think about the number of ways you can have the same XML document. If you take a document and change the order in which the attributes appear, the document is essentially the same. If you take empty tags like <book/> and write them as <book><book/>, you haven’t changed the meaning of the document.

One of the goals of the XML Canonicalization Recommendation is to specify a canonical form for XML documents that can be used to determine whether two documents are identical. This is important for cryptography applications because we want to encrypt the canonical form of an XML document, not the document itself—the canonical form can tell you whether a document has been modified (at least, in certain ways).

Note

You’ll often see the word canonicalization written as c14n—the first and last characters of the word plus 14, which stands for the 14 characters between c and n. This is a short form that’s growing in usage.

Here are the rules for an XML document that’s in canonical form, according to the Canonical XML Recommendation:

• The document is encoded in UTF-8.

• Line breaks are normalized to #A in input before parsing.

• Attribute values are normalized according to the rules for validating XML processors.

• Character and parsed entities are replaced.

• CDATA sections are replaced with their character content.

• The XML declaration and DTD are removed.

• Empty elements are converted to start-end tag pairs.

• Whitespace outside the document element and within start and end tags is normalized.

• All whitespace in character content is retained (aside from characters removed during line-feed normalization).

• Attribute value delimiters are set to quotation marks.

• Special characters in attribute values and character content are replaced by character references.

• Superfluous namespace declarations are removed from each element.

• Default attributes are added to each element.

• Lexicographic order is imposed on the namespace declarations and attributes of each element.

The recommendation describes the process by which you can convert any XML document into a canonical form that obeys all of these rules. (There are actually two canonical forms: one that includes any comments from in the original document and one that doesn’t.) The details of how a document is converted into canonical form aren’t really important for you to understand, but the result of that process is. It means you can write a library to canonicalize XML documents.

Here’s a document using the book schema:

  1: <?xml version="1.0" encoding="UTF-8"?>   2: <book xmlns="http://sauria.com/schemas/apache-xml-book/book"    3:   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    4:   xsi:schemaLocation=   5:    "http://sauria.com/schemas/apache-xml-book/book    6:     http://www.sauria.com/schemas/apache-xml-book/book.xsd"   7:   version="1.0">   8:   <title>Professional XML Development with Apache Tools</title>   9:   <author>Theodore W. Leung</author>  10:   <isbn>0-7645-4355-5</isbn>  11:   <month>December</month>  12:   <year>2003</year>  13:   <publisher>Wrox</publisher>  14:   <address>Indianapolis, Indiana</address>  15: </book>

This is what the document looks like after it’s been converted into XML canonical form. We inserted line breaks in the book element (lines 1-6) in order to make it more readable:

  1: <book xmlns="http://sauria.com/schemas/apache-xml-book/book"   2:  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   3:  version="1.0"   4:  xsi:schemaLocation=   5:   "http://sauria.com/schemas/apache-xml-book/book   6:       http://www.sauria.com/schemas/apache-xml-book/book.xsd">   7:   <title>Professional XML Development with Apache Tools</title>   8:   <author>Theodore W. Leung</author>   9:   <isbn>0-7645-4355-5</isbn>  10:   <month>December</month>  11:   <year>2003</year>  12:   <publisher>Wrox</publisher>  13:   <address>Indianapolis, Indiana</address>  14: </book>

The big changes are the removal of the XML declaration from line 1 of the original and the sorting of the namespace declarations and attributes (lines 2-7 of the original and 1-6 of the canonical form).

Exclusive Canonicalization

It turns out that there’s a problem with the way XML canonicalization works when it’s applied to the digital signature environment or any encapsulated protocol environment. The issue arises when you want to canonicalize just a subelement of a document. In this situation, XML canonicalization may capture namespace declarations and attributes in the xml: namespace from the enclosing elements/document. These values are used when computing a digital signature for this subelement. This will be a problem if the signed subelement is extracted from the original document and/or inserted into another document. Exclusive XML Canonicalization was created to address this and other limitations. It adds two new rules to the set of rules for XML Canonicalization when canonicalizing a document subset:

• Attributes in the XML namespace, such as xml:lang or xml:space, aren’t imported into the document subset.

• Namespace nodes that aren’t on the InclusiveNamespacesPrefixList are expressed only in start tags where they’re visible and only if they aren’t declared in an enclosing element in the subset. The InclusiveNamespacesPrefixList is a parameter to the Exclusive Canonicalization algorithm, which specifies a list of namespace prefixes that should be handled according to the canonical XML rules.

With the advent of exclusive canonical XML, canonical XML is also known as inclusive canonical XML.

XML Signature

The XML Signature Recommendation describes an XML syntax for digital signatures. These signatures can be applied to any kind of data, not just XML. There are two kinds of signatures. In an enveloped (or enveloping) signature, the signature and the data being signed are in the same document. A detached signature signs data that’s external to the document containing the XML signature element.

We’ll explain how XML Signature works by taking you through an example. This is the book document after being signed using XML signature:

  1: <book xmlns="http://sauria.com/schemas/apache-xml-book/book"   2:  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   3:  version="1.0"   4:  xsi:schemaLocation=   5:   "http://sauria.com/schemas/apache-xml-book/book   6:       http://www.sauria.com/schemas/apache-xml-book/book.xsd">   7:   <title>Professional XML Development with Apache Tools</title>   8:   <author >Theodore W. Leung</author>   9:   <isbn>0-7645-4355-5</isbn>  10:   <month>December</month>  11:   <year>2003</year>  12:   <publisher>Wrox</publisher>  13:   <address>Indianapolis, Indiana</address>

Everything up to this point is the original book document, except that the book document has been converted into inclusive canonical XML form. Everything after this is related to XML signature. In order to fit the document into the pages of this book in a readable fashion, we’ve done a small amount of pretty-printing, and we’ve truncated the base64 data that appears in the example.

The Signature Element

The <Signature> element is the element defined by XML Signature to represent a digital signature. Its namespace URI is http://www.w3.org/2000/09/xmldsig#, and in this document you use the prefix ds for the URI. A <Signature> element contains a <SignedInfo>, which is the element that’s signed, along with a description of how to sign it. The <SignedInfo> element can also describe other data to be signed. Returning to the <Signature> element, after the <SignedInfo> element it contains a <SignatureValue> element whose content is the digital signature value. Optionally, it contains a <KeyInfo> element that describes how to obtain the key needed to verify the signature. It also optionally contains some number of <Object> elements that can be used to associate additional information with the signature.

The SignedInfo Element

A <SignedInfo> element contains a <CanonicalizationMethod>, a <SignatureMethod>, and one or more <Reference> methods:

 14: <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">  15: <ds:SignedInfo>

Before the <SignedInfo> element is signed, it’s converted to canonical XML using the algorithm specified by the Algorithm attribute. The XML Signature spec requires support for inclusive canonical XML without comments. Canonical XML with comments is also allowed. The Algorithm attribute value is a URI, allowing URIs for other canonicalization algorithms, such as exclusive canonical XML (with and without comments) to be specified, but these aren’t required in any way by the XML Signature spec:

 16: <ds:CanonicalizationMethod Algorithm=  17:  "http://www.w3.org/TR/2001/REC-xml-c14n-20010315">  18: </ds:CanonicalizationMethod>

The <SignatureMethod> element describes the algorithm used to digitally sign the <SignedInfo> element. The Algorithm attribute is used the same way as in the <CanonicalizationMethod> element. The XML Signature specification uses algorithms that are a combination of a message digest algorithm and a digital signature algorithm. The spec requires the support of the DSA digital signature algorithm with SHA1 as the digest algorithm, which is what’s used in this example. It recommends that implementations support the RSA digital signature algorithm, again with SHA1 as the digest algorithm:

 19: <ds:SignatureMethod  20:  Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1">  21: </ds:SignatureMethod>

Referencing Data to Be Signed

The <SignedInfo> element can contain one or more <Reference> elements. These elements are used to specify data that should be signed. A <Reference> element contains an optional <Transforms> element, a required <DigestMethod>, and a required <DigestValue>. A <Reference> element is generated during signing of the data. In the simplest case, the data referred to by the reference is digested (using a message digest algorithm), and the digest value is stored as the content of the <DigestValue> element. If the optional <Transforms> element has been supplied, then the transforms specified are applied to the data before it’s digested.

The URI attribute of the <Reference> element specifies a data object that’s the target of the reference. Here you reference the <author> element whose id attribute is "#author". To specify the entire document without comments, leave the value of URI empty. To specify the entire document with comments, the value of URI should be "#xpointer(/)":

 22: <ds:Reference URI="#author">

The <Transforms> element contains a sequence of <Transform> elements. You can think of the <Transforms> element as a pipeline of <Transform>s. The input of each <Transform> is the output of the one before it, except the first and the last. For the first <Transform>, the input is the referenced data object; for the last <Transform>, the output serves as input to the message digest algorithm. This example has two <Transform>s: the enveloped signature transform and an inclusive XML canonicalization with comments:

 23: <ds:Transforms>  24: <ds:Transform   25:  Algorithm=  26:   "http://www.w3.org/2000/09/xmldsig#enveloped-signature">  27: </ds:Transform>  28: <ds:Transform  29:  Algorithm=  30:  "http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments">  31: </ds:Transform>

XML Signature specifies a set of transform algorithms:

• A canonicalization algorithm—Any canonicalization algorithm that can be used for <CanonicalizationMethod> can be used as a transform.

• A base64 decoding transform—Assumes the input is base64 and returns the decoded data as output.

• An XPath filtering transform—The XPath expression is evaluated, and the result is the output. XML Signature defines a new XPath function here that can be used in this transform. The here function returns a node set containing the attribute, processing instruction, or parent node of the text node containing the XPath expression. Support for the XPath filtering transform is optional.

• The Enveloped Signature Transform—Removes the entire <Signature> element that contains the enveloped signature transform. This means the digest won’t include the <Signature> element.

• XSLT Transform—The output is the result of applying an XSLT stylesheet to the data object. The stylesheet is the child element of the <Transform> element. Support for the XSLT transform is optional.

In this example, the data object is the <author> element in <book> (due to the #author fragment identifier specified as the value of the <Reference> URI attribute). So, the <author> element has the enveloped signature transform applied (which does nothing, because the Signature element isn’t part of the referenced data), and then it’s canonicalized using inclusive XML canonicalization with comments. The last step is to use the algorithm specified by <DigestMethod> to compute a message digest value:

 32: </ds:Transforms>  33: <ds:DigestMethod  34:  Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">  35: </ds:DigestMethod>

The <DigestMethod> element specifies the algorithm to be used to compute the <DigestValue>. The input is the output of the last <Transform>, or the data object if no <Transforms> element is supplied. Here you use SHA1 as the digest method. The XML Signature Recommendation requires SHA1 to be available as a digest method. It also states that MD5 is not recommended due to recent advances in cryptanalysis.

<DigestValue>’s content is the base64-encoded SHA1 digest of the referenced data:

 36: <ds:DigestValue>198q+YUGo9GC27hTpZOO93eUF3Y=</ds:DigestValue>

The SignatureValue Element

Now we’re ready to talk about the <SignatureValue>, whose content is the digital signature of the <SignedInfo> element:

 37: </ds:Reference>  38: </ds:SignedInfo>  39: <ds:SignatureValue>Su0ucZAbiIs4+0HJB1BBmnBKbbJvhyQlOISCrl/rXuzbhw  40: </ds:SignatureValue>

The value of <SignatureValue> is computed as follows:

1. For each data object being signed, apply the transforms specified in <Transforms>, compute the digest using the digest algorithm, and construct a <Reference> element with the appropriate information.

2. Create a <SignedInfo> element and the correct <SignatureMethod> and <CanonicalizationMethod> elements. Include the <Reference> elements generated in step 1.

3. Use the canonicalization method specified in <CanonicalizationMethod> to canonicalize the <SignedInfo> element.

4. Use the algorithm specified in <SignatureMethod> to compute a signature value.

5. Obtain the content of <SignatureValue> by base64-encoding the result of step 4.

There you have it. You can then combine the <SignedInfo> and <SignatureValue> elements to construct a complete <Signature> element.

The KeyInfo Element

Let’s continue on and expand the example to include some of the other elements you may see in a <Signature> element. The optional <KeyInfo> element tells how to find the public key that can be used to verify the <Signature> element. A number of possible elements can appear as the children of <KeyInfo>:

• <KeyName>—The content of <KeyName> is a text string name for the key. You must assume that the recipient will know how to use this name to find the key.

• <KeyValue>—The content of the <KeyValue> element is a single public key. The specification defines two types of children (but allows for more):

  • <DSAKeyValue>—The parameters of a DSA public key (in subelements).

  • <RSAKeyValue>—The fields of an RSA public key (in subelements).

• <RetrievalMethod>—Retrieve the KeyInfo via a URI and optionally apply a set of <Transforms> to it. The optional Type attribute specifies the type of data being retrieved.

• <X509Data>—Specify that the key information is to be found via X509. This is done by using one or more of the following:

  • <X509IssuerSerial>—X.509 issuer distinguished name and serial number.

  • <X509SKI>—Base64-encoded value of an X.509 SubjectKeyIdentifier.

  • <X509SubjectName>—An X.509 subject distinguished name.

  • <X509Certificate>—Base64-encoded X509 certificate.

  • <X509CRL>—Base64-encoded certificate revocation list.

• <PGPData>—Data from a PGP public key. One of the following:

  • Base64-encoded PGP public key identifier followed by a base64 PGP Key Material Packet.

  • Base64-encoded PGP Key Material Packet.

• <SPKIData>—Base64-encoded SPKI canonical S-expression.

• <MgmtData>—Use of this method is not recommended.

More than one of these methods can appear as the content of <KeyInfo>:

 41: <ds:KeyInfo>  42: <ds:X509Data>  43: <ds:X509Certificate>  44: MIIC4DCCAp4CBD9RdNcwCwYHKoZIzjgEAwUAMFYxCzAJBgNVBAYTAlVTMQ4wDAYDV  45: dzEQMA4GA1UEBxMHTm93aGVyZTESMBAGA1UEChMJS2V5cyBSIFVzMREwDwYDVQQDE  46: ZTAeFw0wMzA4MzEwNDA4NTVaFw0wMzExMjkwNDA4NTVaMFYxCzAJBgNVBAYTAlVTM  47: EwVOb2hvdzEQMA4GA1UEBxMHTm93aGVyZTESMBAGA1UEChMJS2V5cyBSIFVzMREwD  48: b2huIERvZTCCAbcwggEsBgcqhkjOOAQBMIIBHwKBgQD9f1OBHXUSKVLfSpwu7OTn9  49: Hj+AtlEmaUVdQCJR+1k9jVj6v8X1ujD2y5tVbNeBO4AdNG/yZmC3a5lQpaSfn+gEe  50: t8Yb+DtX58aophUPBPuD9tPFHsMCNVQTWhaRMvZ1864rYdcq7/IiAxmd0UgBxwIVA  51: spK5gqLrhAvwWBz1AoGBAPfhoIXWmz3ey7yrXDa4V7l5lK+7+jrqgvlXTAs9B4JnU  52: cQcQgYC0SRZxI+hMKBYTt88JMozIpuE8FnqLVHyNKOCjrh4rs6Z1kW6jfwv6ITVi8  53: 8b6oUZCJqIPf4VrlnwaSi2ZegHtVJWQBTDv+z0kqA4GEAAKBgFDE4IMEhajzZWWO2  54: y81NHLZx9Rxda+UQnjyATvTrCg0dP9wTSMH3hlBXtVE0b8m+Hmq7CmoaPrTO4WpPZ  55: iQDhZMEK/a3FudKQSIlFhsaeFUGxehDHEbkhLay/hfiU7GK/IBxRLBWEwjEHZiq9O  56: SM44BAMFAAMvADAsAhQhD7rJv3laaI5wUTWIJEQMRNyPqAIUYPRYMOPy39mJgbG9o  57: </ds:X509Certificate>  58: </ds:X509Data>  59: <ds:KeyValue>  60: <ds:DSAKeyValue>  61: <ds:P>  62: /X9TgR11EilS30qcLuzk5/YRt1I870QAwx4/gLZRJmlFXUAiUftZPY1Y+r/F9bow9  63: HTRv8mZgt2uZUKWkn5/oBHsQIsJPu6nX/rfGG/g7V+fGqKYVDwT7g/bTxR7DAjVUE  64: K2HXKu/yIgMZndFIAcc=  65: </ds:P>  66: <ds:Q>l2BQjxUjC8yykrmCouuEC/BYHPU=</ds:Q>  67: <ds:G>  68: 9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJF  69: zwkyjMim4TwWeotUfI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog  70: Zl6Ae1UlZAFMO/7PSSo=  71: </ds:G>  72: <ds:Y>  73: UMTggwSFqPNlZY7agITcI0dqSDnLzU0ctnH1HF1r5RCePIBO9OsKDR0/3BNIwfeGU  74: arsKaho+tM7hak9npx7/G8AC6TmJAOFkwQr9rcW50pBIiUWGxp4VQbF6EMcRuSEtr  75: HFEsFYTCMQdmKr04Qlo=  76: </ds:Y>  77: </ds:DSAKeyValue>  78: </ds:KeyValue>  79: </ds:KeyInfo>

In the example, you have two ways to obtain the key: via the enclosed x.509 certificate or via an attached DSA public key value.

The Object Element

The <Object> element is used to attach other kinds of information to the <Signature>:

 80: <ds:Object>  81:  <Manifest xmlns="http://www.w3.org/2000/09/xmldsig#">  82:  </Manifest>

This <Object> has been used to attach an (empty) <Manifest>. A <Manifest> can contain a sequence of <Reference> elements. These <Reference>s are checked in an application-specific manner. They aren’t checked as part of the digital signature verification.

This <Object> element is used to attach a <SignatureProperties> element to the <Signature>. A <SignatureProperties> contains a sequence of <SignatureProperty> elements. The <SignatureProperty> element provides a way to provide additional information about the generation of the signature. A property has an ID that can be used to reference it. The Target attribute identifies the property via a URL, and the content of the <SignatureProperty> is the value of the property:

 83: </ds:Object>  84: <ds:Object>  85:  <SignatureProperties xmlns="http://www.w3.org/2000/09/xmldsig#">  86:   <SignatureProperty   87:    Target="http://www.sauria.com">smartcard</SignatureProperty>  88:  </SignatureProperties>  89: </ds:Object>  90: </ds:Signature>  91: </book>

Validating a Signature

To validate a <Signature>, you perform two steps: You validate each reference, and you validate the signature of the <SignedInfo> element. Here are the steps for reference validation:

1. Use the <CanonicalizationMethod> in <SignedInfo> to get the canonical form.

2. For each <Reference> in the <SignedInfo>:

   1. Retrieve the data to be digested.

   2. Perform any transforms specified in the <Transforms> element for the <Reference>.

   3. Compute the digest value using the method specified in <DigestMethod>.

   4. Compare the computed digest value with the content of <DigestValue>.

To validate the <SignedInfo> signature:

1. If the key information has been specified using <KeyInfo>, obtain the key; otherwise obtain the key some other way.

2. Use the algorithm specified in <CanonicalizationMethod> to compute the canonical form of <SignatureMethod>.

3. Use the algorithm specified in the canonical form of <SignatureMethod> to compute a signature value.

4. Compare the computed value with the content of <SignatureValue>.

This concludes our brief tour of XML Signature. We haven’t covered all the details or technical points in the XML Signature Recommendation, but this should give you a good start toward understanding how to use XML Security to work with XML Signature.

XML Encryption

The XML Encryption Recommendation describes how to encrypt data and represent the result as XML. You can use XML Encryption to encrypt XML documents, XML elements, XML element content, or any other kind of data. When you encrypt data using XML Encryption, the result is an <EncryptedData> element that’s included in an XML document, depending on what data you encrypted:

• If you encrypted an XML document or arbitrary data, then <EncryptedData> is the root element of a new XML document or becomes a child element of a document supplied by your application.

• If you encrypted an XML element, then the <EncryptedData> element replaces the element you encrypted.

• If you encrypted the content of an XML element, then the <EncryptedData> element replaces the element content you encrypted.

Just as we did with XML Signature, we’ll explain XML Encryption by walking through an example. This example has also been slightly modified in order to fit with the formatting of the book (just like the signature example). Again, let’s take the book document and encrypt the <author> element:

  1: <?xml version="1.0" encoding="UTF-8"?>   2: <book version="1.0"   3:  xmlns="http://sauria.com/schemas/apache-xml-book/book"   4:  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   5:  xsi:schemaLocation=   6:  "http://sauria.com/schemas/apache-xml-book/book   7:       http://www.sauria.com/schemas/apache-xml-book/book.xsd">   8:  <title>Professional XML Development with Apache Tools</title>

According to the XML Encryption spec, when you’re encrypting an XML element like <author>, the <EncryptedData> element replaces the element being encrypted. So here, where <author> used to be, you see <EncryptedData>. <EncryptedData> has its own namespace URI, http://www.w3.org/2001/04/xmlenc#, and you use the prefix xenc. An <EncryptedData> element contains an optional <EncryptionMethod> element, followed by an optional <ds:KeyInfo> (from the XML Signature Recommendation) element. After these two optional elements is a required <CipherData> element, followed by an optional <EncryptionProperties> element:

  9:  <xenc:EncryptedData  10:   Type="http://www.w3.org/2001/04/xmlenc#Element"   11:   xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">

The <EncryptedData> element can have some optional attributes:

• Type—Type information about the unencrypted form of the content. This is specified as a URI. The spec describes two types that must be implemented. These two types are used to discriminate between an XML element that has been encrypted and XML element content that has been encrypted:

  • Element—http://www.w3.org/2001/04/xmlenc#Element.

  • Element content—http://www.w3.org/2001/04/xmlenc#Content.

• Id—An ID-valued attribute that can be used to refer to the element.

• MimeType—The MIME media type of the data that was encrypted.

• Encoding—The encoding used by the data.

The <EncryptionMethod> element specifies the algorithm used to encrypt the data. The content of the <EncryptionMethod> element is determined by the value of the Algorithm attribute, which is a URI that specifies the particular encryption algorithm:

 12:   <xenc:EncryptionMethod  13:    Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"  14:    xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"/>

Algorithms detailed by the XML Encryption specification include:

• Triple DES—www.w3.org/2001/04/xmlenc#tripledes-cbc. Support is required.

• AES-128 (128 bit key)—www.w3.org/2001/04/xmlenc#tripledes-cbc. Support is required.

• AES-256 (256 bit key)—www.w3.org/2001/04/xmlenc#tripledes-cbc. Support is required.

• AES-192 (192 bit key)—www.w3.org/2001/04/xmlenc#tripledes-cbc. Support is optional.

An optional <ds:KeyInfo> element may come after the <Encryption> method, although one isn’t shown in this example. The XML Encryption spec defines two new child elements of <ds:KeyInfo>:

• <xenc:EncryptedKey>—Allows the message to carry an encrypted key along with it. It can have two child elements, zero or more <ReferenceList>s followed by zero or more <CarriedKeyName>s:

  • <ReferenceList>—A sequence of <DataReference> and <KeyReference> elements. These elements take a URI that refers to different data depending on whether the element is a <DataReference> or a <KeyReference>. A <DataReference> refers to an <EncryptedData> encrypted by the key represented by the enclosing <EncryptedKey>. A <KeyReference> refers to <EncryptedKey> elements that were encrypted using the key represented by the enclosing <EncryptedKey> element.

  • <CarriedKeyName>—A user-readable name for a key value that’s specified using a <ds:KeyName> element in a <ds:KeyInfo> element.

• <xenc:AgreementMethod>—Allows you to specify a Key Agreement algorithm for deriving a secret key from certain kinds of public keys. This is a topic that’s beyond the scope of this chapter. If you’re interested, you should look at the XML Encryption specification.

XML Encryption also augments the behavior of the <ds:RetrievalMethod> child of <ds:KeyInfo>. If you specify http://www.w3.org/2001/04/xmlenc#EncryptedKey as the Type attribute of the <ds:RetrievalMethod>, the an <EncryptedKey> element is retrieved.

The <CipherData> element is a required element that acts as a container for the encrypted data. The data may appear as either a <CipherValue> element or as a <CipherReference> element:

 15:   <xenc:CipherData  16:    xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">

The content of the <CipherValue> element is the base64-encoded version of the encrypted data:

 17:    <xenc:CipherValue  18:     xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">  19: gfI+hyGKdUiAvgW4n/+xmjNlVoAH8ZBLtqhlmoAe/aAsS3gtc5Tm8HOZyyRaANC  20:    </xenc:CipherValue>

If the <CipherReference> element appears, it specifies a resource that can be processed to yield the encrypted data. <CipherReference> uses a URI attribute to specify the resource to process. The content of the <CipherReference> element can be a <ds:Transforms> element to indicate that Transforms are to be applied to the referenced data. Support for <ds:Transforms> is optional.

The remainder of the document is as it was before:

 21:   </xenc:CipherData>  22:  </xenc:EncryptedData>  23:  <isbn>0-7645-4355-5</isbn>  24:  <month>December</month>  25:  <year>2003</year>  26:  <publisher>Wrox</publisher>  27:  <address>Indianapolis, Indiana</address>  28: </book>