XML Encryption Structure

In the following sections, we walk you through the structure of XML Encryption. We work with sample XML fragments to show how these document fragments would look in encrypted XML.

EncryptedData : The Core of XML Encryption

The core data element in XML Encryption is EncryptedData . An EncryptedData element either wraps data within the XML document that is being encrypted, or it points to something that is encrypted.

If the target of what is being encrypted is within the same document, the EncryptedData element replaces the unencrypted information. This replacement can either include the element tags or just what is within an element tag (including the element's children).

If the target is a reference , then, similar to the XML Signature Reference URI, it can refer to an external non-XML file, or it can refer to all or part of an XML document.

You can also include the key for decrypting the encrypted data right in the EncryptedData element using a KeyInfo element. But if you include the key for decrypting the data right there with the encrypted data itself, why did you encrypt the data in the first place? Couldn't an attacker just take the key and decrypt the data? Yes, that would be the case if you used a symmetric key. Typically, the reason for doing this is to encrypt a shared key using the public key of the recipient, thereby gaining the speed and scalability of shared key cryptography for encryption while still maintaining the key management and trust characteristics of public key cryptography. There are specific techniques for doing this, and we describe them in more detail when we discuss the EncryptedKey and KeyInfo elements.

You can have more than one EncryptedData element in a document, which can be associated with the same encryption key or different ones. Thus, different parts of a document could be hidden from different recipients, and they could potentially see completely different views of the same document.

EncryptedData Schema

Now let's look at the XML shorthand schema for the EncryptedData element. Listing 5.5 comes directly from the XML Encryption specification.

Listing 5.5. XML Shorthand Schema for <EncryptedData>

 <EncryptedData Id? Type? MimeType? Encoding?>     <EncryptionMethod/>?     <ds:KeyInfo>       <EncryptedKey>?       <AgreementMethod>?       <ds:KeyName>?       <ds:RetrievalMethod>?       <ds:*>?     </ds:KeyInfo>?     <CipherData>       <CipherValue>?       <CipherReference URI?>?     </CipherData>     <EncryptionProperties>?  </EncryptedData> 

See the sidebar titled "Reading an XML Shorthand Schema" in Chapter 4 for information on how to read this schema.

Before we run through the EncryptedData schema, let's examine how it will show up in XML documents. In many ways, EncryptedData is simpler than XML Signature because it is more self-contained. The Signature element is about a collection of pointers that represent what is being signed. On the other hand, EncryptedData represents a single resource being encrypted; it does not contain pointers to multiple items. However, much of the strategy that is used in XML Signature is applicable to XML Encryption. An EncryptedData element could encompass an entire document or other XML structure similar to an enveloping signature. Also, an EncryptedData element could contain a pointer (not multiple pointers, though) to a detached resource that is encrypted. The pointer, a CipherReference , works just like Reference in XML Signature, including the possibility of Transforms but with no DigestMethod or DigestValue . Probably the most significant difference (and additional complexity) with XML Encryption is related to EncryptedKey , which is a way to include an encryption key (which, by the way, is almost always synonymous with shared key). We discuss this topic in depth soon.

Let's set aside the KeyInfo element for now. You already learned about KeyInfo in XML Signature, but XML Encryption adds a few twists that we will discuss in the "KeyInfo" section later in this chapter.

The core elements within EncryptedData are EncryptionMethod and CipherData . EncryptionMethod is a pointer to the algorithm used for the encryption. CipherData either wraps the encryption data itself ( CipherValue ) or contains a pointer to the encrypted information ( CipherReference URI ).

EncryptionProperties is a place to hold miscellaneous information about the encrypted data. It is similar to the SignatureProperties element discussed in the preceding chapter and in some scenarios is used along with XML Signatures.

EncryptedData has four optional attributes: Id , an optional identifier for the EncryptedData element; Type ; MimeType ; and Encoding . Type is an identifier for the type of plain text that is behind the EncryptedData element. There are two valid Type values: element , indicating that the entire element (including tags) has been encrypted, and content , which indicates that only the information within the element was encrypted (not including the outer tags). In the XML Encryption specification, Type is optional but, in practice, is always included and is critical for the decryption engine to restore the original document correctly. MimeType and Encoding are optionally used to further describe the encrypted item. For example, if the encrypted item is a Base-64 GIF image, you might see an Encoding of http://www.w3.org/2000/09/xmldsig#base64 and a MimeType of 'image/gif' .

It is important to note here that the EncryptedData structure is not secured from an integrity perspective. To secure the structure this way, you need to wrap the encrypted structure(s) in an XML Signature. This subject brings in new subtleties that we discuss near the end of the chapter.

Before we go through the different elements within EncryptedData , we need to examine the concept of EncryptedType .

EncryptedType

When you look at the schema in the preceding section, you see two elements ” EncryptedData and EncryptedKey ”that have something in common: They both encrypt something. EncryptedType is an abstraction of both of these elements that defines a common structure that both EncryptedData and EncryptedKey extend, similar to the concept of a super class in object-oriented programming languages. EncryptedType is defined in the governing schema for XML Encryption, but you will not see an instance of it in any document containing XML Encryption because it is an abstract typ e in the XML Encryption schema. The point here is that the EncryptedData and EncryptedKey elements are both EncryptedType elements through inheritance, and they share a common structure. When we discuss the elements within EncryptedData , we will also discuss the elements within EncryptedKey . We will discuss EncryptedKey further, describing why and when you use it. For now, you should keep in mind that much of what we discuss about EncryptedData applies to both elements.

EncryptionMethod

EncryptionMethod specifies the encryption algorithm used. In Chapter 3, "The Foundations of Distributed Message-Level Security," we described different encryption algorithms. This is the place where they are specified in XML Encryption. The following encryption algorithms are choices provided by the specification:

• Triple-DES ” http://www.w3.org/2001/04/xmlenc# tripledes -cbc (required)

• Advanced Encryption Standard (AES) 128-bit key ” http://www.w3.org/2001/04/xmlenc#aes128-cbc (required)

• Advanced Encryption Standard 256-bit key ” http://www.w3.org/2001/04/xmlenc#aes256-cbc (required)

• Advanced Encryption Standard 192-bit key ” http://www.w3.org/2001/04/xmlenc#aes192-cbc (optional)

As you can see, the key lengths are included in the names of these algorithms. This may not be true of all algorithms, and an optional KeySize child element may be required for some optional or future encryption algorigthms.

We discuss the EncryptedKey element and key transport further in the "EncryptedKey " section.

CipherData

The CipherData element either contains encrypted information ( CipherValue ) or a pointer (reference) to the resource being encrypted ( CipherReference ).

CipherValue

If CipherValue is used, the Base-64 “encoded encrypted information is right there inline within the element. In Web services scenarios, you usually see the encrypted information embedded in the SOAP message, as in Listing 5.6.

Listing 5.6. Example of How <CipherValue> Is Used

 <CipherData>  <CipherValue>A23B45C56</CipherValue>  </CipherData> 

CipherReference

If the encrypted information is located in a URI-addressable resource, the CipherReference element is used. This element uses a URI attribute almost exactly like the Reference URI in XML Signature. This includes a Transforms element, which contains a pipeline of Transform elements that must end with octets for the decryption algorithm to decode (just as the Reference URI and Transforms within XML Signature must end up with octets to feed the digest algorithm).

EncryptionProperties

The EncryptionProperties element has many similarities to the SignatureProperties element in XML Signature. Its purpose is to hold useful information about the encryption. The only difference is that SignatureProperties is a child of Object , whereas EncryptionProperties is directly descended from EncryptedData . There is so much similarity between the two that XML Encryption even adds a Type , for use with the XML Signature Reference element used to digitally sign EncryptionProperties . Listing 5.7 shows an example.

Listing 5.7. <EncryptedData> with <EncryptionProperties>

 <MyDoc>     <EncryptedData  Id="EncryptedData1"  xmlns:=http://www.w3.org/2001/04/xmlenc#>         <CipherData>             <CipherValue>. . .</CipherValue>         </CipherData>  <EncryptionProperties Id="EncryptedProperties1">   <EncryptionProperty Target="EncryptedData1">   <EncryptionDate>2003-02-28</EncryptionDate>   </EncryptionProperty>   </EncryptionProperties>  </EncryptedData>     <Signature>         <SignedInfo>             <Reference  URI="EncryptionProperties1" Type=http://www.w3.org/2001/04  /xmlenc#EncryptionProperties  >                 <DigestMethod . . ./>                 <DigestValue. . ./>             </Reference>         </SignedInfo>     </Signature> </MyDoc> 

This document (MyDoc) consists of an EncryptedData item and a Signature . We declared one EncryptionProperty called EncryptionDate . Notice that the Target of the EncryptionProperty points to EncryptedData1 . The Signature has one Reference that points to the EncryptionProperties element, which contains the EncryptionDate . As a reminder, this Signature is a Detached Signature (because it neither envelopes nor is enveloped by the item being signed). As you can see, the Type associated with the reference indicates that what is being signed is an EncryptionProperties block (http:///www.w3.org/2001/04/xmlenc#EncryptionProperties).

To underscore the important point made earlier, the integrity of an EncryptedData item is not ensured by the encryption mechanism. This is a little more obvious with EncryptionProperties because they are in the clear and could be modified by an intruder; therefore, the need for a digital signature might seem more obvious. It is true that if a CipherValue or CipherReference were manipulated, the results would not decrypt intelligibly (unless perhaps a non-chaining mode type cipher was used, in which case it might be possible to delete parts of the message and have other parts partially decrypt). However, changes due to data transfer errors or simply a nuisance attack can still cause problems, and because a computer often cannot know whether a decryption was successful by reading the message like a human can, automatically detecting this type of problem can be difficult. We talk more about this issue in the "Using XML Encryption and XML Signature Together" section later in this chapter, but, again, you should strongly consider signing things that you encrypt.

KeyInfo

In general, KeyInfo in XML Encryption has the same function as KeyInfo in XML Signature: to either directly provide you a key or to provide you a hint or pointer to find the key. The big difference is that KeyInfo in XML Signature was generally about providing you with a public key to verify the signature. In XML Encryption, KeyInfo is generally about providing you with an encryption key that is almost always a shared key. This difference is significant and explains why there are additions to the KeyInfo semantics introduced by XML Encryption. In XML Signature, you can put the key right into the signature without problem; a public key is public information. Obviously, it would be a bad idea to include the encryption key directly in the KeyInfo block because an attacker could just get the key and decrypt the cipher data (hence, the reason a shared key is often called a secret key ). The obvious alternative approaches would be to either

• Leave out the key ( assuming both sides already know the secret key).

• Provide a name or pointer to an encryption key (this approach is similar to the preceding item except a name or ID is associated with the key) with the knowledge that the recipient already possesses the key and can determine the correct key to use by the name or pointer provided.

• Encrypt the encryption key using public key technology so that only the holder of the private key would be able to decrypt the encryption key.

We are getting ahead of ourselves a little bit here, so let's review KeyInfo and then look specifically at EncryptedKey . KeyInfo is referenced from the XML Signature namespace and, when used in an XML Encryption context, can contain all the strategies described in the XML Signature chapter to either find a key or actually embed the key. As we just mentioned, embedding the encryption key without additional protection would be a bad idea, but using the naming or reference capabilities described in XML Signature KeyInfo is a completely legitimate strategy for referring to an encryption key because the encryption key is not included directly in the message. The most likely candidates for using this approach within an EncryptedData KeyInfo element would be

• KeyName ” A unique name for the key that would be recognized by the receiver or looked up in a directory of some sort .

• RetrievalMethod ” A URI that would point to a key for decrypting the data. This approach might be used, for example, to refer to a key elsewhere in the same document for another EncryptedData element that was encrypted under the same key.

XML Encryption extends the XML Signature KeyInfo with two new elements: EncryptedKey and AgreementMethod . EncryptedKey is required, so your XML Encryption processor must support it; AgreementMethod is optional. These elements are discussed next .

EncryptedKey

We have been giving hints along the way about EncryptedKey , so you may have already figured this out: EncryptedKey is simply another EncryptedData element that will hold an encrypted encryption key. It has the same syntax as EncryptedData because, as we mentioned earlier, they both come from the abstract type, EncryptedType . The implication is that EncryptedKey can be recursive , meaning an EncryptedKey could have its own KeyInfo / EncryptedKey , which in turn could have its own and so on.

The most obvious use for EncryptedKey is to encrypt the encryption key with the public key of a specific recipient and put it into the KeyInfo / EncryptedKey block. This process is often described as digital enveloping or a key transport strategy. The idea is to take advantage of the power of shared key technology (speed, more information can be encrypted) and the power of public key techology (primarily key management). The difficulty of using a pure shared key approach is the difficulty of communicating the secret shared key to the other party. Obviously, you cannot just include it in the clear within the XML. You could encrypt it, but if you encrypt it with another shared key, you have the same problem all over again. Ultimately, you will either

• Use a shared key strategy, which implies an agreement on the key that is not represented in the XML itself (a shared secret key). In this case, there is either no KeyInfo (the recipient knows the key) within the EncryptedKey , or there is some indicator of the key, such as KeyName , for the recipient to look up the key.

• Use a combined shared and public key strategy in which the shared symmetric key is encrypted using the public asymmetric key of the recipient. In this case, there might be no KeyInfo within the EncryptedKey , or any of the strategies for designating or providing a public key, as described in the "The KeyInfo Element" section in Chapter 4, could be used.

The simplified example in Listing 5.8 uses a public key to encrypt the shared key that is used to encrypt an EncryptedData block.

Listing 5.8. A Public Key Used to Encrypt the Shared Key That Is Then Used to Encrypt the <EncryptedData> Block

 <EncryptedData>     <EncryptionMethod Algorithm=http://www.w3.org/2001/04/xmlenc#aes128-cbc" />     <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmlsig#" />         <EncryptedKey>             <EncryptionMethod Algorithm=http://www.w3.org/2001/04/ xmlenc#rsa-1_5" />             <ds:KeyInfo xmlns:ds=http://www.w3.org/2000/09/xmlsig# />                 <ds:X509Data>                     <ds:X509SubjectName>                         o=MyCompany,ou=Engineering,cn=Dave Remy                     </ds:X509SubjectName>                 </ds:X509Data>             <ds:/KeyInfo>             <CipherData>                 <CipherValue>. . .</CipherValue>             </CipherData>         </EncryptedKey>     </ds:KeyInfo>     <CipherData>         <CipherValue>. . .</CipherValue>     </CipherData> </EncryptedData> 

This example shows XML Encryption with a shared key that is, in turn, encrypted using the recipient's public key. First, notice the two KeyInfo elements within this EncryptedData . The first KeyInfo is for the shared key that is used to decrypt the CipherValue , which is the child of EncryptedData . The second KeyInfo , which is a child of the EncryptedKey , designates the public key that was used to encrypt the shared key. To unwind this, the recipient would need to have access to the private key associated with the SubjectName ” o=MyCompany,ou=Engineering,cn=Dave Remy ”to decrypt the shared key that is encrypted in the CipherValue element (the first one). After the shared key is decrypted, it can then be used to decrypt the CipherValue that is the child of EncryptedData .

Considering that XML Encryption allows you to encrypt multiple elements (with or without tags) in an XML document, you could imagine that most or all of them might be encrypted using the same key. The EncryptedKey element has two elements to help facilitate this scenario: ReferenceList , which is discussed in the "ReferenceList" section, and CarriedKeyName , which is discussed in the "CarriedKeyName" section later.

AgreementMethod

AgreementMethod , whose support is optional in an XML Encryption engine, is another strategy for safely communicating a secret key. The AgreementMethod refers to a key agreement protocol that was used to generate the encryption key along with the key material necessary to repeat the encryption key generation on the recipient's side.

Normally, a key agreement protocol ”for example, SSL ”involves multiple synchronous steps that arrive at a session key (a limited-time-use shared encryption key); however, with XML Encryption, an asynchronous strategy is required. It is expected that the first step of the key agreement protocol ”the generation of the public key agreement material ”has already been done, and the public key agreement material of the recipient is available to the sender. The sender then uses the recipient's public key agreement material combined with the sender's private key material to generate the shared encryption key. The sender then includes her public key agreement material within the AgreementMethod / OriginatorKeyInfo element so that the recipient can then generate the same encryption key and use it to decrypt the encrypted data.

As mentioned earlier, this public key agreement material must be pregenerated and could also be signed by a certificate authority for trust reasons. Listing 5.9 shows an example from the XML Encryption specification of an AgreementMethod with agreement material that is wrapped in an X.509 certificate.

Listing 5.9. The <AgreementMethod> Element

 <AgreementMethod       Algorithm="http://www.w3.org/2001/04/xmlenc#dh"       ds:xmlns="http://www.w3.org/2000/09/xmldsig#">     <KA-Nonce>Zm9v</KA-Nonce>     <ds:DigestMethod      Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>     <OriginatorKeyInfo>       <ds:X509Data><ds:X509Certificate>         ...       </ds:X509Certificate></ds:X509Data>     </OriginatorKeyInfo>     <RecipientKeyInfo>         <ds:KeyValue>           ...         </ds:KeyValue>     </RecipientKeyInfo> </AgreementMethod> 

We will not go into any more detail on AgreementMethod and the use of key agreement protocols for creating an encryption key. It appears that there is actually a good fit for a key agreement type approach for generating encryption keys in this manner with XML Encryption; however, we have not seen this approach used with any prevalence in XML security implementations in the real world and, consequently, in Web Services Security.

Perhaps the reason is that it is optional in the XML security specification or that these types of protocols have primarily been implemented in a synchronous fashion in the past.

ReferenceList

Imagine that you want to encrypt an XML document that contains multiple EncryptedData items that have all been encrypted with the same key. Listing 5.10 shows an example (leaving out the KeyInfo element for now) of this.

Listing 5.10. Multiple <EncryptedData> Items Encrypted with the Same Key

 <Employee>     <Name>Dave Remy</Name>     <SocialSecurityNumber>  <EncryptedData Type="http://www.w3.org/2000/09/xmldsig#content">   <EncryptionMethod Algorithm=". . .">   <CipherData><CipherValue>. . .</CipherValue></CipherData>   </EncryptedData>  </SocialSecurityNumber>     <Salary>  <EncryptedData Type="http://www.w3.org/2000/09/xmldsig#content">   <EncryptionMethod Algorithm=". . .">   <CipherData><CipherValue>. . .</CipherValue></CipherData>   </EncryptedData>  </Salary> </Employee> 

Listing 5.10 has just two EncryptedData elements, SocialSecurityNumber and Salary , but it would be easy to imagine many more within the same document. Such an example could add a lot of size and redundancy to the XML document if you had to add the same KeyInfo block for each of the encrypted data items. The ReferenceList element (along with CarriedKeyName , as you will see) is a strategy for dealing with this situation. Let's expand the previous example using ReferenceList in Listing 5.11.

Listing 5.11. Expanded <Employee> Element Now Using the <ReferenceList> Element for Dealing Efficiently with Multiple <EncryptedData> Elements

 <Employee>     <Name>Dave Remy</Name>     <SocialSecurityNumber>  <EncryptedData id="socsecnum" Type="http://www.w3.org/2000/09/   xmldsig#content">   <EncryptionMethod Algorithm=". . ." />   <CipherData><CipherValue>. . .</CipherValue></CipherData>   </EncryptedData>  </SocialSecurityNumber>     <Salary>  <EncryptedData id="salary" Type="http://www.w3.org/2000/09/   xmldsig#content">   <EncryptionMethod Algorithm=". . .">   <CipherData><CipherValue>. . .</CipherValue></CipherData>   </EncryptedData>  </Salary>     <EncryptedKey>         <EncryptionMethod Algorithm=". . ." />         <CipherData>             <CipherValue>. . .</CipherValue>         </CipherData>  <ReferenceList>   <DataReference URI="#socsecnum" />   <DataReference URI="#salary" />   </ReferenceList>  </EncryptedKey> </Employee> 

Notice that, rather than including a separate KeyInfo / EncryptedKey for each EncryptedData , we created a standalone EncryptedKey with a ReferenceList to each of the EncryptedData items that had been encrypted with the key.

ReferenceList can contain a list of DataReference elements and/or KeyReference elements. If a KeyReference is used, the target of the reference is an EncryptedKey rather than an EncryptedData element. This approach would be valuable when using a key that was used to encrypt a set of keys such as a master encryption key .

When we discuss WS-Security in Chapter 7, you will see that ReferenceList is a fundamental concept for referring to the parts of the message that are encrypted when XML Encryption is used in a SOAP header.

CarriedKeyName

ReferenceList provides a mechanism for referring to all the EncryptedData elements from a single EncryptedKey element; however, in every other circumstance we have talked about, the EncryptedData element has a reference to the key using KeyInfo . The CarriedKeyName element provides the EncryptedKey with a name, so the KeyInfo can point to it using KeyName . Listing 5.12 shows the preceding example with the addition of a CarriedKeyName element to identify the EncryptedKey structure.

Listing 5.12. Previous Example with <CarriedKeyName> Added to Identify the <EncryptedKey> Structure

 <Employee>     <Name>Dave Remy</Name>     <SocialSecurityNumber>         <EncryptedData id="socsecnum" Type="http://www.w3.org/2000/09/ xmldsig#content">  <KeyInfo>   <KeyName>Jothy Rosenberg</KeyName>   </KeyInfo>  <EncryptionMethod Algorithm=". . ." />             <CipherData><CipherValue>. . .</CipherValue></CipherData>         </EncryptedData>     </SocialSecurityNumber>     <Salary>         <EncryptedData id="salary" Type="http://www.w3.org/2000/09/ xmldsig#content">             <EncryptionMethod Algorithm=". . .">             <CipherData><CipherValue>. . .</CipherValue></CipherData>         </EncryptedData>     </Salary>     <EncryptedKey>         <EncryptionMethod Algorithm=". . ." />         <CipherData>             <CipherValue>. . .</CipherValue>         </CipherData>         <ReferenceList>             <DataReference URI="#socsecnum" />             <DataReference URI="#salary" />         </ReferenceList>  <CarriedKeyName>Jothy Rosenberg</CarriedKeyName>  </EncryptedKey> </Employee> 

As you can see in this example, when you add a CarriedKeyName element to the EncryptedKey , you can then refer to it using the KeyInfo KeyName element. The advantage here is that an XML Encryption processor (or a reader, for that matter) can navigate from either the EncryptedData element itself or from the ReferenceList .

Super Encryption

It is entirely possible for an EncryptedData element to encrypt other EncryptedData elements. This type of encryption, which can occur an unlimited number of times, is called super encryption . The only limitation here is that you have to encrypt the entire EncryptedData element; you cannot just encrypt one of its children. If you have a document with multiple encryptions in it, perhaps with multiple recipients involved, you might want to encrypt the entire document under one EncryptedData element. Doing this is fine. The receiving XML Encryption process repeatedly decrypts until no more EncryptedData elements are left to decrypt.