5. Algorithms

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.

5.1 Algorithm Identifiers and Implementation Requirements

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 the algorithm element or in an algorithm specific namespace. An example of such an explicit parameter could be an encryption initialization vector (IV) although for all encryption algorithms specified herein, the IV appears as part of the "cipher text" block.

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 signature applications.

No stream encryption algorithms are sepcified.

5.2 Block Encryption Algorithms

Block encryption algorithms take, as implicit arguments, the data to encrypted or decrypted, the keying material, and their direction of operation. Any initialization vector required is encoded with the cipher text. They 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.

5.2.1 Triple DES

Identifiers:

http://www.w3.org/2001/04/xmlenc#3des

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 168 bits of key and a 64 bit Initialization Vector (IV). Of the key bits, the first 56 are used in the first DES operation, the second 56 bits in the middle DES operation, and the third 56 bits in the last DES operation. The resulting cipher text is prefixed by the IV before being encoded in base64 for inclusion in XML output. Implementation of 3DES for data encryption is mandatory. An example 3DES EncryptionMethod is as follows:

   <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#3des"/>

5.2.2 AES

Identifiers:

http://www.w3.org/2001/04/xmlenc#aes128
http://www.w3.org/2001/04/xmlenc#aes192
http://www.w3.org/2001/04/xmlenc#aes256

The AES algorithm is described in [AES]. XML Encryption implementations MUST support AES with 128 bit keys and it is recommended that they support 192 and 256 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. Implementation of 128 bit AES for data encryption is mandatory. An example AES EncryptionMethod is as follows:

   <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128"/>

5.3 Key Transport

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 encrytion 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].

5.3.1 RSA Version 1.5

Identifier:

http://www.w3.org/2001/04/xmlenc#rsa-1_5

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 MUST be as follows:

   CRYPT ( PAD ( KEY ))

where the padding MUST be 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 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 mandtory to implement. Support of this algorithm for transporting AES keys is optional.

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>

5.3.2 RSA-OAEP

Identifier:

http://www.w3.org/2001/04/xmlenc#rsa-oaep

This is the RSAES-OAEP-ENCRYPT algorithm described in RFC 2437 [PKCS1]. The RSA-OAEP algorithm takes as explicit parameters a hash function and an octet string "P". The hash function is indicated by the Algorithm attribute of a child OAEP element and "P" is the UTF-8 encoding of the text child of this OAEP 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">
      <OAEP Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">foo</OAEP>
   <EncryptionMethod>

The CipherData for an RSA OAEP 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 the hash function and P specified in the OAEP element and using the mask generator function MGF1 specified in RFC 2437.

5.4 Key Agreement

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 associatred with the sender is indicated by an optional KeyInfo parameter child of AgreementMethod which appears as the content of KeyInfo. Information to determine the key associated with the recipient, if present, is indicated by other element content of the 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"/>
      <KeyInfo>
         <KeyValue>...recipient...</KeyValue>
         <AgreementMethod Algorithm="Example:Agreement/Algorithm">
            <Nonce>...</Nonce>
            <KeyInfo>
               <KeyValue>...sender...</KeyValue>
            </KeyInfo>
         </AgreementMethod>
      </KeyInfo>
      <CipherData>...</CipherData>
   </EncryptedData>

If the agreed key is being used to wrap a key, rather than directly as above, then AgreementMethod would appear inside a KeyInfo inside an EncryptedKey element.

The AgreementMethod will derive some shared secret ZZ. The amount of actual keying material needed will then be calculated as follows:

   Keying Material = KM(1) | KM(2) | ...

where "|" is byte atream concatenation and

   KM(counter) = SHA1 ( Algorithm | ZZ | counter | Nonce ).

Algorithm is the URI of the algorithm 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. Each application of SHA1 produces 160 bits or 20 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, for 128 bit AES, the first 16 bytes from KM(1) are taken and the remaining 4 bytes discarded. For 256 bit AES, all of KM(1) suffixed with the first 12 bytes of KM(2) are taken and the remaining 8 bytes of KM(2) are discarded.

5.4.1 Diffie-Hellman Key Values

Identifier:

http://www.w3.org/2001/04/xmlenc#DHKeyValue

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 X such that X = 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="X" type="ds:CryptoBinary"/>
      </sequence>
   </complexType>

5.4.2 Diffie-Hellman Key Agreement

Identifier:

http://www.w3.org/2001/04/xmlenc#dh

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>

5.5 Symmetric Key Wrap

Symmetric Key Wrap algorithms are 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. This attribute must be the URI of a symmetric encryption algorithm.

5.5.1 CMS Key Checksum

Some specific key wrap algorithms given below 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

1. Compute the 20 octet SHA-1 hash on the key being wrapped.
2. Use the first 8 octets of this hash as the checksum value.

5.5.2 CMS Triple DES Key Wrap

Identifiers:

http://www.w3.org/2001/04/xmlenc#kw-3des

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#ke-3des"/>

1. Represent the key being wrapped as an octet sequence. If it is a 3DES key, this is 24 octets (192 bits) produced by inserting an odd parity bit as the bottom bit of each octet.
2. Compute the key checksum defined in 5.5.1 above, call this CKS.
3. Let WKCKS = WK || CKS where || is concatenation.
4. Generate 8 random octets and call this IV.
5. Encrypt WKCKS in CBC mode using KEK as the key and IV as the initialization vector. Call the results TEMP1.
6. Left TEMP2 = IV || TEMP1.
7. Reverse the order of the octets in TEMP2 and call the result TEMP3.
8. Encrypt TEMP3 in CBC mode using the KEK and an initialization vector of 0x4adda22c79e82105. The resulting ciphertext is the desired result. It is 40 octets long if a 3DES key is being wrapped.

