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 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. 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.
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="OAEPparams" minOccurs="0" type="OAEPparamsType">
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
<!-- (0,unbounded) elements from (1,1) external namespace -->
</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. (Schema does not provide
a facility for expressing conditionality of child element occurrance based on
attribute value.) The presence of any child element under
EncryptionMethod which is not permitted by the algorithm
MUST be treated as an error.
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 IV is encoded with the data 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.
The triple DES algorithm is described in FIPS 46-3 [DES] 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 (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.
ARCFOUR is an fast simple stream encryption algorithm that is compatible with
RSA Security'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 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 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 OAEPparams. 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
OAEPparams 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"/>
<OAEPparams> foo </OAEPparams>
<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 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.
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 agreement to 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 OriginatorKeyInfo
parameter child of an AgreementMethod element while that associated
with the recipient is indicated by an optional RecipientKeyInfo.
The AgreementMethod element
appears as the content of a KeyInfo since,
like other KeyInfo
children, it yields a key. This KeyInfo is in turn child of and
EncryptedData
or EncryptedKey and, in fact,
the Type attribute in this grandparent EncryptedData or
EncryptedKey is an implicit parameter
to the key agreement computation. 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>
<AgreementMethod Algorithm="Example:Agreement/Algorithm">
<Nonce> foo </Nonce>
<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256">
<OriginatorKeyInfo>
<KeyValue>...originator...</KeyValue>
</OriginatorKeyInfo>
<RecipientKeyInfo>
<KeyValue>...recipient...</KeyValue>
</RecipientKeyInfo>
</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="OriginatorKeyInfo" minOccurs="0" type="ds:KeyInfoType">
<element name="RecipientKeyInfo" 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 [ESDH].
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 [CMS-Algorithms]. 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 (encrypts) a key (the wrapped key, WK)
under a 3DES key-encryption-key (KEK):
The following algorithm unwraps (decyrpts) a key:
The above specification is that given in [CMS-Algorithms].
Implementation of AES key wrap as specified 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]
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]
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]
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 applications implement Canonical XML With Comments and they MAY also implement Canonical XML (without comments).