XML Encryption Syntax and Processing

Abstract

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.

Status of this document

This is an Editors' draft with no official standing.

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 element representing the role of the algorithm, a reference to the formal specification, definitions for the representation of keys and the results of cryptographic operations where applicable, and general applicability comments.

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 SHOULD 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 quantity) provided to a key agreement algorithm.

This specification defines a set of algorithms, their URIs, and requirements for implementation. Levels of requirement specified, such as "REQUIRED" or "OPTIONAL", refere to implementation, not use. Furthermore, the mechanism is extensible, and alternative algorithms may be used.

Table of Algorithms

The table below lists the categories of algorithms. Within each category, a brief name, the level of implementation requirement, and an identifying URI are given for each algorithm.

Block Encryption

1. REQUIRED TRIPLEDES
   http://www.w3.org/2001/04/xmlenc#tripledes-cbc
2. REQUIRED AES-128
   http://www.w3.org/2001/04/xmlenc#aes128-cbc
3. REQUIRED AES-256
   http://www.w3.org/2001/04/xmlenc#aes256-cbc
4. OPTIONAL AES-192
   http://www.w3.org/2001/04/xmlenc#aes192-cbc

Stream Encryption

1. none
   Syntax and recommendations are given below to support user specified algorithms.

Key Transport

1. REQUIRED RSA-v1.5
   http://www.w3.org/2001/04/xmlenc#rsa-1_5
2. REQUIRED RSA-OAEP
   http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

Key Agreement

1. OPTIONAL Diffie-Hellman
   http://www.w3.org/2001/04/xmlenc#dh

Symmetric Key Wrap

1. REQUIRED TRIPLEDES KeyWrap
   http://www.w3.org/2001/04/xmlenc#kw-tripledes
2. REQUIRED AES-128 KeyWrap
   http://www.w3.org/2001/04/xmlenc#kw-aes128
3. REQUIRED AES-256 KeyWrap
   http://www.w3.org/2001/04/xmlenc#kw-aes256
4. OPTIONAL AES-192 KeyWrap
   http://www.w3.org/2001/04/xmlenc#kw-aes192

Message Digest

1. REQUIRED SHA1
   http://www.w3.org/2000/09/xmldsig#sha1
2. RECOMMENDED SHA256
   http://www.w3.org/2001/04/xmlenc#sha256
3. OPTIONAL SHA512
   http://www.w3.org/2001/04/xmlenc#sha512
4. OPTIONAL RIPEMD-160
   http://www.w3.org/2001/04/xmlenc#ripemd160

Message Authentication

1. RECOMMENDED XML Digital Signature
   http://www.w3.org/TR/2001/CR-xmldsig-core-20010419/

Canonicalization

1. OPTIONAL Canonical XML (omits comments)
   http://www.w3.org/TR/2001/REC-xml-c14n-20010315
2. OPTIONAL Canonical XML with Comments
   http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments
3. OPTIONAL Exclusive XML Canonicalization (omits comments)
   http://www.w3.org/TR/2001/xml-exc-c14n#
4. OPTIONAL Exclusive XML Canonicalization with Comments
   http://www.w3.org/TR/2001/xml-exc-c14n#WithComments

Encoding

1. REQUIRED base64
   http://www.w3.org/2000/09/xmldsig#base64

EncryptionMethod Element Schema

The schema for EncryptionMethod is as follows:

  Schema Definition:

  <complexType name='EncryptionMethodType' mixed='true'>
    <sequence>
      <element name='KeySize' minOccurs='0'
               type='xenc:KeySizeType'/>
      <!-- <element ref='ds:DigestMethod' minOccurs='0'/> -->
      <element name='OAEPparams' minOccurs='0'
               type='base64Binary'/>
      <any namespace='##other' minOccurs='0'
                               maxOccurs='unbounded'/>
     </sequence>
   <attribute name='Algorithm' type='anyURI' use='required'/>
  </complexType>

NOTE: Which child elements to the EncryptionMethod algorithm role are allowed or required depends on the specific value of the Algorithm attribute URI; however, the KeySize child element is always permitted. (Schema does not provide a facility for expressing conditionality of child element occurrence based on attribute value.) 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.)

