15.2 XML Encryption Syntax

This section specifies the XML Encryption syntax. Using skeletal XML, the EncryptedData element has the following structure:

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

The syntax of XML Encryption is described in detail in the rest of this section. Applications that conform to the XML Encryption standard must implement all elements noted here unless otherwise stated. The following XML preamble, including the declaration, internal entities, and import of the XMLDSIG namespace, is part of specifying the syntax using [Schema]:

 <?xml version="1.0" encoding="utf-8"?> <!-- XML Schema context --> <!DOCTYPE schema PUBLIC "-//W3C//DTD XMLSchema 200102//EN"   "http://www.w3.org/2001/XMLSchema.dtd" [ <!ATTLIST schema   xmlns:xenc CDATA #FIXED 'http://www.w3.org/2001/04/xmlenc#'   xmlns:ds CDATA #FIXED 'http://www.w3.org/2000/09/xmldsig#' > <!ENTITY  % p"> <!ENTITY  % s"> ]> <schema xmlns='http://www.w3.org/2001/XMLSchema' version='1.0'         xmlns:ds='http://www.w3.org/2000/09/xmldsig#'         xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'         targetNamespace='http://www.w3.org/2001/04/xmlenc#'         elementFormDefault='qualified'> <import namespace='http://www.w3.org/2000/09/xmldsig#'         schemaLocation= 'http://www.w3.org/TR/2001/CR-xmldsig-core-20010419/xmldsig- core-schema.xsd' <!-- wrapped due to line length limit! --> />

The funny "p" and "s" ENTITY attributes are artifacts of the way [Schema] is specified. They stand for prefix and suffix, respectively. XML Schema uses them in constructs such as "xmlns&s;='foo'" and "<&p;foo/>". They default to "xs:" and ":xs". These attributes are set to null in the preceding code to avoid having to use "xs" or some other namespace prefix on all schema constructs.

Versioning

Unlike most encryption standards, XML Encryption does not have a version number field. Instead, XML Encryption uses the namespace [Names] for this purpose. XML Encryption currently uses the "http://www.w3.org/2001/04/xmlenc#" namespace, but a new XML Encryption version would use a new namespace.

15.2.1 The EncryptedType

EncryptedType is the abstract type from which EncryptedData and EncryptedKey are derived. Its schema follows:

 <!-- EncryptedType Schema --> <complexType name='EncryptedType' abstract='true'>   <sequence>     <element name='EncryptionMethod'              type='xenc:EncryptionMethodType'              minOccurs='0'/>     <element ref='ds:KeyInfo' minOccurs='0'/>     <element ref='xenc:CipherData'/>     <element ref='xenc:EncryptionProperties'              minOccurs='0'/>   </sequence>   <attribute name='Id' type='ID' use='optional'/>   <attribute name='Type' type='anyURI' use='optional'/>   <attribute name='MimeType' type='string' use='optional'/>   <attribute name='Encoding" type='string' use='optional'/> </complexType>

The "abstract" schema attribute means that you cannot use EncryptedType directly. Instead, you can use it only to derive other types.

The ds:KeyInfo element is optional. [XMLDSIG] contains the original definition of this element, which carries information about the key used to encrypt the CipherData. (See Chapter 13.)

CipherData is a mandatory child of EncryptedType. It contains or points to the cipher text. (See Section 15.2.2.)

EncryptionProperties can contain information concerning the encryption such as the time it was performed. (See Section 15.2.3.)

The optional Id attribute of EncryptedType provides the usual method of referencing the element within a document.

The optional Type attribute provides information about the plain text and/or its processing before encryption. If the plain text is an element or element content that EncryptedData replaces, you should provide a Type so that decryption can restore the XML. A Type could also indicate, for example, compression of plain text before encryption that would need to be decompressed after decryption to ensure its recovery.

The optional MimeType attribute gives the MIME [RFC 2045] type of the encrypted data, and the optional Encoding attribute specifies how it has been encoded. For example, MimeType could be "image/jpeg" and Encoding could be "base64". Both attributes are purely advisory, so no validation is required. Note that this information is unnecessary when the application can deduce it from the Type attribute. For example, if Type indicates that an element or element content was encrypted, then it will always be encoded in UTF-8.

EncryptionMethod is an optional element that describes the encryption algorithm applied to the cipher data. If this element is absent, the recipient must know, from the application context, the encryption algorithm. The schema for the EncryptionMethod element follows.

 <!-- EncryptionMethod schema --> <element name="EncryptionMethod"          type="xenc:EncryptionMethodType"/> <complexType name="EncryptionMethodType" mixed="true">    <sequence>       <element name='KeySize' minOccurs='0'                type='xenc:KeySizeType'/>       <element name='OAEPparams' minOccurs='0'                type='base64Binary'/>       <any namespace='##other' minOccurs='0'                                maxOccurs='unbounded'/>       <!-- (0,unbounded) elements from            (1,1) external namespace -->    </sequence>    <attribute name="Algorithm"               type="anyURI" use="required"/> </complexType>

Which child elements to EncryptionMethod are allowed or required depends on the specific Algorithm attribute value; however, KeySize is always permitted. ([Schema] does not provide a facility for expressing child element allowability based on attribute values.) The presence of any child element under EncryptionMethod that the algorithm does not permit, or the presence of a KeySize child that is inconsistent with the algorithm, must be treated as an error.

Table 15-1 lists some types, the first two of which must be supported.

Table 15-1. Plain Text Types
Name	Attribute Value
Element	Type='http://www.w3.org/2001/04/xmlenc#Element'
Content	Type='http://www.w3.org/2001/04/xmlenc#Content'
Media Type^[1]	MimeType='/'

^[1] Media Type is intended to be a MIME type[RFC2045]. Implementation of all such types occurs through simple octet stream encryption.

15.2.2 The CipherData Element

The CipherData element is a mandatory child of the EncryptedData and EncryptedKey elements. It provides the encrypted data by either containing or pointing to it via a CipherValue or CipherReference child, respectively. CipherValue provides a base-64 [RFC 2045] encoded octet sequence of cipher text. CipherReference provides a reference to an external location containing cipher text information.

The schema for CipherData follows:

 <!-- CipherData Schema --> <element name='CipherData'          type='xenc:CipherDataType'/> <complexType name='CipherDataType'>   <sequence>     <choice>       <element name='CipherValue'                type='ds:CryptoBinary'/>       <element ref='xenc:CipherReference'/>     </choice>   </sequence> </complexType>

The CipherReference Element

If you do not supply a CipherValue element, a CipherReference element identifies a source that, when processed, yields the cipher text octet sequence.

You obtain the actual value as follows: The CipherReference URI is dereferenced. If the CipherReference element contains a sequence of Transforms, the data resulting from the dereferenced URI is transformed to yield the intended cipher value. For example, if the value is encoded in base-64 within an XML document, the Transforms could specify an XPath expression to extract the base-64 text followed by a base-64 decoding.

The syntax of the URI and Transforms resembles that used for [XMLDSIG] reference validation. Signature and encryption processing do differ, however. In [XMLDSIG], both generation and validation processing start with the same source data and perform any Transforms in the same order. In encryption, the decrypter has only the cipher data. The specified Transforms are enumerated for the decrypter, in the order necessary to obtain the cipher text octets. The encrypter generally performed these steps in the reverse order. For this reason, the CipherReference Transforms element appears in the XML Encryption namespace.

While you follow different steps to create an EncryptedData element, for example, than to create a Signature element, a Transforms element need not exist during the preparation of such elements. Transforms must exist only for the receiver to use as a list of steps to perform in the appropriate order. Putting the CipherReference and Reference Transforms in different namespaces can prove confusing, particularly given that XML Encryption also uses the XMLDSIG namespace Transforms in the ReferenceList element and that in all cases the Transform element resides in the XMLDSIG namespace.

For example, if the relevant cipher value is captured within a CipherValue element in a different XML document, the CipherReference might look as follows:

 <CipherReference  URI="http://www.example.com/CipherValues.xml">   <Transforms>     <ds:Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">       <ds:XPath xmlns:rep="&repository;">         self::text()[parent::CipherValue[@]]       </XPath>     </Transform>     <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#base64"/>   </Transforms> </CipherReference>

XML Encryption implementations must include the CipherReference feature and the same URI encoding, dereferencing, scheme, and HTTP response codes as are required of XMLDSIG implementations. Implementation of the Transforms feature is optional. The schema definition for CipherReference follows:

 <!--CipherReference Schema--> <element name='CipherReference'          type='xenc:CipherReferenceType'/> <complexType name='CipherReferenceType'>   <choice>     <element name='Transforms' minOccurs='0'/>   </choice>   <attribute name='URI' type='anyURI' use='required'/> </complexType> <complexType name="TransformsType">   <sequence>     <element ref="ds:Transform"              maxOccurs="unbounded"/>   </sequence> </complexType>

15.2.3 The EncryptionProperties Element

 EncryptionProperties Identifier:     http://www.w3.org/2001/04/xmlenc#EncryptionProperties

You can use the preceding identifier within a ds:Reference element to identify the referent's type.

You can place additional information concerning the generation of an EncryptedData or EncryptedKey in the optional EncryptionProperties element. For example, this information could include a date/time stamp created when encryption occurred or the serial number of cryptographic hardware in use during encryption. The Target attribute identifies the EncryptedData or EncryptedKey structure being augmented.

 <!-- EncryptionProperties Schema --> <element name='EncryptionProperties'          type='xenc:EncryptionPropertiesType'/> <complexType name='EncryptionPropertiesType'>   <sequence>     <element ref='xenc:EncryptionProperty'              maxOccurs='unbounded'/>   </sequence>   <attribute name='Id' type='ID' use='optional'/> </complexType> <element name='EncryptionProperty'          type='xenc:EncryptionPropertyType'/> <complexType name='EncryptionPropertyType' mixed='true'>   <choice maxOccurs='unbounded'>     <any namespace='##other' processContents='lax'/>   </choice>   <attribute name='Target' type='anyURI' use='optional'/>   <attribute name='Id' type='ID' use='optional'/>   <anyAttribute    namespace="http://www.w3.org/XML/1998/namespace"/> </complexType>

The anyAttribute element in the schema permits inclusion of any attribute or attributes in the XML namespace, such as xml:space, xml:lang, or xml:base.

15.2.4 The EncryptedData Element

The EncryptedData element is the core element of the syntax. Not only does its CipherData child contain the encrypted data, but this element also replaces the encrypted element or serves as the new document root. Its syntax follows:

 <!-- EncryptedData schema --> <element name='EncryptedData'          type='xenc:EncryptedDataType'/> <complexType name='EncryptedDataType'>   <complexContent>     <extension base='xenc:EncryptedType'/>   </complexContent> </complexType>

15.2.5 The EncryptedKey Element

 Identifier:     http://www.w3.org/2001/04/xmlenc#EncryptedKey

You can use the preceding identifier with a ds:RetrievalMethod element to identify the referent's type.

You use the EncryptedKey element to transport encryption keys encrypted with a key-encrypting key from the originator to a recipient. You can use it as a stand-alone XML document, place it within an application document, or include it inside an EncryptedData element as a child of a ds:KeyInfo element. The key value is encrypted to the recipient(s). See Figure 15-3.

Figure 15-3. Typical enveloped key structure

graphics/15fig03.gif

The syntax for EncryptedKey follows:

 <!-- EncryptedKey schema --> <element name='EncryptedKey'          type='xenc:EncryptedKeyType'/> <complexType name='EncryptedKeyType'>   <complexContent>     <extension base='xenc:EncryptedType'>       <sequence>         <element ref='xenc:ReferenceList'                  minOccurs='0'/>         <element name='CarriedKeyName' type='string'                  minOccurs='0'/>       </sequence>       <attribute name='Recipient' type='string'                  use='optional'/>     </extension>   </complexContent> </complexType>

ReferenceList is an optional element containing pointers to data and keys encrypted using this key. The reference list may contain multiple references to EncryptedKey and EncryptedData elements. (See Section 15.2.6.)

CarriedKeyName is an optional element for associating a user-readable name with the key value. You can use it to reference the key using the ds:KeyName element within ds:KeyInfo. Unlike with an ID type attribute value, the same CarriedKeyName label may occur multiple times within a single document. The value of the key should remain the same in all EncryptedKey elements identified with the same CarriedKeyName label within a single XML document. Note, however, that the key may have been encrypted in different ways in different EncryptedKey elements.

Recipient is an optional attribute that contains a hint about the recipient for which this encrypted key value is intended. Its contents are application dependent.

The Type attribute inherited from EncryptedType can specify the type of the encrypted key if necessary.

Reference by the ds:RetrievalMethod Element

Using ds:RetrievalMethod with a Type of "http://www.w3.org/2001/04/xmlenc#EncryptedKey" provides a way to link to an EncryptedKey element containing the key needed to decrypt the data. The ds:RetrievalMethod with this type is always a child of the ds:KeyInfo element and may appear multiple times. If more than one instance of a ds:RetrievalMethod occurs in a ds: KeyInfo of this type, then the EncryptedKey objects must contain the same key value, possibly encrypted in different ways and/or for different recipients.

 <!--     <attribute name='Type' type='anyURI' use='optional'     fixed='http://www.w3.org/2001/04/xmlenc#EncryptedKey' /> -->

15.2.6 The ReferenceList Element

ReferenceList is an element that contains pointers from an EncryptedKey to items encrypted by that key. Its schema follows:

 <!-- ReferenceList schema --> <element name='ReferenceList'>   <complexType>     <sequence>       <element name='DataReference'                type='xenc:ReferenceType'                minOccurs='0' maxOccurs='unbounded'/>       <element name='KeyReference'                type='xenc:ReferenceType'                minOccurs='0' maxOccurs='unbounded'/>     </sequence>   </complexType> </element> <complexType name='ReferenceType'>   <sequence>     <any namespace='##other' minOccurs='0'                              maxOccurs='unbounded'/>   </sequence>   <attribute name='URI' type='anyURI' use='optional'/> </complexType>

You use DataReference elements to refer to EncryptedData elements encrypted using the key defined in the enclosing EncryptedKey element. Multiple DataReference elements can point to multiple EncryptedData elements encrypted by the same key.

You use KeyReference elements to refer to EncryptedKey objects encrypted using the key defined in the enclosing EncryptedKey element. Multiple KeyReference elements can point to multiple EncryptedKey elements encrypted by the same key.

Both types of references may include a child Transforms element to aid the recipient in retrieving the pointed-to EncryptedKey and/or EncryptedData elements. These elements could include information such as XPath Transforms, decompression Transforms, or information on how to retrieve the objects from a document storage facility. For example:

 <ReferenceList>   <DataReference URI="#invoice34">     <ds:Transforms>       <ds:Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">         <ds:XPath          xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">           self::xenc:EncryptedData[@]         </ds:XPath>       </ds:Transforms>     </ds:Transform>   </DataReference> </ReferenceList>

15.2.7 Extensions to the ds:KeyInfo Element

You can obtain the keying material that decrypting needs in three ways:

The EncryptedData or EncryptedKey element you are trying to decrypt can specify the associated keying material through a child of ds:KeyInfo. You can use all of the child elements of ds:KeyInfo specified in [XMLDSIG] along with the EncryptedKey and AgreementMethod added in [XMLENC]. (See Chapter 13.) Note the following:
1. Using the literal, unprotected ds:KeyValue to transport the encryption key is not recommended.
2. Support of ds:KeyName to refer to an EncryptedKey CarriedKeyName is recommended.
3. Support for same-document ds:RetrievalMethod is required.
4. Encryption applications must support EncryptedKey.
A detached (not inside ds:KeyInfo) EncryptedKey element can specify the EncryptedData or EncryptedKey to which its decrypted key will apply via a DataReference or KeyReference (see Section 15.2.6).
The recipient may determine the keying material for the application based on context; in this case, the transmitted XML does not have to provide the keying material.