This section discusses algorithms used with the XML encryption specification. Entries contain the identifier to be used as the value of the Algorithm attribute of the EncryptionMethod element or other elements representing the role of the algorithm, a reference to the formal specification and definitions, where applicable, for the representation of keys and the results of cryptographic operations.
All algorithms listed below have implicit parameters depending on their role. For example, the data to be encrypted or decrypted, keying material, and direction of operation (encrypting or decrypting) for encryption algorithms. Any explicit additional parameters to an algorithm appear as content elements within the element. Such parameter child elements have descriptive element names, which are frequently algorithm specific, and MUST be in the same namespace as this XML Encryption specification, the XML Signature specification, or in an algorithm specific namespace. An example of such an explicit parameter could be a nonce (unique random quantity) provided to a key agreement algorithm.
This specification defines a set of algorithms, their URIs, and requirements for implementation. Requirements are specified over implementation, not over requirements for encryption use. Furthermore, the mechanism is extensible, alternative algorithms may be used by encryption applications.
The table below lists the categories of algorithms. Within each category, a brief name, the level of implementation requirement, and a URI are given.
| Algorithm Type | Algorithm | Requirements |
|---|---|---|
| Algorithm URI | ||
| Block Encryption | ||
| 3DES | REQUIRED | |
| http://www.w3.org/2001/04/xmlenc#3des-cbc | ||
| AES 128 | REQUIRED | |
| http://www.w3.org/2001/04/xmlenc#aes128-cbc | ||
| AES 256 | REQUIRED | |
| http://www.w3.org/2001/04/xmlenc#aes256-cbc | ||
| AES 192 | OPTIONAL | |
| http://www.w3.org/2001/04/xmlenc#aes192-cbc | ||
| Stream Encryption | ||
| ARCFOUR | OPTIONAL | |
| http://www.w3.org/2001/04/xmlenc#arcfour | ||
| Key Transport | ||
| RSA-v1.5 | REQUIRED | |
| http://www.w3.org/2001/04/xmlenc#rsa-1_5 | ||
| RSA-OAEP | REQUIRED | |
| http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p | ||
| Key Agreement | ||
| Diffie-Hellman | OPTIONAL | |
| http://www.w3.org/2001/04/xmlenc#dh | ||
| Symmetric Key Wrap | ||
| 3DES KeyWrap | REQUIRED | |
| http://www.w3.org/2001/04/xmlenc#kw-3des | ||
| AES 128 KeyWrap | REQUIRED | |
| http://www.w3.org/2001/04/xmlenc#kw-aes128 | ||
| AES 256 KeyWrap | REQUIRED | |
| http://www.w3.org/2001/04/xmlenc#kw-aes256 | ||
| AES 192 KeyWrap | OPTIONAL | |
| http://www.w3.org/2001/04/xmlenc#kw-aes192 | ||
| Message Digest | ||
| SHA1 | REQUIRED | |
| http://www.w3.org/2000/09/xmldsig#sha1 | ||
| SHA256 | RECOMMENDED | |
| http://www.w3.org/2001/04/xmlenc#sha256 | ||
| SHA512 | OPTIONAL | |
| http://www.w3.org/2001/04/xmlenc#sha512 | ||
| RIPEMD-160 | OPTIONAL | |
| http://www.w3.org/2001/04/xmlenc#ripemd160 | ||
| Message Authentication | ||
| XML Digital Signature | RECOMMENDED | |
| http://www.w3.org/TR/2001/CR-xmldsig-core-20010419/ | ||
| Canonicalization | ||
| Canonical XML with Comments | RECOMMENDED | |
| http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments | ||
| Canonical XML | OPTIONAL | |
| http://www.w3.org/TR/2001/REC-xml-c14n-20010315 | ||
| Encoding | ||
| base64 | REQUIRED | |
| http://www.w3.org/2000/09/xmldsig#base64 | ||
The schema for EncryptionMethod is as follows:
Schema Definition:
<element name="EncryptionMethod" type="enc:EncryptionMethodType"/>
<complexType name="EncryptionMethodType" mixed="true">
<sequence>
<element name="KeySize" minOccurs="0" type="KeySizeType"/>
<element name="DigestMethod" minOccures="0" type="ds:DigestMethodType"/>
<element name="Params" minOccurs="0" type="string">
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
<!-- (0,unbounded) elements from (1,1) external namespace -->
</sequence>
<attribute name="Algorithm" type="anyURI" use="required"/>
</complexType>
Block encryption algorithms are designed for encrypting and decrypting data. Their identifiers appear as the value of the Algorithm attributes of EncryptionMethod elements that are children of EncryptedData.
Block encryption algorithms take, as implicit arguments, the data to encrypted or decrypted, the keying material, and their direction of operation. For all of these algorithms specified below, an initialization vector (IV) is required that is encoded with the cipher text. For user specified block encryption algorithms, the IV, if any, could be specified as being with the cipher data, as an algorithm element content, or elsewhere.
The triple DES algorithm is described in FIPS 46-3 [FIPS46] and ANSI X9.52 [3DES]. It is composed of three sequential DES operations. The XML Encryption 3DES consists of a DES encrypt, a DES decrypt, and a DES encrypt used in the Cipher Block Chaining (CBC) mode with 192 bits of key and a 64 bit Initialization Vector (IV). Of the key bits, the first 64 are used in the first DES operation, the second 64 bits in the middle DES operation, and the third 64 bits in the last DES operation. (Each of these 64 bits of key contain 56 effective bits and 8 parity bits.) The resulting cipher text is prefixed by the IV before being encoded in base64 for inclusion in XML output. Encryption applications MUST implement 3DES for data encryption. An example 3DES EncryptionMethod is as follows:
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#3des-cbc"/>
The AES algorithm is described in [AES]. XML Encryption implementations MUST support AES with 128 bit and 256 bit keys and MAY support AES with 192 bit keys. AES is used in the Cipher Block Chaining (CBC) mode with a 128 bit Initialization Vector (IV). The resulting cipher text is prefixed by the IV before being encoded in base64 for inclusion in XML output. An example AES EncryptionMethod is as follows:
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
Simple stream encryption algorithms generate, based on the key, a stream of bytes which are XORed with the plain text bytes to produce the cipher text on encryption and with the cipher text bytes to produce plain text on decryption.
NOTE: It is critical that each simple stream encryption key be used once only. If the same key is ever used on two messages then, by XORing the two cipher texts, you can obtain the XOR of the two plain texts. This is usually very compromising.
ARCFOUR is an fast simple stream encryption algorithm that is compatible with RSA Data System's RC4(tm) algorithm. It takes an optional KeySize explicit parameter. In cases where the key size is not apparent, as in the use of key agreement methods, this parameter sets the key size. If the size of the key to be used is apparent and disagrees with the KeySize parameter, an error should be returned. An example of an ARCFOUR EncryptionMethod is as follows:
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#arcfour">
<KeySize>40</KeySize>
</EncryptionMethod>
Implementation of ARCFOUR is optional. The schema for the KeySize parameter is as follows:
Schema Definition:
<simpleType name='KeySizeType'>
<restriction base="integer"/>
</simpleType>
Key Transport algorithms are public key encryption algorithms especially specified for encrypting and decrypting keys. Their identifiers appear as Algorithm attributes to EncryptionMethod elements that are children of EncryptedKey. The type of key being transported is given by the Type attribute of the EncryptedKey element. This attribute value must be the URI of an encryption algorithm.
The Key Transport algorithms given below are those used in conjunction with the Cryptographic Message Syntax (CMS) of S/MIME [CMS-Algorithms, CMS-AES].
This is the RSAES-PKCS1-v1_5 algorithm described in RFC 2437 [PKCS1]. The RSA-PKCS1-v1_5 algorithm takes no explicit parameters. An example of an RSA Version 1.5 EncryptionMethod element is:
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
The CipherData for such an encrypted key is the base64 [MIME] encoding of the octet string computed as per RFC 2437 [PKCS1, section 7.2.1: Encryption operation]. As specified in the EME-PKCS1-v1_5 function RFC 2437 [PKCS1, section 9.1.2.1], the value input to the key transport function is as follows:
CRYPT ( PAD ( KEY ))
where the padding is of the following special form:
02 | PS* | 00 | key
where "|" is concatentation, "02" and "00" are fixed octets of the corresponding hexadecimal value, PS is a string of strong pseudo-random octets [RANDOM] at least eight octets long, containing no zero octets, and long enough that the value of the quantity being CRYPTed is one octet shorter than the RSA modulus, and "key" is the key being transported. The key is 168 bits for 3DES and 128, 192, or 256 bits for AES. Support of this key transport algorithm for transporting 3DES keys is mandatory to implement. Support of this algorithm for transporting AES and ARCFOUR keys is optional. RAS-OAEP is recommended for the transport of AES keys.
The resulting base64 [MIME] string is the value of the child text node of the CipherData element, e.g.
<CipherData> IWijxQjUrcXBYoCei4QxjWo9Kg8D3p9tlWoT4
t0/gyTE96639In0FZFY2/rvP+/bMJ01EArmKZsR5VW3rwoPxw=
</CipherData>
This is the RSAES-OAEP-ENCRYPT algorithm described in RFC 2437 [PKCS1]. The RSA-OAEP algorithm takes as explicit parameters a message digest function and an optional octet string "Params". The message digest function is indicated by the Algorithm attribute of a child DigestMethod element and the octet string is the UTF-8 encoding of the text child of an optional Params element with white space (space, tab, CR, and LF) stripped. An example of an RSA-OAEP element is:
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep">
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<Params> foo </Params>
<EncryptionMethod>
The CipherData for an RSA-OAEP encrypted key is the base64 [MIME] encoding of the octet string computed as per RFC 2437 [PKCS1, section 7.1.1: Encryption operation]. As described in the EME-OAEP-ENCODE function RFC 2437 [PKCS1, section 9.1.1.1], the value input to the key transport function is calculated use the message digest function and string specified in the DigestMethod and Params elements and using the mask generator function MGF1 specified in RFC 2437. The desired output length for EME-OAEP-ENCODE is one byte shorter than the RSA modulus.
Encryption applications MUST implement RSA-OAEP for the transport of 128 and 256 bit AES keys. They MAY implement RSA-OAEP for the transport of 192 bit AES keys, 3DES keys, and ARCFOUR keys.
A Key Agreement algorithm provides for the derivation of a shared secret quantity based on certain types of compatible public keys from both the sender and the recipient. Information to determine the key associated with the originator is indicated by an optional KeyInfo parameter child of an AgreementMethod element. This element appears as the content of a KeyInfo. Information to determine the key associated with the recipient, if present, is indicated by other element content of this KeyInfo element child of EncryptedData or EncryptedKey. In addition, the sender may include a Nonce element under AgreementMethod to assure that different keying material is generated even for repeated agreements using the same sender and recipient public keys. For example:
<EncryptedData>
<EncryptionMethod Algorithm="Example:Block/Algorithm"
<KeySize>80</KeySize>
</EncryptionMethod>
<KeyInfo>
<KeyValue>...recipient...</KeyValue>
<AgreementMethod Algorithm="Example:Agreement/Algorithm">
<Nonce> foo </Nonce>
<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256">
<KeyInfo>
<KeyValue>...originator...</KeyValue>
</KeyInfo>
</AgreementMethod>
</KeyInfo>
<CipherData>...</CipherData>
</EncryptedData>
If the agreed key is being used to wrap a key, rather than data as above, then AgreementMethod would appear inside a KeyInfo inside an EncryptedKey element.
The Schema for AgreementMethod is as follows:
Schema Definition:
<element name="AgreementMethod" type="enc:AgreementMethodType"/>
<complexType name="AgreementMethodType" mixed="true">
<sequence>
<element name="Nonce" minOccurs="0" type="string"/>
<element name="DigestMethod" minOccurs="0" type="ds:DigestMethodType">
<element name="KeyInfo" minOccurs="0" type="ds:KeyInfoType">
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
<!-- (0,unbounded) elements from (1,1) external namespace -->
</sequence>
<attribute name="Algorithm" type="anyURI" use="required"/>
</complexType>
The AgreementMethod will derive some shared secret octet sequence ZZ. The amount of actual keying material needed will then be calculated as follows:
Keying Material = KM(1) | KM(2) | ...
where "|" is byte stream concatenation and
KM(counter) = DigestAlg ( EncryptionAlg | ZZ | counter | Nonce | KeySize ).
DigestAlg is the message digest algorithm specified by the DigestMethod child of AgreementMethod. EncryptionAlg is the URI of the encryption algorithm, including possible key wrap algorithms, in which the derived keying material is to be used ("Example:Block/Algorithm" in the example above), not the URI of the agreement algorithm. Nonce is the UTF-8 serialization of the text child of the Nonce child of AgreementMethod, if present, with white space (space, tab, CR, and LF) stripped. If the Nonce element is absent, it is null. Counter is a one byte counter. KeySize is the size in bits of the key to be derived from the shared secret as the UTF-8 string for the corresponding decimal integer with only digits in the string and no leading zeros. For some algorithms the key size is inherent in the URI. For others, such as ARCFOUR, it may be explicitly provided. For example, the initial (KM(1)) calculation for the example above, with ZZ not replaced by the binary shared secret octet sequence and the binary "1" counter byte represented as %01, would be calculated as follows:
SHA-256 ( Example:Block/AlgorithmZZ%01foo40 )
Each application of DigestAlg will produces some number of bytes of keying material. >From the concatenated string of one or more KM's, enough leading bytes are taken to meet the need for an actual key and the remainder discarded. For example, if DigestAlg is SHA1 which produces 20 octets of hash, then for 128 bit AES the first 16 bytes from KM(1) would be taken and the remaining 4 bytes discarded. For 256 bit AES, all of KM(1) suffixed with the first 12 bytes of KM(2) would be taken and the remaining 8 bytes of KM(2) discarded.
Diffie-Hellman keys can appear directly within KeyValue elements or be obtained by RetrievalMethod fetches as well as appearing in certificates and the like. The above identifier can be used as the value of the Type attribute of Reference or RetrievalMethod elements.
A DH public key consists of three quantities, a large Prime p, a "Generator" g, and "Public" such that Public = g**x mod p. The corresponding private key is x. Because a Prime and Generator can be safely shared over many DH keys, they may be known from the application environment and are optional. The schema for a DHKeyValue is as follows:
Schema:
<element name="DHKeyValue" type="enc:DHKeyValueType"/>
<complexType name="DHKeyValueType">
<sequence>
<element name="Prime" type="ds:CryptoBinary" minOccurs="0"/>
<element name="Generator" type="ds:CryptoBinary" minOccurs="0"/>
<element name="Public" type="ds:CryptoBinary"/>
</sequence>
</complexType>
Diffie-Hellman (DH) key agreement involves the derivation of shared secret information based on compatible DH keys from the sender and recipient. Two DH public keys are compatible if they have the same prime and generator. If, for the second one, Y = g**y mod p, then the two parties can calculate the shared secret ZZ = ( g**(x*y) mod p ) even though each knows only their own private key and the other party's pubic key. Leading zero bytes MUST be maintained in ZZ so it will be the same length, in bytes, as p. We require that p be at least 512 bits and g at least 160 bits. There are numerous other complex security considerations in the selection of g, p, and a random x as described in [RFC 2631].
Diffie-Hellman key agreement is optional to implement. An example of a DH AgreementMethod element is as follows:
<AgreementMethod Algorithm="http://www.w3.org/2001/04/xmlenc#dh">
<KeyInfo><X509Data><X509Certificate>
...
</X509Certificate></X509Data></KeyInfo>
</AgreementMethod>
Symmetric Key Wrap algorithms are shared secret key encryption algorithms especially specified for encrypting and decrypting symmetric keys. Their identifiers appear as Algorithm attributes to EncryptionMethod elements that are children of EncryptedKey. The type of the key being wrapped is indicated by the Type attribute of EncryptedKey.
Some key wrap algorithms make use of the Key Checksum defined in CMS [RFC 2630bis]. This is used to provide an integrity check value for the key being wrapped. The algorithm is
The type of the key being wrapped is given by the Type attribute of the parent EncryptedKey element. XML Encryption applications MUST support 3DES wrapping of 3DES keys and may optionally support 3DES wrapping of AES keys. An example of a 3DES Key Wrap EncryptionMethod element is a as follows:
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#kw-3des"/>
The following algorithm wraps (encryptes) a key (the wrapped key, WK)
under a 3DES key-encryption-key (KEK):
The following algorithm unwraps (decyrptes) a key:
The above specification is that given in [CMS-Algorithms].
Implementation of AES key wrap as sepcified by NIST/NSA/CMS will be mandatory for AES 128 and AES 256 and recommended for AES 192 -- when it's completely specified.
Message digest algorithms are used in CipherData to insure integrity, in AgreementMethod as part of the key derivation, and within RSA-OAEP encryption as a hash function, and in connection with the HMAC Message Authentication Code method as described in [XMLDSIG].)
The SHA-1 algorithm [SHA-1] takes no explicit parameters. XML encryption applications MUST implement SHA-1. An example of an SHA-1 DigestMethod element is:
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
A SHA-1 digest is a 160-bit string. The content of the DigestValue element shall be the base64 encoding of this bit string viewed as a 20-octet octet stream. For example, the DigestValue element for the message digest:
A9993E36 4706816A BA3E2571 7850C26C 9CD0D89D
from Appendix A of the SHA-1 standard would be:
<DigestValue>qZk+NkcGgWq6PiVxeFDCbJzQ2J0=</DigestValue>
The SHA-256 algorithm [SHA-256] takes no explicit parameters. It is RECOMMENDED that XML encryption applications implement SHA-256. An example of an SHA-256 DigestMethod element is:
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha256"/>
A SHA-256 digest is a 256-bit string. The content of the DigestValue element shall be the base64 encoding of this bit string viewed as a 32-octet octet stream.
The SHA-512 algorithm [SHA-512] takes no explicit parameters. XML encryption applications MAY implement SHA-512. An example of an SHA-512 DigestMethod element is:
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha512"/>
A SHA-512 digest is a 512-bit string. The content of the DigestValue element shall be the base64 encoding of this bit string viewed as a 64-octet octet stream.
The RIPEMD-160 algorithm [RIPEMD-160] takes no explicit parameters. XML encryption applications may implement RIPEMD-160. An example of an RIPEMD-160 DigestMethod element is:
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#ripemd160"/>
A RIPEMD-160 digest is a 160-bit string. The content of the DigestValue element shall be the base64 encoding of this bit string viewed as a 20-octet octet stream.
XML Signature [XMLDSIG] is optional to implement for XML encryption applications. It is the recommended way to provide key based authentication.
If XML is to be encrypted it must first be serialized into an octet stream If it is to be later decrypted into a different environment and it is desired to preserve such aspects of its original environment as namespace prefix bindings, the value of attributes in the "xml" namespace, etc., then the Canonical XML With Comments version of the XML should be the serialization that is encrypted [Canon]. Although this is not, properly speaking, a part of the encryption/decryption process, it is RECOMMENDED that XML encryption applicaitons implement Canonical XML With Comments and they MAY also implement Canonial XML (without comments).