5.2 Block Encryption Algorithms

Block encryption algorithms are designed for encrypting and decrypting data in fixed size, multiple octet blocks. 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 be 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 content element, or elsewhere.

The IV is encoded with and before the cipher text for the algorithms below for ease of availability to the decryption code and to emphasize its association with the cipher text. Good cryptographic practice requires that a different IV be used for every encryption.

Padding

Since the data being encrypted is an arbitrary number of octets, it may not be a multiple of the block size. This is solved by padding the plain text up to the block size before encryption and unpadding after decrytion. (This us done after prepending the nonce for encryption.) The padding algorithm is to calculate the smallest non-zero number of octets, say N, that must be suffixed to the plain text to bring it up to a multiple of the block size. We will assume the block size is B octets so N is in the range of 1 to B. Pad by suffixing the plain text with N-1 arbitrary pad bytes and a final byte whose value is N. On decryption, just take the last byte and, after sanity checking it, strip that many bytes from the end of the decrypted cipher text.

For example, assume an 8 byte block size and plain text of 0x616263. The padded plain text would then be 0x616263????????05 where the "??" bytes can be any value. Similarly, plain text of 0x2122232425262728 would be padded to 0x2122232425262728??????????????08.

5.2.1 Triple DES

Identifier:

http://www.w3.org/2001/04/xmlenc#tripledes-cbc (REQUIRED)

ANSI X9.52 [TRIPLEDES] specifies three sequential FIPS 46-3 [DES] operations. The XML Encryption TRIPLEDES 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.

Note: Each of these 64 bits of key contain 56 effective bits and 8 parity bits. Thus there are only 168 operational bits out of the 192 being transported for a TRIPLEDES key. (Depending on the criterion used for analysis, the effective strength of the key may be thought to be 112 bits (due to meet in the middle attacks) or even less.)

The resulting cipher text is prefixed by the IV. If included in XML output, it is then base64 encoded. An example TRIPLEDES EncryptionMethod is as follows:

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

5.2.2 AES

Identifier:

http://www.w3.org/2001/04/xmlenc#aes128-cbc (REQUIRED)

http://www.w3.org/2001/04/xmlenc#aes192-cbc (OPTIONAL)

http://www.w3.org/2001/04/xmlenc#aes256-cbc (REQUIRED)

