This document specifies syntax for keying information and encryption algorithm.
The syntax is designed based on the principle to reuse content-encryption mechanism for key-encryption, that is, not to distinguish contents and keys. The syntax assumes the following:
In addition to these, the syntax assumes that keys are represented as elements or text strings. Though the data model of information set [INFOSET] will satisfy all assumptions, the syntax does not assume any data model except satisfying them.
This section provides an overview and examples of syntax for keying information and encryption algorithm.
The information relative to encryption keys includes their locations, encrypted data' locations, encryption algorithms, and so on. Such information is contained in the EncryptionInfo element, which has the following structure (where "?" denotes zero or one occurrence):
<EncryptionInfo (Id=)?>
(EncryptionMethod)
(EncryptionPropertyList)?
(ReferenceList)?
(KeyInfo)
</EncryptionInfo>
The elements constituting this structure are used as follows:
The syntax for encrypted data is out of scope of this document, and below it is only assumed that the top element of the syntax is EncryptedData and it contains a URI attribute to hold a URI identifying an EncryptionInfo element and/or contains an Id attribute to be referenced by the EncryptionInfo element.
When an encryption key is detached from encrypted data, it may not have to be encrypted. In such case, an EncryptionInfo element for the key may be as follows. This type of EncryptionInfo element is the basis for some key management methods such as key transport and key agreement and will be recalled in later examples.
[01] <EncryptionInfo xmlns="http://www.w3.org/2000/10/xmlenc" Id="encryptionInfo23"> [02] <EncryptionMethod Algorithm="http://www.w3.org/2000/10/xmlenc#des-cbc-pkcs5padding"/> [03] <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> [04] <ds:KeyValue>MC0CFFrV...</ds:KeyValue> <!-- symmetric key value --> [05] </ds:KeyInfo> [06] </EncryptionInfo>
[01-06] The EncryptionInfo element may reference one or more encrypted data, or reversely may be referenced by them. This EncryptionInfo element is the latter because it contains the Id attribute, which is for being referenced by other objects.
[03-05] One KeyInfo element corresponds to one encryption key. The element comes from XML Signature namespace.
[04] The KeyValue element contains a single key in structured or string format. Note that when a binary formatted key being contained, it must be encoded using some encoding rule such as base64 [MIME].
When encrypting data with a symmetric key already shared with recipients, an EncryptionInfo element may be as follows:
[01] <EncryptionInfo xmlns="http://www.w3.org/2000/10/xmlenc"> [02] <EncryptionMethod Algorithm="http://www.w3.org/2000/10/xmlenc#des-cbc-pkcs5padding"/> [03] <ReferenceList> [04] <Reference URI="#encryptedData11"/> [05] </ReferenceList> [06] <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> [07] <ds:KeyName>1234</ds:KeyName> <!-- symmetric key identifier --> [08] </ds:KeyInfo> [09] </EncryptionInfo>
[01-09] This EncryptionInfo element is the element that references encrypted data because it contains a Reference element ([04]) for it.
[07] The KeyName element contains a string value that may be used by the originator to communicate a key identifier to recipients.
When encrypting data with a randomly generated symmetric key and delivering the key by key transport, an EncryptionInfo element may be as follows:
[01] <EncryptionInfo xmlns="http://www.w3.org/2000/10/xmlenc" Id="encryptionInfo23"> [02] <EncryptionMethod Algorithm="http://www.w3.org/2000/10/xmlenc#des-cbc-pkcs5padding"/> [03] <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> [04] <ds:KeyValue> [05] <EncryptedData URI="#encryptionInfo27">k0xFFH56...</EncryptedData> [06] </ds:KeyValue> [07] </ds:KeyInfo> [08] </EncryptionInfo> [09] <EncryptionInfo xmlns="http://www.w3.org/2000/10/xmlenc" Id="encryptionInfo27"> [10] <EncryptionMethod Algorithm="http://www.w3.org/2000/10/xmlenc#rsa"/> [11] <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> [12] <ds:X509Data>...</ds:X509Data> <!-- recipient's certificate --> [13] </ds:KeyInfo> [14] </EncryptionInfo>
[03-07] When using key transport, the KeyInfo element contains a symmetric key encrypted with each recipient's public key in parallel. To be concrete, the symmetric key is contained in the KeyValue element ([04-06]), and then the element's content is encrypted with a recipient's public key into an EncryptedData element ([05]). Multiple declarations about the same key but different encryptions must be grouped within a single KeyInfo element.
[05] This EncryptedData element contains the symmetric key encrypted with a recipient's public key and contains the URI attribute for referencing an EncryptionInfo element ([09-14]) containing a certificate of the public key.
The second EncryptionInfo element can be placed under the EncryptedData element. The resultant EncryptionInfo element is as follows:
[01] <EncryptionInfo xmlns="http://www.w3.org/2000/10/xmlenc" Id="encryptionInfo23"> [02] <EncryptionMethod Algorithm="http://www.w3.org/2000/10/xmlenc#des-cbc-pkcs5padding"/> [03] <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> [04] <ds:KeyValue> [05] <EncryptedData> [06] <EncryptionInfo> [07] <EncryptionMethod Algorithm="http://www.w3.org/2000/10/xmlenc#rsa"/> [08] <ds:KeyInfo> [09] <ds:X509Data>...</ds:X509Data> <!-- recipient's certificate --> [10] </ds:KeyInfo> [11] </EncryptionInfo> [12] <CipherText>k0xFFH56...</CipherText> [13] </EncryptedData> [14] </ds:KeyValue> [15] </ds:KeyInfo> [16] </EncryptionInfo>
[05-13] This EncryptedData element contains the EncryptionInfo element ([06-11]) first. The symmetric key is structured and contained in a CipherText element ([12]).
When encrypting data with a randomly generated symmetric key and delivering the symmetric key by key agreement, an EncryptionInfo element may be as follows:
[01] <EncryptionInfo xmlns="http://www.w3.org/2000/10/xmlenc" Id="encryptionInfo23"> [02] <EncryptionMethod Algorithm="http://www.w3.org/2000/10/xmlenc#des-cbc-pkcs5padding"/> [03] <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> [04] <EncryptedData URI="#encryptionInfo27" IV="d03L...">k0xFFH56...</EncryptedData> [05] </ds:KeyInfo> [06] </EncryptionInfo> [07] <EncryptionInfo xmlns="http://www.w3.org/2000/10/xmlenc" Id="encryptionInfo27"> [08] <EncryptionMethod Algorithm="http://www.w3.org/2000/10/xmlenc#des-cbc-pkcs5padding"/> [09] <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> [10] <KeyAgreement> [11] <ds:KeyInfo>...</ds:KeyInfo> <!-- originator's public key --> [12] <ds:KeyInfo>...</ds:KeyInfo> <!-- recipient's public key --> [13] </KeyAgreement> [14] </ds:KeyInfo> [15] </EncryptionInfo>
[10-13] When using key agreement, the KeyAgreement element should be contained by the KeyInfo element. The KeyAgreement element mainly contains two KeyInfo elements for originator's and recipient's public keys. The originator's public key and the recipient's private key corresponding to his public key are used to generate a pairwise symmetric key, the symmetric key is used to encrypt a randomly generated symmetric key, and the latter symmetric key is used to encrypt some data.
The meta-information includes encryption time, originator, recipients, message length, data type, expiration date, decryption policies, and so on. Because required meta-information varies according to contexts, this specification defines only an element for containing any meta-information, that is, EncryptionProperty. Applications may place their own meta-information within this element through the XML namespace facility [NS].
For example, when including encryption time as meta-information, an EncryptionInfo element may be as follows:
[01] <EncryptionInfo xmlns="http://www.w3.org/2000/10/xmlenc" Id="encryptionInfo23"> [02] <EncryptionMethod Algorithm="http://www.w3.org/2000/10/xmlenc#des-cbc-pkcs5padding"/> [03] <EncryptionPropertyList> [04] <EncryptionProperty> [05] <timestamp xmlns="http://www.ietf.org/rfcxxxx.txt"> <!-- encryption time --> [06] <date>20001027</date> [07] <time>192030</time> [08] </timestamp> [09] </EncryptionProperty> [10] </EncryptionPropertyList> [11] <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> [12] <ds:KeyName>1234</ds:KeyName> [13] </ds:KeyInfo> [14] </EncryptionInfo>
[04-09] This EncryptionProperty element contains a timestamp element defined in another namespace.
[PROP2] says that some encryption parameters such as an initialization vector (IV) should be contained in the syntax for encryption algorithm. However, the IV should be encoded into encrypted data or be contained by the syntax for it because the IV will be normally different for every encrypted data. In particular, when multiple data are encrypted with a single key and the key is referenced by all the encrypted data, the EncryptionInfo element has no way of containing multiple IVs. The syntax for encrypted data should be designed on considering this point.
This section describes the operations to be performed as part of encryption and decryption.
For each data object being encrypted:
For each EncryptedData element:
For each EncryptionInfo element:
The decryption process needs to deserialize serialized data objects. Note that if a data object is a text string, the serialized one cannot be deserialized by an XML processor. One way to avoid this issue is to hold a sign informing what kind of data object is serialized and later refer to the sign for deserialization. Another way is to regard a serialized data object as an external entity. The latter is useful because an XML processor does not have to care whether the deserialized one is an element or a text string.
This section provides detailed syntax for keying information and encryption algorithm.
The syntax is defined via XML Schema with the following preamble (where the target namespace is assumed to be http://www.w3.org/2000/10/xmlenc):
<!DOCTYPE schema PUBLIC "-//W3C//DTD XMLSCHEMA 200010//EN"
"http://www.w3.org/2000/10/XMLSchema.dtd" [
<!ATTLIST schema xmlns:xenc CDATA #FIXED "http://www.w3.org/2000/10/xmlenc">
xmlns:ds CDATA #FIXED "http://www.w3.org/2000/09/xmldsig#">
<!ENTITY xenc "http://www.w3.org/2000/10/xmlenc">
<!ENTITY dsig "http://www.w3.org/2000/09/xmldsig#">
]>
<schema xmlns="http://www.w3.org/2000/10/XMLSchema"
xmlns:xenc="&xenc;"
xmlns:ds="&dsig;"
targetNamespace="&xenc;"
elementFormDefault="qualified">
<import namespace="&dsig;"/>
The EncryptionInfo element is the root element and one EncryptionInfo element corresponds to one encryption key. The element consists of four elements: EncryptionMethod, EncryptionPropertyList, ReferenceList, and KeyInfo. The EncryptionMethod is for specifying an encryption algorithm and its parameters (if needed). The optional EncryptionPropertyList element is for containing meta-information. The optional ReferenceList element is for referencing one or more EncryptedData elements. The reference means that the referent is encrypted with the key specified in this element. The KeyInfo element comes from XML Signature [DSIG] namespace. This document reuses the element for specifying an encryption key. The EncryptionInfo element may contain an optional Id attribute that will allow it to be referenced by other objects.
<element name="EncryptionInfo">
<complexType>
<sequence>
<element ref="xenc:EncryptionMethod"/>
<element ref="xenc:EncryptionPropertyList" minOccurs="0"/>
<element ref="xenc:ReferenceList" minOccurs="0"/>
<element ref="ds:KeyInfo"/>
</sequence>
<attribute name="Id" type="ID" use="optional"/>
</complexType>
</element>
EncryptionMethod is an element that specifies an algorithm used for encryption. The algorithm identifies all cryptographic functions involved in such operations. The Algorithm attribute holds a URI identifying the algorithm.
<element name="EncryptionMethod">
<complexType>
<sequence>
<any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<attribute name="Algorithm" type="uriReference" use="required"/>
</complexType>
</element>
EncryptionProperty is an element that contains additional information items concerning encryption and decryption (e.g., encryption time, message length, data type, or decryption policies).
<element name="EncryptionPropertyList">
<complexType>
<sequence>
<element ref="xenc:EncryptionProperty" maxOccurs="unbounded"/>
</sequence>
</complexType>
</element>
<element name="EncryptionProperty">
<complexType>
<sequence>
<any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>
</element>
Reference is an element that references an EncryptedData element containing encrypted data. The EncryptedData element can be referenced using a URI or an XPath, which are held by the URI and XPath attributes, respectively. The Reference element may contain parameters relative to encrypted data such as an IV. Note that the IV should be encoded into the encrypted data or be contained by the syntax for it.
<element name="ReferenceList">
<complexType>
<sequence>
<element ref="xenc:Reference" maxOccurs="unbounded"/>
</sequence>
</complexType>
</element>
<element name="Reference">
<complexType>
<sequence>
<any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<attribute name="URI" type="uriReference" use="optional"/>
<attribute name="XPath" type="string" use="optional"/>
</complexType>
</element>
Some block cipher modes such as cipher block chaining (CBC) require IVs. The IV element contains an IV, which is always encoded using base64 [MIME]. The element may occur as child of the Reference element or wherever allowed.
<element name="IV" type="ds:CryptoBinary"/>
The KeyAgreement element is used when delivering an encryption key by key agreement. The element is expected to occur as child of the KeyInfo element. The element consists of three elements: two KeyInfos and UserKeyingMaterial. The former KeyInfo element is for specifying an originator's public key; the latter, for specifying a recipient's public key. Both elements are optional.
The UserKeyingMaterial element is for containing a user keying material (UKM). With some key agreement algorithms, an originator provides a UKM to ensure that a different key is generated each time the same two parties generate a pairwise key, and hence this element is optional. The UKM is always encoded using base64.
<element name="KeyAgreement">
<complexType>
<sequence>
<element ref="ds:KeyInfo" minOccurs="0"/> <!-- for originator -->
<element ref="ds:KeyInfo" minOccurs="0"/> <!-- for recipient -->
<element name="UserKeyingMaterial" type="ds:CryptoBinary" minOccurs="0"/>
</sequence>
</complexType>
</element>
There exist some discussions: