Exploring XML Encryption, Part 1
Demonstrating the secure exchange of structured data
Currently, Transport Layer Security (TLS) is the de facto standard for secure communication over the Internet. TLS is an end-to-end security protocol that follows the famous Secure Socket Layer (SSL). SSL was originally designed by Netscape, and its version 3.0 was later adapted by the Internet Engineering Task Force (IETF) while they were designing TLS. This is a very secure and reliable protocol that provides end-to-end security sessions between two parties. XML Encryption is not intended to replace or supersede SSL/TLS. Rather, it provides a mechanism for security requirements that are not covered by SSL. The following are a two important areas not addressed by SSL:
- Encrypting part of the data being exchanged
- Secure sessions between more than two parties
With XML Encryption, each party can maintain secure or insecure states with any of the communicating parties. Both secure and non-secure data can be exchanged in the same document. For example, think of a secure chat application containing a number of chat rooms with several people in each room. XML-encrypted files can be exchanged between chatting partners so that data intended for one room will not be visible to other rooms.
XML Encryption can handle both XML and non-XML (e.g. binary) data. We'll now demonstrate a simple exchange of data, making it secure through XML Encryption. We'll then slowly increase the complexity of the security requirements and explain the XML Encryption schema and the use of its different elements.
A simple example of secure exchange of XML data
Suppose you want to send the XML file in Listing 1 to a publishing company. This file contains details of a book that you want to purchase. In addition, it also contains your credit card information for payment. Naturally, you would like to use secure communication for this sensitive data. One option is to use SSL, which secures the whole communication. The alternative is to use XML Encryption. As already mentioned, XML Encryption is not an alternative to SSL/TLS. If the application requires that the whole communication be secure, you'll use SSL. On the other hand, XML Encryption is the best choice if the application requires a combination of secure and insecure communication (which means that some of the data will be securely exchanged and the rest will be exchanged as is).
Listing 1. The sample XML file to be encrypted
<purchaseOrder> <Order> <Item>book</Item> <Id>123-958-74598</Id> <Quantity>12</Quantity> </Order> <Payment> <CardId>123654-8988889-9996874</CardId> <CardName>visa</CardName> <ValidDate>12-10-2004</ValidDate> </Payment> </purchaseOrder>
Note: We have intentionally kept the XML file in Listing 1 very simple. This helps in keeping our focus on encryption-related issues. Real-world XML files in collaborative commerce or Web services will be similar in structure but more verbose. WSDL (Web Services Definition Language) and SOAP (Simple Object Access Protocol) are XML-based grammars that are frequently used in B2B integration. Both WSDL and SOAP can use XML Encryption to provide secure communication across the enterprise. Visit the W3C for details about them (see Related topics).
Encrypting complete documents with XML Encryption
Listing 2 shows the resulting XML-encrypted file, in case you decide to encrypt the entire
XML document in Listing 1. Notice the
<CipherValue> tags. The actual encrypted data appears as contents of the
<CipherValue> tag. The complete
CipherData element appears within an
EncryptedData element. The
EncryptedData element contains the XML namespace used for encryption. For example, your original data before encryption was
XML and the official type definition by the Internet Assigned Numbers Authority (IANA) for
XML is http://www.isi.edu/in-notes/iana/assignments/media-types/text/xml.
This appears as the value of the
Type attribute. XML Encryption uses the type definitions by IANA for various popular data formats such as RTF, PDF, and JPG. Refer to their Web site for complete details (see Related topics). If you have special application
data types (perhaps your own DTDs or XSDs that belong to your company's content
management system), you can specify them in the
Type attribute of
EncryptedData element. The other attribute, xmlns, specifies the XML Encryption namespace that we used to encrypt the XML data.
Encrypting a single element with XML Encryption
You may want to encrypt only one element in Listing 1 -- for example, the
In this case, the result is illustrated in Listing 3. Compare Listing 2 and Listing 3 and you'll find the following differences:
- Listing 2 contains only XML Encryption's schema, while Listing 3 contains both XML Encryption as well as elements from the original data in Listing 1. In Listing 3, the XML Encryption is embedded inside the user's XML.
- Listing 3 also has a
<EncryptedData>, but its value is http://www.w3.org/2001/04/xmlenc#Element. We are no longer using the IANA type; instead, we are using the type that XML Encryption has specified.
- Note particularly the fragment #Element at the end that means EncryptedData -- this represents one element.
Encrypting the content of an element
Listing 4 will be the result if you want to encrypt only the content in
CardId, an element in Listing 1. This time, we have used http://www.w3.org/2001/04/xmlenc#Content as the
Type attribute value. We use this value whenever we have to encrypt only the content.
Encrypting non-XML data
What if you want to send, say, a JPEG file through XML Encryption? Listing 5 is a typical file that
will result. The complete JPEG file in an encrypted sequence of bytes
will appear as the content of the
Notice that there is only one difference between Listing 2 and Listing 5:
Type attribute of the
EncryptedData element. Listing 5 includes the
IANA type for the JPEG format. Similarly, you can encrypt any format by providing IANA values (refer to the IANA Web site, see Related topics).
Keys for XML Encryption
In Listings 1 through 5, we have demonstrated encryption, which is not possible without keys (see the sidebar Public, private, and secret keys). With XML Encryption, all key-related issues are divided into two parts:
- Exchange of keys (asymmetric encryption)
- Using keys that were previously exchanged (symmetric encryption)
This way, users can exchange keys and use them later.
Asymmetric keys for exchange of secret keys
In this scenario, one party sends its public key to a second party.
The second party uses this public key to encrypt its secret key.
This exchange of data is shown in Listing 6 (request) and Listing 7 (response). We will imagine Imran and Ali as the first party and second party, respectively, communicating with each other. Imran initializes
the public key exchange request and sends his public key in the element named KeyValue .
CarriedKeyName represents the name of the key that is being transported.
Note that the root element of this structure is
EncryptedKey, which contains
ds:KeyValue elements. The
ds: KeyInfo and
ds:KeyValue elements belong to the XML Digital Signature (ds:) namespace. XML
Encryption relies entirely on the XML Digital Signature specification for key exchange.
<ds:KeyValue> belong to the XML Digital
Signature specification namespace. Listing 7 is what Ali sends in response.
CipherValue element in Listing 7 contains a newly generated secret key,
which is encrypted with the public key of the first party. Looking closely at Listing 6 and Listing 7, you'll notice that both request and response contain an
EncryptedKey element. The
ds:KeyValue elements within the
EncryptedKey element carry the public key (Listing 6). On the other hand, the
CipherValue elements inside the
EncryptedKey element (Listing 7) will transport the secret (encrypted) keys. Also notice that the
EncryptedKey element always contains a
CarriedKeyName attribute to specify the name of the key it is carrying.
Using keys we have already exchanged in the past
In the previous section, we exchanged a secret key. We'll now use that key to encrypt data.
We will assume that Imran sends an XML message (Listing 8) in response to Listing 7 (recall that Listing 7 contains an encrypted secret key whose name is "Imran Ali").
Imran will decrypt this secret key with his (Imran's own) private key (as Ali encrypted this secret key with Imran's public key). Imran can encrypt the data he wants to send to Ali using this secret key and placing it inside the
CipherValue element in Listing 8.
ds:KeyInfo element in Listing 8 contains a
KeyName element. This combination refers to the name of the key that Imran uses for data encryption.
Figure 1 is a visual diagram showing this exchange of XML files for secure data exchange.
Figure 1. Sequence of key and data exchange with XML Encryption
Referring external encrypted data from our XML Encryption file
In Listings 5 and 7, the
CipherData element can appear within an
EncryptedData element or an
EncryptedKey element. We use a
CipherData element to refer to either the encrypted data (when it appears inside an
EncryptedData element) or the encrypted key
(when it appears inside an
EncryptedKey element). In both Listings 5 and 7, there is a
CipherValue child element inside the
CipherData element that contains the actual encrypted data.
We can also refer to external encrypted data or encrypted keys. This means that actual encrypted data or keys will be present somewhere else (perhaps somewhere on the Internet) and not inside our XML Encryption file. In this case we will use
CipherReference instead of the
CipherValue child element inside
CipherData. We'll refer to the actual encrypted data through a URI. This is shown in Listing 9.
Referencing a particular element of an external XML file
Listing 10 illustrates a variation of referring external XML files. Here we have referenced only a portion of the external file that the URI is pointing to. There is a
Transforms child element inside the
CipherReference element. This
Transforms element may contain a number of
Transform elements, each of which will contain a single XPath element. This XPath element specifies an XPath expression that refers to a particular node of the external XML document.
The DOM structure of our API
We have already demonstrated how to author XML Encryption files and exchange encrypted data. We will now propose a Java API for XML Encryption and provide a sample implementation. We will use DOM for this purpose.
Our DOM implementation consists of a set of classes (Listings 11 to 16). The
XmlEncryption class (Listing 11) is a wrapper for the rest of the classes, which means users of our API will only need to interact with this class. It uses the functionality of other classes internally.
Listing 11 is a wrapper class that can generate a complete XML encrypted file.
Listing 12 authors the
Listing 13 authors the
Listing 14 authors the
Listing 15 authors the
Listing 16 contains names of Algorithms as static integers and their corresponding namespaces as strings.
XmlEncryption class (Listing 11) contains various public Get/Set methods. The user will call Set methods to specify encryption parameters, which include the following:
- Name of the file to be encrypted
- Name of the resulting XML Encryption file
- Name of the algorithm for encryption
- Name of the key that we will use for encryption
- An ID for identification of
We have demonstrated the use of the
XmlEncryption class (Listing 11) through a
main () method. In the
main () method, we have created an instance of this class. The constructor instantiates DOM so that all underlying classes will use the same object.
This implementation only supports encryption of complete files, as illustrated in Listing 2. The
EncryptCompleteXmlFile () method will do this job by calling the following methods in a sequence:
GetEncryptedDataDoc()returns the object of the
EncryptedDataclass (Listing 12). It contains the structure of the
GetEncryptionMethodDoc()returns the Document object, which contains the XML structure corresponding to the
EncryptionMethodclass (Listing 13) to author XML.
Documentobject, which contains the XML structure corresponding to KeyInfo element.
GetKeyInfoDoc()uses the object of
GenericKeyInfoclass (Listing 14) to author the XML. This class only provides the minimum necessary functionality (support for
KeyValueelements) you will inherit from
GenericKeyInfoclass to provide the complete functionality, which includes support for X509 Certificates, PGP Data, etc.
ReadFile()fetches the data (complete XML file) that we want to encrypt.
GetEncryptedData()for the time being is not doing anything. We'll implement this method in the next part of this article. It is supposed to create the encrypted form of XML data that we fetched in step 4. We have briefly discussed our encryption strategy in the last section (Java Cryptographic Architecture).
GetCipherDataDoc()takes the encrypted data as an argument and returns the Document Object containing the
GetCipherDataDoc()uses the Object of
CipherDataclass (Listing 12) to author XML.
- At the end,
addChild()method of Object of
EncryptedData(Listing 15) is called thrice, which will take the Document Objects of steps 2, 3, and 6 and adds them to the
<EncryptedData>structure, which is the parent of all of them.
SaveEncryptedFile()saves the completed XML Encryption file.
AlgoNames (Listing 16) is a helper class that only specifies namespace declarations required by XML Encryption.
XmlEncryption class (Listing 11) can also be used as a server-side component. In the next part of this series, we'll demonstrate its use inside independent as well as server-side applications.
The set of classes that we have developed only performs DOM-based XML authoring. We need to implement cryptographic functionality as well. We will now try to form a strategy for cryptographic support. For this purpose, we need to study the Java Cryptographic Architecture (JCA).
The Java Cryptographic Architecture (JCA)
Java offers complete support for cryptography. For this purpose, there are several packages inside J2SE, covering all the main features of security architecture such as access controls, signatures, certificates, key pairs, key stores, and message digests.
The primary principle of JCA design is to separate cryptographic concepts from algorithmic implementations, so that different vendors can offer their tools within the JCA framework.
JCA Engine classes
JCA defines a series of Engine classes, where each Engine provides a cryptographic function. For example, there are several different standards of MD (Message Digest) algorithm. All these standards differ in the implementation, but at the Engine API level they are all the same. Different vendors are free to provide implementations of specific algorithms.
Java Cryptographic Extension (JCE)
All independent (third party) vendor implementations of cryptographic algorithms are called Java Cryptographic Extensions (JCEs). Sun Microsystems has also provided an implementation of JCE. Whenever we use JCE, we need to configure it with JCA. For this, we need to do the following:
1. Add the address of the jar file to configure the provider (all JCE implementations are called providers) in the
CLASSPATH environment variables.
2. Configure the provider in the list of your approved providers by editing the java.security file. This file is located in JavaHome/jre/lib/security folder. The following is the syntax to specify the priority:
security.provider.<n>=<masterClassName>. Here, n is the priority number (1, 2, 3, etc.).
MasterClassName is the name of master class to which the engine classes will call for a specific algorithm implementation. The provider's documentation will specify its master class name. For example, consider the following entries in a java.security file:
These entries mean that the engine class will search for any algorithm implementation in the above mentioned order. It will execute the implementation found first. After these simple steps, we are all set to use JCA/JCE in our XML Encryption application.
Using JCA and JCE in our implementation of XML Encryption
GetEncryptedData() function in our wrapper class,
XmlEncryption (Listing 11), is the place to handle all JCA/JCE-related issues. Currently this method only returns the string "This is Cipher Data". We have not yet written JCA/JCE-related classes. This method takes the unencrypted data and returns it as an encrypted string. We will handle all the algorithm- and key-related issues in this method after writing the wrapper classes for JCA/JCE.
Next time: In our next installment of this series of articles, we will discuss and implement the details of cryptography. We'll demonstrate the working of encryption and decryption classes and their interaction with parsing logic, and present applications of XML Encryption in Web services.
- Read "Exploring XML Encryption, Part 2" of this two-part series of articles on XML Encryption by Bilal Siddiqui (developerworks, August 2002).
- Visit W3C to see official details of XML Encryption Requirements and XML Encryption Processing and Syntax.
- Check out news about XML Encryption at OASIS/Robin Cover's XML Cover Pages.
- IBM's toolkits for XML Encryption is available for download at alphaWorks.
- Check what's happening at SUN's community process for XML Encryption.
- We mentioned IANA in this article. Visit IANA's Web site to check type definitions for popular data formats.