| This section describes the sequence of operations for XML encryption and decryption processing. The XML Encryption Recommendation [XMLENC] attempts to define the boundary between the application and an encrypter or decrypter, but it remains flexible because some steps may be carried out by either one. Discussion of cryptographic and directly related processing, where XMLDSIG is used as an analogy, appears in the subsections "Encryption Processing" and "Decryption Processing." Discussion of other "application" processing appears in the subsections "Pre-encryption Processing," "Post-encryption Processing," "Pre-decryption Processing," and "Post-decryption Processing." 15.4.1 Encryption The following steps need to be performed for successful XML encryption. Pre-encryption Processing Obtain the data to be encrypted as an octet sequence. If the data to be directly encrypted is an XML element or XML element content, the octet sequence is a UTF-8 encoded string representation of the element or its content, respectively. To obtain this representation, you can use a standardized XML canonicalization algorithm (see Chapter 9). Consider using Canonical XML to serialize the data, especially if the XML will be decrypted in an environment where different namespace declaration or xml namespace attributes are in scope this difference may change the meaning of the data in an undesirable way. For many purposes, almost any printing to parseable UTF-8 encoded XML will work well. Other processing may be done, such as compressing the octet sequence. To assure interoperability, the Type attribute of the resulting EncryptedData or EncryptedKey must indicate that such processing has taken place; the processing can then be undone upon decryption. You also need to ensure that the recipient will implement your Type. Encryption Processing For each data item or key to be encrypted, do the following: -
Select the algorithm (and parameters) to use in encrypting the item. -
Obtain the encryption keying material. If the key will be encrypted, recursively apply this process to create an EncryptedKey element. If the key will be represented, construct the appropriate ds:KeyInfo element. If the key was encrypted, the ds:KeyInfo may have the EncryptedKey as a child or may point to it with a ds:RetrievalMethod or with a ds:KeyName referring to a CarriedKeyName in the EncryptedKey. If the key resulted from a key agreement algorithm, the ds:KeyInfo will have or point to an AgreementMethod child, which may itself have keying information children. -
Obtain the octet sequence to encrypt. -
Encrypt the sequence using the key and encryption algorithm. If the algorithm requires it, prefix the cipher text with the appropriate initialization vector (IV). -
Construct the CipherData element. If the octet sequence produced in this step will be enveloped, it is encoded in base-64 and becomes the content of a CipherValue element. If you plan to store the octet sequence produced in this step elsewhere, construct a CipherReference element by which the recipient can retrieve it. (This step may require constructing a Transforms element.) -
Build the EncryptedData or EncryptedKey element. This element will include the CipherData child element. It may also include EncryptionMethod, KeyInfo, and/or EncryptionProperties child elements, as well as Type, Id, MimeType, and/or Encoding attributes. An EncryptedKey element may include ReferenceList and/or CarriedKeyName child elements and/or a Recipient attribute. (These items are not permitted with EncryptedData.) Post-encryption Processing If the data being encrypted consists of an XML element or XML element content, the processing removes the unencrypted data and replaces it with the new XML structure using the same encoding as the parent XML document. If the data being encrypted consists of an external octet sequence, you probably want to use the EncryptedData element by including or ref erencing the encrypted data as the top-level element in a new XML document or insert it into another XML document or database (this processing is application dependent). 15.4.2 Decryption Perform the following steps for successful XML decryption. Pre-decryption Processing To decrypt each EncryptedData or EncryptedKey, parse the element and obtain the EncryptionMethod, KeyInfo, and CipherData elements from it or from the application. Decryption Processing Determine the encryption algorithm and parameters. Obtain the decryption keying information. If an AgreementMethod represents this information, the encryption algorithm and parameters may affect the resulting key, particularly its size. If the decryption keying information is either represented by an EncryptedKey as the child of the KeyInfo element or pointed to by a RetrievalMethod or named by a KeyName, recursively apply this process to obtain the key. Obtain the data to decrypt. If CipherData has a CipherValue child, base-64 decode its contents. If CipherData has a CipherReference child, either retrieve the data and apply any Transforms, or use an equivalent method for the application's purposes for example, by retrieving a copy of the cipher text from a local cache. If the encryption algorithm and parameters specify it, strip any IV from the data and provide it to the algorithm. Decrypt the cipher data with the encryption algorithm, parameters, and keying material. Post-decryption Processing If the plain text is a key, save it for processing the associated EncryptedData or EncryptedKey. When the data is XML, the resulting octets are interpreted as an UTF-8 encoded string of XML characters representing an element or element content. If the plain text comes from an EncryptedData structure and the Type is "Element" or "Content," use the resulting characters to replace the EncryptedData element. If the target document is not in UTF-8, re-encode the characters with the encoding of the parent XML document. For other Type values (e.g., proprietary compressed data), handle them according to the Type. If the Type is unknown, the application should indicate an error. 15.4.3 XML Encryption The preceding specification presumes that the data to be encrypted are processed as an octet sequence. When encrypting XML, the application is responsible, as part of pre-encryption processing, for serializing the XML into an octet sequence that will be useful subsequent to decryption. For instance, if the application wishes to encode/compress the data into some XML packaging format, it needs to marshal the XML accordingly and identify the resulting type with the optional Type attribute of the EncryptedData element. The likelihood of interoperable decryption and subsequent use will depend on the decrypting application's support for a given Type. In addition, if processing of the data will occur both before and after decryption (e.g., XML Signature [XMLDSIG] validation or XSLT Transform [XSLT]), the encrypter must be careful to preserve information necessary for that process's success. |
