A short tutorial

This short tutorial is just enough to get your feet wet. This document is still a work in progress. Also, please keep in mind that this is beta software, and allthough it has been tested to some degree, it is by no means production quality software. An area that is particularly grey, is that of interoperability. Numerous other xml encryption libraries exist, but, it is mostly comercial libraries which cost money (of course, its comercial...). As a result of that, this library has not been tested against the major xml encryption implemenations available and the level of interoperabillity is not known.

Before you begin

Have you checked out the resources and dependencies pages? If not, I suggest you do that. It is listed above the documentation section for a reason. I am convinced that you will have a lot less stress if you familiarize yourself with the contents of the aforementioned pages first.

Introduction

To perform encryption or decryption operations, you'll need an XMLCipher, a DOM representation of an XML file and some cryptographic helpers. Youre import section will look something like this:

import java.security.Key;
import javax.crypto.SecretKey;
import javax.crypto.SecretKeyFactory;
import javax.crypto.spec.DESedeKeySpec;
import javax.crypto.spec.SecretKeySpec;
...
import org.apache.xml.security.encryption.XMLCipher;
...
import org.w3c.dom.Document;
import org.w3c.dom.Element;

Key, SecretKey, SecretKeyFactory, DESedeKeySpec and SecretKeySpec are used to generate secret keys. You will most propably need all the Key-related classes. XMLCipher will perform the encryption/decryption operations and Document and Element supply context and a source for the encryption/decryption operation.

This following sections will illustrate how to encrypt an element using the Tripple DES and AES algorithms.

Encryption

The basic steps you need to perform to encrypt an Element is:

Get hold of a DOM representation (Document) of an XML file,
generate a Key,
initialize the XMLCipher,
identify and retrieve an DOM Element from the Document and
encrypt the Element.

The pseudo code for the aforementioned steps would look something like this:

Document d =
getDocumentFromSomewhere();

Key k = generateKeySomehow();
XMLCipher xmlCipher = XMLCipher.init(INIT_FOR_ENC, k, ...);
Element e = d.getElementSomehow();
d = xmlCipher.doFinal(d, e);

The final step in the encryption operation will return the initial document but, the element that was encrypted during the encryption operation will be replaced by its encrypted counterpart.

Tripple DES

The following code fragment illustrates how to encrypt an Element using the DESede algorithm.

Document d = getDocument();              // context
Element e = getElement(d, ELEMENT_NAME); // source

try {
    // prepare for encryption
    byte[] passPhrase = "24 Bytes per DESede key!".getBytes();
    DESedeKeySpec keySpec = new DESedeKeySpec(passPhrase);
    SecretKeyFactory keyFactory = SecretKeyFactory.getInstance("DESede");
    SecretKey key = keyFactory.generateSecret(keySpec); // generate a DESede Key

    // encrypt
    cipher = XMLCipher.getInstance(XMLCipher.TRIPLEDES);
    cipher.init(XMLCipher.ENCRYPT_MODE, key);
    d = cipher.doFinal(d, e);
} catch (Exception ex) {
    ...
}

AES

The following code fragment shows how to encrypt and Element using the AES algorithm.

Document d = getDocument();              // context
Element e = getElement(d, ELEMENT_NAME); // source

try {
    byte[] bits128 = {
        (byte) 0x10, (byte) 0x11, (byte) 0x12, (byte) 0x13,
        (byte) 0x14, (byte) 0x15, (byte) 0x16, (byte) 0x17,
        (byte) 0x18, (byte) 0x19, (byte) 0x1A, (byte) 0x1B,
        (byte) 0x1C, (byte) 0x1D, (byte) 0x1E, (byte) 0x1F};
    Key key = new SecretKeySpec(bits128, "AES");

    // encrypt
    cipher = XMLCipher.getInstance(XMLCipher.AES_128);
    cipher.init(XMLCipher.ENCRYPT_MODE, key);
    d = cipher.doFinal(d, e);
} catch (Exception ex) {
    ...
}

Decryption

The basic steps you need to perform to decrypt an Element is:

Get hold of a DOM representation (Document) of an XML file,
generate a Key,
initialize the XMLCipher,
identify and retrieve an DOM Element from the Document and
decrypt the Element.

The pseudo code for the aforementioned steps would look something like this:

Document d =
getDocumentFromSomewhere();

Key k = generateKeySomehow();
XMLCipher xmlCipher = XMLCipher.init(INIT_FOR_DEC, k, ...);
Element e = d.getElementSomehow();
d = xmlCipher.doFinal(d, e);

The final step in the encryption operation will return the initial document but, the element that was decrypted during the decryption operation will be replaced by its decrypted counterpart.

Tripple DES

The following code fragment illustrates how to decrypt an Element using the DESede algorithm.

Document d = getDocument();              // context
Element e = getElement(d, ELEMENT_NAME); // source

try {
    // prepare for decryption
    byte[] passPhrase = "24 Bytes per DESede key!".getBytes();
    DESedeKeySpec keySpec = new DESedeKeySpec(passPhrase);
    SecretKeyFactory keyFactory = SecretKeyFactory.getInstance("DESede");
    SecretKey key = keyFactory.generateSecret(keySpec); // generate a DESede Key

    // encrypt
    cipher = XMLCipher.getInstance(XMLCipher.TRIPLEDES);
    cipher.init(XMLCipher.DECRYPT_MODE, key);
    d = cipher.doFinal(d, e);
} catch (Exception ex) {
    ...
}

AES

The following code fragment shows how to encrypt and Element using the AES algorithm.

Document d = getDocument();              // context
Element e = getElement(d, ELEMENT_NAME); // source

try {
    byte[] bits128 = {
        (byte) 0x10, (byte) 0x11, (byte) 0x12, (byte) 0x13,
        (byte) 0x14, (byte) 0x15, (byte) 0x16, (byte) 0x17,
        (byte) 0x18, (byte) 0x19, (byte) 0x1A, (byte) 0x1B,
        (byte) 0x1C, (byte) 0x1D, (byte) 0x1E, (byte) 0x1F};
    Key key = new SecretKeySpec(bits128, "AES");

    // encrypt
    cipher = XMLCipher.getInstance(XMLCipher.AES_128);
    cipher.init(XMLCipher.DECRYPT_MODE, key);
    d = cipher.doFinal(d, e);
} catch (Exception ex) {
    ...
}