# XML - Managing Data Exchange/XML Encryption

**Author**: Shayla S. Lee 02:38, 15 November
2005 (UTC)

## Introduction

XML encryption was developed to address two common areas not addressed
by the Transport Layer Security and Secure Socket Layer protocol
(TLS/SSL). TLS/SSL is a very secure and reliable protocol that provides
end-to-end security sessions between two parties. XML adds an extra
layer of security to TLS/SSL by encrypting part or all of the data being
exchanged and by allowing for secure sessions between more than two
parties. In other words, each party can maintain secure or insecure
sessions with any of the communicating parties, and both secure and
non-secure data can be exchanged in the same document. Furthermore, XML
encryption can handle both XML and non-XML (e.g. binary) data.

## Encryption Syntax

All XML encrypted files must start with the following XML preamble,
declaration, internal entity, and import.

`Schema Definition:`\
` `

```{=html}
<?xml version="1.0" encoding="utf-8"?>
```
` <!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 xenc '``http://www.w3.org/2001/04/xmlenc#``'>`\
`    <!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'>`{=html}\
`   ``<import namespace='http://www.w3.org/2000/09/xmldsig#'
            schemaLocation='http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-   schema.xsd'/>`{=html}

### EncryptedType Element

**EncryptedType** is the abstract type from which EncryptedData and
EncryptedKey are derived.

` Schema Definition:`\
`  ``<complexType name='EncryptedType' abstract='true'>`{=html}\
`   ``<sequence>`{=html}\
`     ``<element name='EncryptionMethod' type='xenc:EncryptionMethodType' 
               minOccurs='0'/>`{=html}\
`     ``<element ref='ds:KeyInfo' minOccurs='0'/>`{=html}\
`     ``<element ref='xenc:CipherData'/>`{=html}\
`     ``<element ref='xenc:EncryptionProperties' minOccurs='0'/>`{=html}\
`   ``</sequence>`{=html}\
`   ``<attribute name='Id' type='ID' use='optional'/>`{=html}\
`   ``<attribute name='Type' type='anyURI' use='optional'/>`{=html}\
`   ``<attribute name='MimeType' type='string' use='optional'/>`{=html}\
`   ``<attribute name='Encoding' type='anyURI' use='optional'/>`{=html}` `\
`  ``</complexType>`{=html}

**Syntax Explanation**

**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.

`<element name='EncryptionMethod' type='xenc:EncryptionMethodType' 
               minOccurs='0'/>`{=html}

**ds:KeyInfo** is an optional element 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.

`<element ref='ds:KeyInfo' minOccurs='0'/>`{=html}

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

`<element ref='xenc:CipherData'/>`{=html}

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

`<element ref='xenc:EncryptionProperties' minOccurs='0'/>`{=html}

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

`<attribute name='Id' type='ID' use='optional'/>`{=html}

**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 in
dycryption. 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.

`<attribute name='Type' type='anyURI' use='optional'/>`{=html}

**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.

`<attribute name='MimeType' type='string' use='optional'/>`{=html}

### EncryptionMethod Element

**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.

`Schema Definition:`\
` ``<complexType name='EncryptionMethodType' mixed='true'>`{=html}\
`   ``<sequence>`{=html}\
`     ``<element name='KeySize' minOccurs='0' type='xenc:KeySizeType'/>`{=html}\
`     ``<element name='OAEPparams' minOccurs='0' type='base64Binary'/>`{=html}\
`     ``<any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>`{=html}\
`   ``</sequence>`{=html}\
`   ``<attribute name='Algorithm' type='anyURI' use='required'/>`{=html}\
` ``</complexType>`{=html}

### CipherData Element

**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.

`Schema Definition:`\
` ``<element name='CipherData' type='xenc:CipherDataType'/>`{=html}\
` ``<complexType name='CipherDataType'>`{=html}\
`    ``<choice>`{=html}\
`      ``<element name='CipherValue' type='base64Binary'/>`{=html}\
`      ``<element ref='xenc:CipherReference'/>`{=html}\
`    ``</choice>`{=html}\
`  ``</complexType>`{=html}

### CipherReference Element

**CipherReference** identifies a source which, when processed, yields
the encrypted octet sequence CipherReference is used when CipherValue is
not supplied directly. 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.

`Schema Definition:`\
` ``<element name='CipherReference' type='xenc:CipherReferenceType'/>`{=html}\
`  ``<complexType name='CipherReferenceType'>`{=html}\
`      ``<sequence>`{=html}\
`        ``<element name='Transforms' type='xenc:TransformsType' minOccurs='0'/>`{=html}\
`      ``</sequence>`{=html}\
`      ``<attribute name='URI' type='anyURI' use='required'/>`{=html}\
`  ``</complexType>`{=html}

`   ``<complexType name='TransformsType'>`{=html}\
`      ``<sequence>`{=html}\
`        ``<element ref='ds:Transform' maxOccurs='unbounded'/>`{=html}` `\
`      ``</sequence>`{=html}\
`    ``</complexType>`{=html}

**Cipher Reference with Optional Tranform feature and Tranform
Algorithm:**

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

### EncryptedData Element

**EncryptedData** 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.

`Schema Definition:`\
` ``<element name='EncryptedData' type='xenc:EncryptedDataType'/>`{=html}\
` ``<complexType name='EncryptedDataType'>`{=html}\
`   ``<complexContent>`{=html}\
`    ``<extension base='xenc:EncryptedType'>`{=html}\
`    ``</extension>`{=html}\
`   ``</complexContent>`{=html}\
` ``</complexType>`{=html}

## Resources

The information above was obtained from W3C and IBM. For more
information, please visit the following links:

`http://www.w3.org/TR/2002/CR-xmlenc-core-20020802/#sec-Encryption-Syntax`\
`http://www-128.ibm.com/developerworks/xml/library/x-encrypt/`

