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();
Element e = getElement(d, ELEMENT_NAME); // source
try {
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
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();
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");
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();
Element e = getElement(d, ELEMENT_NAME); // source
try {
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
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();
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");
cipher = XMLCipher.getInstance(XMLCipher.AES_128);
cipher.init(XMLCipher.DECRYPT_MODE, key);
d = cipher.doFinal(d, e);
} catch (Exception ex) {
...
}