[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. If included in XML output, it is then base64 encoded. An example AES EncryptionMethod is as follows:

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

5.3 Stream Encryption Algorithms

Simple stream encryption algorithms generate, based on the key, a stream of bytes which are XORed with the plain text data bytes to produce the cipher text on encryption and with the cipher text bytes to produce plain text on decryption. They are normally used for the encryption of data and are specified by the value of the Algorithm attribute of the EncryptionMethod child of an EncryptedData element.

NOTE: It is critical that each simple stream encryption key (or key and initialization vector (IV) if an IV is also used) be used once only. If the same key (or key and IV) 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.

No specific steam encryption algorithms are specified herein but this section is included to provide general guidelines.

Stream algorithms typically use the optional KeySize explicit parameter. In cases where the key size is not apparent from the algorithm URI or key source, 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 MUST be returned. Implementation of any stream algorithms is optional. The schema for the KeySize parameter is as follows:

  Schema Definition:

  <simpleType name='KeySizeType'>
    <restriction base="integer"/>
  </simpleType>

5.4 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. EncryptedKey is in turn the child of a ds:KeyInfo element. The type of key being transported, that is to say the algorithm in which it is planned to use the transported key, is given by the Algorithm attribute of the EncryptionMethod child of the EncryptedData or EncryptedKey parent of this ds:KeyInfo element.

(Key Transport algorithms may optionally be used to encrypt data in which case they appear directly as the Algorithm attriubte of an EncryptionMethod child of an EncryptedData element. Because they use public key algorithms directly, Key Transport algorithms are not efficient for the transport of any amounts of data significantly larger than symmetric keys.)

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.4.1 RSA Version 1.5

Identifier:

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

The RSAES-PKCS1-v1_5 algorithm, specified in RFC 2437 [PKCS1], 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 CipherValue 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 concatenation, "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 192 bits for TRIPLEDES and 128, 192, or 256 bits for AES. Support of this key transport algorithm for transporting 192 bit keys is mandatory to implement. Support of this algorithm for transporting other 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>

5.4.2 RSA-OAEP

Identifier:

http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p (REQUIRED)

THE RSAES-OAEP-ENCRYPT, as specified in RFC 2437 [PKCS1], algorithm takes as explicit parameters a message digest function and an optional octet string OAEPparams. The message digest function is indicated by the Algorithm attribute of a child DigestMethod element and the octet string is the base64 decoding of the content of an optional OAEPparams child element. An example of an RSA-OAEP element is:

  <EncryptionMethod
     Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p">
     <ds:DigestMethod
        Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
     <OAEPparams> 9lWu3Q== </OAEPparams>
  <EncryptionMethod>

The CipherValue 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 using the message digest function and string specified in the DigestMethod and OAEPparams 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.

The transported key size is 192 bits for TRIPLEDES and 128, 192, or 256 bits for AES. Implementations MUST implement RSA-OAEP for the transport of 128 and 256 bit keys. They MAY implement RSA-OAEP for the transport of other keys.

5.5 Key Agreement

A Key Agreement algorithm provides for the derivation of a shared secret key based on a shared secret computed from certain types of compatible public keys from both the sender and the recipient. Information from the originator to determine the secret is indicated by an optional OriginatorKeyInfo parameter child of an AgreementMethod element while that associated with the recipient is indicated by an optional RecipientKeyInfo. A shared key is derived from this shared secret by a method determined by the Key Agreement algorithm.

Note: XML Encryption does not provide an on-line key agreement negotiation protocol. The AgreementMethod element can be used by the originator to identify the keys and computational procedure that were used to obtain a shared encryption key. The method used to obtain or select the keys or algorithm used for the agreement computation is beyond the scope of this specification.

The AgreementMethod element appears as the content of a ds:KeyInfo since, like other ds:KeyInfo children, it yields a key. This ds:KeyInfo is in turn a child of an EncryptedData or EncryptedKey element. The Algorithm attribute and KeySize child of the EncryptionMethod element under this EncryptedData or EncryptedKey element are implicit parameters to the key agreement computation. In cases where this EncryptionMethod algorithm URI is insufficient to determine the key length, a KeySize MUST have been included. In addition, the sender may place a KA-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/Alg"
     <KeySize>80</KeySize>
   </EncryptionMethod>
   <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
     <AgreementMethod Algorithm="Example:Agreement/Algorithm">
       <KA-Nonce>Zm9v</KA-Nonce>
       <DigestMethod
        Algorithm="http://www.w3.org/2001/04/xmlenc#sha1">
       <OriginatorKeyInfo>
         <KeyValue>...originator...</KeyValue>
       </OriginatorKeyInfo>
       <RecipientKeyInfo>
         <KeyValue>...recipient...</KeyValue>
       </RecipientKeyInfo>
     </AgreementMethod>
   </ds: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 ds:KeyInfo inside an EncryptedKey element.

The Schema for AgreementMethod is as follows:

  Schema Definition:

  <element name="AgreementMethod"
           type="xenc:AgreementMethodType"/>
  <complexType name="AgreementMethodType" mixed="true">
    <sequence>
      <element name="KA-Nonce" minOccurs="0" type="base64Binary"/>
      <element ref="ds:DigestMethod" minOccurs="0"/>
      <element name="OriginatorKeyInfo" minOccurs="0"
               type="ds:KeyInfoType"/>
      <element name="RecipientKeyInfo" minOccurs="0"
               type="ds:KeyInfoType"/>
      <any namespace="##other" minOccurs="0"
                               maxOccurs="unbounded"/>
     </sequence>
   <attribute name="Algorithm" type="anyURI" use="required"/>
   </complexType>

5.5.1 Diffie-Hellman Key Values

Identifier:

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

Diffie-Hellman keys can appear directly within KeyValue elements or be obtained by ds: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 ds:RetrievalMethod elements.

As specified in [ESDH], a DH public key consists of up to six quantities, two large primes p and q, a "generator" g, the public key, and validation parameters "seed" and "pgenCounter". These relate as follows: The public key = ( g**x mod p ) where x is the corresponding private key; p = j*q + 1 where j >= 2. "seed" and "pgenCounter" are optional and can be used to determine if the Diffie-Hellman key has been generated in conformance with the algorithm specified in [ESDH]. Because the primes 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="xenc:DHKeyValueType"/>
  <complexType name="DHKeyValueType">
     <sequence>
        <sequence minOccurs="0">
           <element name="P" type="ds:CryptoBinary"/>
           <element name="Q" type="ds:CryptoBinary"/>
           <element name="Generator"type="ds:CryptoBinary"/>
        </sequence>
        <element name="Public" type="ds:CryptoBinary"/>
        <sequence minOccurs="0">
           <element name="seed" type="ds:CryptoBinary"/>
           <element name="pgenCounter" type="ds:CryptoBinary"/>
        </sequence&gy;
     </sequence>
  </complexType>

5.5.2 Diffie-Hellman Key Agreement

Identifier:

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

The Diffie-Hellman (DH) key agreement protocol [ESDH] 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 public key. Leading zero bytes MUST be maintained in ZZ so it will be the same length, in bytes, as p. The size of p MUST 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 [ESDH].

Diffie-Hellman key agreement is optional to implement. An example of a DH AgreementMethod element is as follows:

  <xenc:AgreementMethod
      xenc:Algorithm="http://www.w3.org/2001/04/xmlenc#dh"
      xmlns="http://www.w3.org/2000/09/xmldsig#">
    <xenc:KA-Nonce>Zm9v</KA-Nonce>
    <DigestMethod
     Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
    <xenc:OriginatorKeyInfo>
      <X509Data><X509Certificate>
        ...
      </X509Certificate></X509Data>
    </xenc:OriginatorKeyInfo>
    <xenc:RecipientKeyInfo><KeyValue>
      ...
    </KeyValue></RecipientKeyInfo>
  </xenc:AgreementMethod>

Assume the Diffie-Hellman shared secret is the octet sequence ZZ. The shared keying material needed will then be calculated as follows:

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

where "|" is byte stream concatenation and

  KM(counter) = DigestAlg ( ZZ | counter | EncryptionAlg | 
                KA-Nonce | KeySize )

DigestAlg

The message digest algorithm specified by the DigestMethod child of AgreementMethod.

EncryptionAlg

The URI of the encryption algorithm, including possible key wrap algorithms, in which the derived keying material is to be used ("Example:Block/Alg" in the example above), not the URI of the agreement algorithm. This is the value of the Algorithm attribute of the EncryptionMethod child of the EncryptedData or EncryptedKey grandparent of AgreementMethod.

KA-Nonce

The base64 decoding the content of the KA-Nonce child of AgreementMethod, if present. If the KA-Nonce element is absent, it is null.

Counter

A one byte counter starting at one and counting by one. It is expressed as two hex digits.

KeySize

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 most stream ciphers, it must be explicitly provided.

For example, the initial (KM(1)) calculation for the AgreementMethod example above would be as follows, where the bbinary one byte counter value of 1 is represented by the two character UTF-8 sequence 01, ZZ is the shared secret, and "foo" is the base64 decoding of "Zm9v".

  SHA-1 ( Example:Block/AlgZZ001foo80 )

Assuming that ZZ is 0xDEADBEEF, that would be

  SHA-1 ( 0x4578616D706C652F416C67DEADBEEF3031666F6F3830 )

whose value is

  0x606F9961E4CEFB12416FAB0FCC9377FF06EDC87

Each application of DigestAlg for successive values of Counter will produce some additional 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.

5.6 Symmetric Key Wrap

Symmetric Key Wrap algorithms are shared secret key encryption algorithms especially specified for encrypting and decrypting symmetric keys. Their identifiers appear as Algorithm attribute values to EncryptionMethod elements that are children of EncryptedKey which is in turn a child of ds:KeyInfo which is in turn a child of EncryptedData or another EncryptedKey. The type of the key being wrapped is indicated by the Algorithm attribute of EncryptionMethod child of the parent of the ds:KeyInfo grandparent of the EncryptionMethod specifying the symmetric key wrap algorithm.

5.6.1 CMS Key Checksum

Some key wrap algorithms make use of the key checksum defined in CMS [CMS-Wrap]. 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.6.2 CMS Triple DES Key Wrap

Identifiers and Requirements:

http://www.w3.org/2001/04/xmlenc#kw-tripledes (REQUIRED)

XML Encryption implementations MUST support TRIPLEDES wrapping of 168 bit keys and may optionally support TRIPLEDES wrapping of other keys.

An example of a TRIPLEDES Key Wrap EncryptionMethod element is a as follows:

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

The following algorithm wraps (encrypts) a key (the wrapped key, WK) under a TRIPLEDES key-encryption-key (KEK) as specified in [CMS-Algorithms]:

1. Represent the key being wrapped as an octet sequence. If it is a TRIPLEDES key, this is 24 octets (192 bits) with odd parity bit as the bottom bit of each octet.
2. Compute the CMS key checksum, (section 5.6.1), call this CKS.
3. Let WKCKS = WK || CKS, where || is concatenation.
4. Generate 8 random octets [RANDOM] 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 cipher text is the desired result. It is 40 octets long if a 168 bit key is being wrapped.

The following algorithm unwraps (decrypts) a key as specified in [CMS-Algorithms]:

1. Check if the length of the cipher text is reasonable given the key type. It must be 40 bytes for a 168 bit key and either 32, 40, or 48 bytes for a 128, 192, or 256 bit key. If the length is not supported or inconsistent with the algorithm for which the key is intended, return error.
2. Decrypt the cipher text with TRIPLEDES 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 TRIPLEDES 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, (section 5.6.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.

5.6.3 AES KeyWrap

Identifiers and Requirements:

http://www.w3.org/2001/04/xmlenc#kw-aes128 (REQUIRED)

http://www.w3.org/2001/04/xmlenc#kw-aes192 (OPTIONAL)

http://www.w3.org/2001/04/xmlenc#kw-aes256 (REQUIRED)

Implementation of AES key wrap is described below, as suggested by NIST. It provides for confidentiality and integrity. This algorithm is defined only for inputs which are a multiple of 64 bits. The information wrapped need not actually be a key. The algorithm is the same whatever the size of the AES key used in wrapping, called the key encrypting key or KEK. The implementation requirements are indicated below.

Assume tha the data to be wrapped consists of N 64-bit data blocks denoted P(1), P(2), P(3) ... P(N). The result of wrapping will be N+1 64-bit blocks denoted C(0), C(1), C(2), ... C(N). They key encrypting key is represented by K. Assume integers i, j, and t and intermediate 64-bit register A, 128-bit register B, and array of 64-bit quantities R(1) through R(N).

"|" represents concatentation so x|y, where x and y and 64-bit quantities, is the 128-bit quantity with x in the most significant bits and y in the least significant bits. AES(K)enc(x) is the operation of AES encrypting the 128-bit quantity x under the key K. AES(K)dec(x) is the corresponding decryption opteration. XOR(x,y) is the bitwise exclusive or of x and y. MSB(x) and LSB(y) are the most significant 64 bits and least significant 64 bits of x and y respectively.

If N is 1, a single AES operation is performed for wrap or unwrap. If N>1, then 6*N AES operations are performed for warp or unwrap.

The key wrap algorithm is as follows:

1. If N is 1:
   • B=AES(K)enc(0xA6A6A6A6A6A6A6A6|P(1))
   • C(0)=MSB(B)
   • C(1)=LSB(B)
   If N>1, perform the following steps:
2. Initialize variables:
   • Set A to 0xA6A6A6A6A6A6A6A6
   • Fori=1 to N,
     R(i)=P(i)
3. Calculate intermediate values:
   • Forj=0 to 5,
     • For i=1 to N,
       t= i + j*N
B=AES(K)enc(A|R(i))
A=XOR(t,MSB(B))
R(i)=LSB(B)
4. Output the results:
   • Set C(0)=A
   • For i=1 to N,
     C(i)=R(i)

The key unwrap algorithm is as follows:

1. If N is 1:
   • B=AES(K)dec(C(0)|C(1))
   • P(1)=LSB(B)
   • If MSB(B) is 0xA6A6A6A6A6A6A6A6, return success. Otherwise, return an integrity check failure error.
   If N>1, perform the following steps:
2. Initialize the variables:
   • A=C(0)
   • For i=1 to N,
     R(i)=C(i)
3. Calculate intermediate values:
   • For j=5 to 0,
     • For i=N to 1,
       t= i + j*N
B=AES(K)dec(XOR(t,A)|R(i))
A=MSB(B)
R(i)=LSB(B)
4. Output the results:
   • For i=1 to N,
     P(i)=R(i)
   • If A is 0xA6A6A6A6A6A6A6A6, return success. Otherwise, return an integrity check failure error.

For example, wrapping the data 0x00112233445566778899AABBCCDDEEFF with the KEK 0x000102030405060708090A0B0C0D0E0F produces the ciphertext of 0x1FA68B0A8112B447, 0xAEF34BD8FB5A7B82, 0x9D3E862371D2CFE5.

5.7 Message Digest

Message digest algorithms can be used in AgreementMethod as part of the key derivation, within RSA-OAEP encryption as a hash function, and in connection with the HMAC message authentication code method as described in [XML-DSIG].)

5.7.1 SHA1

Identifier:

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

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

5.7.2 SHA256

Identifier:

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

The SHA-256 algorithm [SHA] takes no explicit parameters. It is RECOMMENDED that XML encryption implementations implement SHA-256. An example of an SHA-256 DigestMethod element is:

   <DigestMethod
    Algorithm="http://www.w3.org/2001/04/xmlenc#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.7.3 SHA512

Identifier:

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

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

   <DigestMethod
    Algorithm="http://www.w3.org/2001/04/xmlenc#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.

5.7.4 RIPEMD-160

Identifier:

http://www.w3.org/2001/04/xmlenc#ripemd160 (OPTIONAL)

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

   <DigestMethod
    Algorithm="http://www.w3.org/2001/04/xmlenc#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.

5.8 Message Authentication

Identifier:

http://www.w3.org/2000/09/xmldsig# (RECOMMENDED)

XML Signature [XML-DSIG] is optional to implement for XML encryption applications. It is the recommended way to provide key based authentication.

5.9 Canonicalization

A Canonicalization of XML is a method of consistently serializing XML into an octet stream as is necessary prior to encrypting XML.

5.9.1 Inclusive Canonicalization

Identifiers:

http://www.w3.org/TR/2001/REC-xml-c14n-20010315 (OPTIONAL)

http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments (OPTIONAL)

Canonical XML [Canon] is a method of serializing XML which includes the in scope namespace and xml namespace attribute context from ancestors of the XML being serialized.

If XML is to be encrypted and then later decrypted into a different environment and it is desired to preserve namespace prefix bindings and the value of attributes in the "xml" namespace of its original environment, then the canonical XML with comments version of the XML should be the serialization that is encrypted

5.9.2 Exclusive Canonicalization

Identifiers:

http://www.w3.org/TR/2001/xml-exc-c14n# (OPTIONAL)

http://www.w3.org/TR/2001/xml-exc-c14n#WithComments (OPTIONAL)

Exclusive XML Canonicalization [Exclusive] serializes XML in such a way as to include to the minimum extent practical the namespace prefix binding and xml namespace attribute context inherited from ancestor elements.

It is the recommended method where the outer context of a fragment which was signed and then encrypted may be changed. Otherwise the validation of the signature over the fragment may fail because the canonicalization by signature validation may include unnecessary namespaces into the fragment.