XML Encryption Syntax and Processing

This document specifies a process for encrypting data and representing the result in XML. The data may be arbitrary data (including an XML document), an XML element, or XML element content. The result of encrypting data is an XML Encryption element which contains or references the cipher data.

This document is the W3C XML Encryption Recommendation (REC). This document has been reviewed by W3C Members and other interested parties and has been endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited as a normative reference from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

This specification was produced by the W3C XML Encryption Working Group (Activity) which believes the specification is sufficient for the creation of independent interoperable implementations as demonstrated in the Interoperability Report.

Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page in conformance with W3C policy.

Please report errors in this document to xml-encryption@w3.org (public archive).

The list of known errors in this specification is available at http://www.w3.org/Encryption/2002/12-xmlenc-errata.

The English version of this specification is the only normative version. Information about translations of this document (if any) is available http://www.w3.org/Encryption/2002/12-xmlenc-translations.

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR/.

This document specifies a process for encrypting data and representing the result in XML. The data may be arbitrary data (including an XML document), an XML element, or XML element content. The result of encrypting data is an XML Encryption EncryptedData element which contains (via one of its children's content) or identifies (via a URI reference) the cipher data.

When encrypting an XML element or element content the EncryptedData element replaces the element or content (respectively) in the encrypted version of the XML document.

When encrypting arbitrary data (including entire XML documents), the EncryptedData element may become the root of a new XML document or become a child element in an application-chosen XML document.

This specification uses XML schemas [XML-schema] to describe the content model.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in RFC2119 [KEYWORDS]:

"they MUST only be used where it is actually required for interoperation or to limit behavior which has potential for causing harm (e.g., limiting retransmissions)"

Consequently, we use these capitalized keywords to unambiguously specify requirements over protocol and application features and behavior that affect the interoperability and security of implementations. These key words are not used (capitalized) to describe XML grammar; schema definitions unambiguously describe such requirements and we wish to reserve the prominence of these terms for the natural language descriptions of protocols and features. For instance, an XML attribute might be described as being "optional." Compliance with the XML-namespace specification [XML-NS] is described as "REQUIRED."

The design philosophy and requirements of this specification (including the limitations related to instance validity) are addressed in the XML Encryption Requirements [EncReq].

No provision is made for an explicit version number in this syntax. If a future version is needed, it will use a different namespace. The experimental XML namespace [XML-NS] URI that MUST be used by implementations of this (dated) specification is:

This namespace is also used as the prefix for algorithm identifiers used by this specification. While applications MUST support XML and XML namespaces, the use of internal entities [XML, section 4.2.1], the "xenc" XML namespace prefix [XML-NS, section 2] and defaulting/scoping conventions are OPTIONAL; we use these facilities to provide compact and readable examples. Additionally, the entity &xenc; is defined so as to provide short-hand identifiers for URIs defined in this specification. For example "&xenc;Element" corresponds to "http://www.w3.org/2001/04/xmlenc#Element".

This specification makes use of the XML Signature [XML-DSIG] namespace and schema definitions

URIs [URI] MUST abide by the [XML-Schema] anyURI type definition and the [XML-DSIG, 4.3.3.1 The URI Attribute] specification (i.e., permitted characters, character escaping, scheme support, etc.).

The contributions of the following Working Group members to this specification are gratefully acknowledged in accordance with the contributor policies and the active WG roster.

Additionally, we thank the following for their comments during and subsequent to Last Call:

This section provides an overview and examples of XML Encryption syntax. The formal syntax is found in Encryption Syntax (section 3); the specific processing is given in Processing Rules (section 4).

Expressed in shorthand form, the EncryptedData element has the following structure (where "?" denotes zero or one occurrence; "+" denotes one or more occurrences; "*" denotes zero or more occurrences; and the empty element tag means the element must be empty ):

The CipherData element envelopes or references the raw encrypted data. If enveloping, the raw encrypted data is the CipherValue element's content; if referencing, the CipherReference element's URI attribute points to the location of the raw encrypted data

Consider the following fictitious payment information, which includes identification information and information appropriate to a payment method (e.g., credit card, money transfer, or electronic check):

This markup represents that John Smith is using his credit card with a limit of $5,000USD.

Smith's credit card number is sensitive information! If the application wishes to keep that information confidential, it can encrypt the CreditCard element:

By encrypting the entire CreditCard element from its start to end tags, the identity of the element itself is hidden. (An eavesdropper doesn't know whether he used a credit card or money transfer.) The CipherData element contains the encrypted serialization of the CreditCard element.

As an alternative scenario, it may be useful for intermediate agents to know that John used a credit card with a particular limit, but not the card's number, issuer, and expiration date. In this case, the content (character data or children elements) of the CreditCard element is encrypted:

Or, consider the scenario in which all the information except the actual credit card number can be in the clear, including the fact that the Number element exists:

Both CreditCard and Number are in the clear, but the character data content of Number is encrypted.

If the application scenario requires all of the information to be encrypted, the whole document is encrypted as an octet sequence. This applies to arbitrary data including XML documents.

An XML document may contain zero or more EncryptedData elements. EncryptedData cannot be the parent or child of another EncryptedData element. However, the actual data encrypted can be anything, including EncryptedData and EncryptedKey elements (i.e., super-encryption). During super-encryption of an EncryptedData or EncryptedKey element, one must encrypt the entire element. Encrypting only the content of these elements, or encrypting selected child elements is an invalid instance under the provided schema. For example, consider the following:

A valid super-encryption of "//xenc:EncryptedData[@Id='ED1']" would be:

where the CipherValue content of 'newEncryptedData' is the base64 encoding of the encrypted octet sequence resulting from encrypting the EncryptedData element with Id='ED1'.

[s1] The type of data encrypted may be represented as an attribute value to aid in decryption and subsequent processing. In this case, the data encrypted was an 'element'. Other alternatives include 'content' of an element, or an external octet sequence which can also be identified via the MimeType and Encoding attributes.

[s2] This (3DES CBC) is a symmetric key cipher.

[s4] The symmetric key has an associated name "John Smith".

[s6] CipherData contains a CipherValue, which is a base64 encoded octet sequence. Alternately, it could contain a CipherReference, which is a URI reference along with transforms necessary to obtain the encrypted data as an octet sequence

The following EncryptedData structure is very similar to the one above, except this time the key is referenced using a ds:RetrievalMethod:

[t02] This (AES-128-CBC) is a symmetric key cipher.

[t04] ds:RetrievalMethod is used to indicate the location of a key with type &xenc;EncryptedKey. The (AES) key is located at '#EK'.

[t05] ds:KeyName provides an alternative method of identifying the key needed to decrypt the CipherData. Either or both the ds:KeyName and ds:KeyRetrievalMethod could be used to identify the same key.

Within the same XML document, there existed an EncryptedKey structure that was referenced within [t04]:

[t09] The EncryptedKey element is similar to the EncryptedData element except that the data encrypted is always a key value.

[t10] The EncryptionMethod is the RSA public key algorithm.

[t12] ds:KeyName of "John Smith" is a property of the key necessary for decrypting (using RSA) the CipherData.

[t14] The CipherData's CipherValue is an octet sequence that is processed (serialized, encrypted, and encoded) by a referring encrypted object's EncryptionMethod. (Note, an EncryptedKey's EncryptionMethod is the algorithm used to encrypt these octets and does not speak about what type of octets they are.)

[t15-17] A ReferenceList identifies the encrypted objects (DataReference and KeyReference) encrypted with this key. The ReferenceList contains a list of references to data encrypted by the symmetric key carried within this structure.

[t18] The CarriedKeyName element is used to identify the encrypted key value which may be referenced by the KeyName element in ds:KeyInfo. (Since ID attribute values must be unique to a document,CarriedKeyName can indicate that several EncryptedKey structures contain the same key value encrypted for different recipients.)

This section provides a detailed description of the syntax and features for XML Encryption. Features described in this section MUST be implemented unless otherwise noted. The syntax is defined via [XML-Schema] with the following XML preamble, declaration, internal entity, and import:

EncryptedType is the abstract type from which EncryptedData and EncryptedKey are derived. While these two latter element types are very similar with respect to their content models, a syntactical distinction is useful to processing. Implementation MUST generate laxly schema valid [XML-schema] EncryptedData or EncryptedKey as specified by the subsequent schema declarations. (Note the laxly schema valid generation means that the content permitted by xsd:ANY need not be valid.) Implementations SHOULD create these XML structures (EncryptedType elements and their descendents/content) in Normalization Form C [NFC, NFC-Corrigendum].

EncryptionMethod is an optional element that describes the encryption algorithm applied to the cipher data. If the element is absent, the encryption algorithm must be known by the recipient or the decryption will fail.

ds:KeyInfo is an optional element, defined by [XML-DSIG], that carries information about the key used to encrypt the data. Subsequent sections of this specification define new elements that may appear as children of ds:KeyInfo.

CipherData is a mandatory element that contains the CipherValue or CipherReference with the encrypted data.

EncryptionProperties can contain additional information concerning the generation of the EncryptedType (e.g., date/time stamp).

Id is an optional attribute providing for the standard method of assigning a string id to the element within the document context.

Type is an optional attribute identifying type information about the plaintext form of the encrypted content. While optional, this specification takes advantage of it for mandatory processing described in Processing Rules: Decryption (section 4.2). If the EncryptedData element contains data of Type 'element' or element 'content', and replaces that data in an XML document context, it is strongly recommended the Type attribute be provided. Without this information, the decryptor will be unable to automatically restore the XML document to its original cleartext form.

MimeType is an optional (advisory) attribute which describes the media type of the data which has been encrypted. The value of this attribute is a string with values defined by [MIME]. For example, if the data that is encrypted is a base64 encoded PNG, the transfer Encoding may be specified as 'http://www.w3.org/2000/09/xmldsig#base64' and the MimeType as 'image/png'. This attribute is purely advisory; no validation of the MimeType information is required and it does not indicate the encryption application must do any additional processing. Note, this information may not be necessary if it is already bound to the identifier in the Type attribute. For example, the Element and Content types defined in this specification are always UTF-8 encoded text.

EncryptionMethod is an optional element that describes the encryption algorithm applied to the cipher data. If the element is absent, the encryption algorithm must be known by the recipient or the decryption will fail.

The permitted child elements of the EncryptionMethod are determined by the specific value of the Algorithm attribute URI, and the KeySize child element is always permitted. For example, the RSA-OAEP algorithm (section 5.4.2) uses the ds:DigestMethod and OAEPparams elements. (We rely upon the ANY schema construct because it is not possible to specify element content based on the value of an attribute.)

The presence of any child element under EncryptionMethod which is not permitted by the algorithm or the presence of a KeySize child inconsistent with the algorithm MUST be treated as an error. (All algorithm URIs specified in this document imply a key size but this is not true in general. Most popular stream cipher algorithms take variable size keys.)

The CipherData is a mandatory element that provides the encrypted data. It must either contain the encrypted octet sequence as base64 encoded text of the CipherValue element, or provide a reference to an external location containing the encrypted octet sequence via the CipherReference element.

If CipherValue is not supplied directly, the CipherReference identifies a source which, when processed, yields the encrypted octet sequence.

The actual value is obtained as follows. The CipherReference URI contains an identifier that is dereferenced. Should the CipherReference element contain an OPTIONAL sequence of Transforms, the data resulting from dereferencing the URI is transformed as specified so as to yield the intended cipher value. For example, if the value is base64 encoded within an XML document; the transforms could specify an XPath expression followed by a base64 decoding so as to extract the octets.

The syntax of the URI and Transforms is similar to that of [XML-DSIG]. However, there is a difference between signature and encryption processing. In [XML-DSIG] both generation and validation processing start with the same source data and perform that transform in the same order. In encryption, the decryptor has only the cipher data and the specified transforms are enumerated for the decryptor, in the order necessary to obtain the octets. Consequently, because it has different semantics Transforms is in the &xenc; namespace.

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

Implementations MUST support the CipherReference feature and the same URI encoding, dereferencing, scheme, and HTTP response codes as that of [XML-DSIG]. The Transform feature and particular transform algorithms are OPTIONAL.

The EncryptedData element is the core element in the syntax. Not only does its CipherData child contain the encrypted data, but it's also the element that replaces the encrypted element, or serves as the new document root.

There are three ways that the keying material needed to decrypt CipherData can be provided:

In addition, we provide two additional child elements: applications MUST support EncryptedKey (section 3.5.1) and MAY support AgreementMethod (section 5.5).

(This can be used within a ds:RetrievalMethod element to identify the referent's type.)

The EncryptedKey element is used to transport encryption keys from the originator to a known recipient(s). It may be used as a stand-alone XML document, be placed within an application document, or appear inside an EncryptedData element as a child of a ds:KeyInfo element. The key value is always encrypted to the recipient(s). When EncryptedKey is decrypted the resulting octets are made available to the EncryptionMethod algorithm without any additional processing.

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. This is done using KeyReference and DataReference elements respectively. These are defined below.

CarriedKeyName is an optional element for associating a user readable name with the key value. This may then be used to reference the key using the ds:KeyName element within ds:KeyInfo. The same CarriedKeyName label, unlike an ID type, may occur multiple times within a single document. The value of the key is to be the same in all EncryptedKey elements identified with the same CarriedKeyName label within a single XML document. Note that because whitespace is significant in the value of the ds:KeyName element, whitespace is also significant in the value of the CarriedKeyName element.

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

The Type attribute inheritted from EncryptedType can be used to further specify the type of the encrypted key if the EncryptionMethod Algorithm does not define a unambiguous encoding/representation. (Note, all the algorithms in this specification have an unambigous representation for their associated key structures.)

The ds:RetrievalMethod [XML-DSIG]with a Type of 'http://www.w3.org/2001/04/xmlenc#EncryptedKey' provides a way to express a link to an EncryptedKey element containing the key needed to decrypt the CipherData associated with an EncryptedData or EncryptedKey element. The ds:RetrievalMethod with this type is always a child of the ds:KeyInfo element and may appear multiple times. If there is more than one instance of a ds:RetrievalMethod in a ds:KeyInfo of this type, then the EncryptedKey objects referred to must contain the same key value, possibly encrypted in different ways or for different recipients.

ReferenceList is an element that contains pointers from a key value of an EncryptedKey to items encrypted by that key value (EncryptedData or EncryptedKey elements).

DataReference elements are used to refer to EncryptedData elements that were encrypted using the key defined in the enclosing EncryptedKey element. Multiple DataReference elements can occur if multiple EncryptedData elements exist that are encrypted by the same key.

KeyReference elements are used to refer to EncryptedKey elements that were encrypted using the key defined in the enclosing EncryptedKey element. Multiple KeyReference elements can occur if multiple EncryptedKey elements exist that are encrypted by the same key.

For both types of references one may optionally specify child elements to aid the recipient in retrieving the EncryptedKey and/or EncryptedData elements. These could include information such as XPath transforms, decompression transforms, or information on how to retrieve the elements from a document storage facility. For example:

(This can be used within a ds:Reference element to identify the referent's type.)

Additional information items concerning the generation of the EncryptedData or EncryptedKey can be placed in an EncryptionProperty element (e.g., date/time stamp or the serial number of cryptographic hardware used during encryption). The Target attribute identifies the EncryptedType structure being described. anyAttribute permits the inclusion of attributes from the XML namespace to be included (i.e., xml:space, xml:lang, and xml:base).

This section describes the operations to be performed as part of encryption and decryption processing by implementations of this specification. The conformance requirements are specified over the following roles:

For each data item to be encrypted as an EncryptedData or EncryptedKey (elements derived from EncryptedType), the encryptor must:

The definition of this type as bound to an identifier specifies how to obtain and interpret the plaintext octets after decryption. For example, the idenifier could indicate that the data is an instance of another application (e.g., some XML compression application) that must be further processed. Or, if the data is a simple octet sequence it MAY be described with the MimeType and Encoding attributes. For example, the data might be an XML document (MimeType="text/xml"), sequence of characters (MimeType="text/plain"), or binary image data (MimeType="image/png").

An EncryptedType structure represents all of the information previously discussed including the type of the encrypted data, encryption algorithm, parameters, key, type of the encrypted data, etc.

The encryptor SHOULD be able to replace the unencrypted 'element' or 'content' with the EncryptedData element. When an application requires an XML element or content to be replaced, it supplies the XML document context in addition to identifying the element or content to be replaced. The encryptor removes the identified element or content and inserts the EncryptedData element in its place.

(Note: If the Type is "content" the document resulting from decryption will not be well-formed if (a) the original plaintext was not well-formed (e.g., PCDATA by itself is not well-formed) and (b) the EncryptedData element was previously the root element of the document)

For each EncryptedType derived element, (i.e., EncryptedData or EncryptedKey), to be decrypted, the decryptor must:

The application supplies the XML document context and identifies the EncryptedData element being replaced. If the document into which the replacement is occurring is not UTF-8, the decryptor MUST transcode the UTF-8 encoded characters into the target encoding.

Encryption and decryption operations are transforms on octets. The application is responsible for the marshalling XML such that it can be serialized into an octet sequence, encrypted, decrypted, and be of use to the recipient.

For example, if the application wishes to canonicalize its data or encode/compress the data in an XML packaging format, the application needs to marshal the XML accordingly and identify the resulting type via the EncryptedData Type attribute. The likelihood of successful decryption and subsequent processing will be dependent on the recipient's support for the given type. Also, if the data is intended to be processed both before encryption and after decryption (e.g., XML Signature [XML-DSIG] validation or an XSLT transform) the encrypting application must be careful to preserve information necessary for that process's success.

For interoperability purposes, the following types MUST be implemented such that an implementation will be able to take as input and yield as output data matching the production rules 39 and 43 from [XML]:

The following sections contain specifications for decrypting, replacing, and serializing XML content (i.e., Type 'element' or element 'content') using the [XPath] data model. These sections are non-normative and OPTIONAL to implementors of this specification, but they may be normatively referenced by and MANDATORY to other specifications that require a consistent processing for applications, such as [XML-DSIG-Decrypt].

Where P is the context in which the serialized XML should be parsed (a document node or element node) and O is the octet sequence representing UTF-8 encoded characters resulting from step 4.3 in the Decryption Processing (section 4.2). Y is node-set representing the decrypted content obtained by the following steps:

Where X is the [XPath] node set corresponding to an XML document and e is an EncryptedData element node in X.

In Encrypting XML (section 4.1, step 3.1), when serializing an XML fragment special care SHOULD be taken with respect to default namespaces. If the data will be subsequently decrypted in the context of a parent XML document then serialization can produce elements in the wrong namespace. Consider the following fragment of XML:

Read more here:
XML Encryption Syntax and Processing