The following algorithm unwraps (decyrptes) a key:

1. Check if the length of the cipher text is reasonable given the key type. It must be 40 bytes for a 3DES key and either 32, 40, or 48 bytes for an AES key. If the length is wrong, return error.
2. Decrypt the cipher text with 3DES in CBC mode using the KEK and an initialization vector (IV) of 0x4adda22c79e82105. Call the output TEMP3.
3. Reverse the order of the octets in TEMP3 and call the result TEMP2.
4. Decompose TEMP2 into IV, the first 8 octets, and TEMP1, the remaining octets.
5. Decrypt TEMP1 using 3DES in CBC mode using the KEK and the IV found in the previous step. Call the result WKCKS.
6. Decompose WKCKS. CKS is the last 8 octets and WK, the wrapped key, are those octets before the CKS.
7. Calculate a CMS Key Checksum, as described in Section 5.5.1, over the WK and compare with the CKS extracted in the above step. If they are not equal, return error.
8. WK is the wrapped key, now extracted for use in data decryption.

The above specification is that given in [CMS-Algorithms].

5.5.3 CMS RC2 Key Wrap

Identifiers:

http://www.w3.org/2001/04/xmlenc#kw-rc2

The type of the key being wrapped is given by the Type attribute of the parent EncryptedKey element. XML Encryption applications MUST support RC2 wrapping of 3DES keys and AES keys. An example of an RC2 Key Wrap EncryptionMethod element is a as follows:

   <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#kw-rc2"/>

1. Let the length of the wrapped key (WK) be a single octet called LENGTH.
2. Let LWK = LENGTH || WK.
3. Let LWKPAD = LWK || PAD where PAD is the smallest number of random octets, possibly none, necessary to bring the length of LWKPAD up to a multiple of 8.
4. Let LWKPADCKS = LWKPAD || CKS where CKS is the 8 octet key checksum on LCKPAD as described in 5.5.1.
5. Generate 8 octets at random and call this IV.
6. Encrypt LWKPADCKS with RC2 in CBC mode using the KEK with initialization vector IV. Call the ciphertext TEMP1.
7. Let TEMP2 = IV || TEMP1.
8. Reverse the order of octets in TEMP2 and call the result TEMP3.
9. Encrypt TEMP3 with RC2 in CBC mode using the KEK and an initialization vector (IV) of 0x4adda22c79e82105.

The following algorithm unwraps (decyrptes) a key:

1. If the data to be unwrapped is not a multiple of 8 octets, then return error.
2. Decrypt with the KEK in CBC mode using an initialization vector (IV) of of 0x4adda22c79e82105. Call the output TEMP3.
3. Reverse the order of the bytes in TEMP3 calling the result TEMP2.
4. Decompose TEMP2 into IV and TEMP1 where IV is the first 8 octets and TEMP1 is the remainder.
5. Decrypt TEMP1 with RC2 in CBC mode using KEK and IV. Call the plaintext LWKPADCKS.
6. Decompose LWKPADCKS into LWKPAD and CKS where CKS is the last 8 octets and LWKPAD are those appearing before CKS.
7. Compute the 8 byte checksum of LWKPAD as described in 5.5.1 and compare with CKS. If they differ, return error.
8. Decompose LWKPAD into LENGTH, WK, and PAD. LENGTH is the first octet. WK is the following LENGTH octets and PAD is any remaining octets. If the length of PAD is greater than 7 octets or would be negative, return error.
9. WK is the desired unwrapped key.

The above specification is that given in [CMS-Algorithms].

5.5.4 AES KeyWrap

Identifiers:

http://www.w3.org/2001/04/xmlenc#kw-aes128
http://www.w3.org/2001/04/xmlenc#kw-aes192
http://www.w3.org/2001/04/xmlenc#kw-aes256

Implementation of AES key wrap as sepcified by NIST/NSA/CMS will be mandatory for AES 128 and recommended for AES 192 and 256 -- when it's completely specified.

5.6 Message Digest

Message digest algorithms are used to insure integrity without authentication. The algorithm URI appears as the value of the Algorithm attribute of a DigestMethod element within a CipherData element. (These algorithms can also be used as the hash algorithm in connection with the RSA-OAEP key transport algorithm and in connection with the HMAC Message Authentication Code method as described in [XMLDSIG].)

5.6.1 SHA1

Identifier:

http://www.w3.org/2000/09/xmldsig#sha1

The SHA-1 algorithm [SHA-1] takes no explicit parameters. 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>

5.6.2 SHA256

Identifier:

http://www.w3.org/2001/04/xmlenc#sha256

The SHA-256 algorithm [SHA-256] takes no explicit parameters. 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.

5.6.3 SHA512

Identifier:

http://www.w3.org/2001/04/xmlenc#sha512

The SHA-512 algorithm [SHA-512] takes no explicit parameters. An example of an SHA-512 DigestMethod element is:

   <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha512"/>

A SHA-1 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.

5.7 Message Authentication

XML Signature [XMLDSIG] is optional to implement and is the recommended way to provide key based authentication.

5.8 Canonicalization

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 it is RECOMMENDED that the Canonical XML With Comments version of the XML be encrypted [Canon].