8 Oracle XML Security

8.2.2.1 Setting the CLASSPATH on Windows

If you are installing Oracle XML Security on Windows, set your CLASSPATH as follows:

1. In your Windows Control Panel, select System.

2. In the System Properties dialog, select the Advanced tab.

3. Click Environment Variables.

4. In the User Variables section, click New to add a CLASSPATH environment variable for your user profile. If a CLASSPATH environment variable already exists, select it and click Edit.

5. Add the full path and file names for all the required jar and class files to the CLASSPATH.

   For example, your CLASSPATH might look like this:

   %CLASSPATH%;C:\ORACLE_HOME\jlib\osdt_core.jar;
   C:\ORACLE_HOME\jlib\osdt_cert.jar;
   C:\ORACLE_HOME\jlib\osdt_xmlsec.jar;
   C:\ORACLE_HOME\jlib\jaxen.jar;
   
   

6. Click OK.

8.2.2.2 Setting the CLASSPATH on UNIX

On UNIX, set your CLASSPATH environment variable to include the full path and file name of all the required jar and class files. For example:

setenv CLASSPATH $CLASSPATH:$ORACLE_HOME/jlib/osdt_core.jar:\
$ORACLE_HOME/jlib/osdt_cert.jar:\
$ORACLE_HOME/jlib/osdt_xmlsec.jar:\
$ORACLE_HOME/jlib/jaxen.jar:

8.3.1.1 The oracle.security.xmlsec.dsig.XSSignature Class

This class represents the top-level Signature element of the XML Signature schema. Creating an instance of this class is the first step in creating a new signature or in verifying an existing signature.

To create a new signature, you create a new instance of the XSSignature class by calling the static newInstance() method:

XSSignature sig = XSSignature.newInstance("MySignatureID");

To obtain Signature elements from an XML document to verify a signature, you first obtain an org.w3c.dom.NodeList object that contains all the Signature elements as instances of org.w3c.dom.Node. You can then iterate through the NodeList and convert each node to an instance of XSSignature, as the following example illustrates:

Document doc = Instance of org.w3c.dom.Document;
// Get list of all XML Signatures in the document.
NodeList sigList = doc.getElementsByTagNameNS(XMLURI.ns_xmldsig, "Signature");
if (sigList.getLength() == 0)
    System.err.println("No XML-DSIG Signature elements found.");

// Convert each org.w3c.dom.Node object to a oracle.security.xmlsec.dsig.XSSignature
// object and perform verification
for (int s = 0, n = sigList.getLength(); s < n; ++s)
{
    XSSignature sig = new XSSignature((Element)sigList.item(s));
    //Perform signature verification for this signature
    ...
}

8.3.1.2 The oracle.security.xmlsec.dsig.XSSignedInfo Class

This class represents the SignedInfo element of the XML Signature schema. As with XSSignature, you must use this class to both create and verify signatures. In signature creation, you create an instance of this class with the following code:

XSignature sig = XSSignature.newInstance("MySignatureID");
XSSignedInfo si = sig.createSignedInfo("MySignedInfoID");

When performing verification, you first obtain an instance of XSSignature as shown in Example 8-2, then obtain the SignedInfo element from the top-level Signature with the following code:

XSSignature sig;

//Instance of XSSignature is obtained (Example 8-2)

//Get SignedInfo
XSSignedInfo si = sig.getSignedInfo();

8.3.1.3 The oracle.security.xmlsec.dsig.XSReference class

This class represents the Reference element of the XML Signature schema. You must use this class when creating and verifying signatures. In signature creation, you create an instance of this class with the following code:

XSignature sig = XSSignature.newInstance("MySignatureID");
String uri = "the URI of the data object you want to reference";
String type = "the type of the data object you want to reference (optional)";
XSAlgorithmIdentifier digestAlg = 
    the digest algorithm identifier (e.g., XMLURI.alg_sha1);
XSReference ref = 
    sig.createReference("MyReferenceID", uri, type, digestAlg);

When performing verification, you first obtain an instance of XSSignature as shown in Example 8-2, then obtain the Reference elements from the top-level Signature with the following code:

XSSignature sig;

//Instance of XSSignature is obtained (Example 8-2)

//Get Vector of reference objects
Vector refs = sig.References();

8.3.1.4 The oracle.security.xmlsec.dsig.XSKeyInfo class

This class represents the KeyInfo element of the XML Signature schema. You may use this class for signature creation as well as signature verification.

In signature creation, you create an instance of this class with the following code:

XSignature sig = XSSignature.newInstance("MySignatureID");
XSKeyInfo si = sig.createKeyInfo("MyKeyInfoID");

A KeyInfo element can have various child elements that contain the actual key data. The classes that support these KeyInfo children are found in the oracle.security.xmlsec.keys package.

For example, to create an RSAKeyValue element containing a signer's public key, you can use the following code:

X509 cert = An instance of the oracle.security.crypto.cert.X509 class;
XSKeyInfo ki = An instance of the XSKeyInfo class;
RSAKeyValue rsaKeyValue = ki.createKeyValue(cert.getPublicKey());
ki.addKeyInfoData(rsaKeyValue);

When performing verification, you first obtain an instance of XSSignature as shown in Example 8-2, then obtain the KeyInfo element from the top-level Signature with the following code:

XSSignature sig;

//Instance of XSSignature is obtained (Example 8-2)

//Get KeyInfo
XSSignedInfo si = sig.getKeyInfo();

8.3.1.5 The oracle.security.xmlsec.enc.XEEncryptedData class

This class represents the EncryptedData element of the XML encryption schema. You must create an instance of this class when encrypting or decrypting arbitrary data or an entire XML document.

When encrypting, you create an instance of this class with the following code:

Document doc = Instance of org.w3c.dom.Document;
String dataType = Either XMLURI.obj_content (content only) or
    XMLURI.obj_Element (entire element);
XEEncryptedData encData = 
    XEEncryptedData.newInstance(doc, "MyEncryptedDataID", dataType);

When decrypting, you can obtain the EncryptedData elements from an XML document with the following code:

Document doc = Instance of org.w3c.dom.Document;

// Get list of all XML EncryptedData elements in the document.
NodeList encDataList = 
    doc.getElementsByTagNameNS(XMLURI.ns_xmlenc, "EncryptedData");
if (encDataList.getLength() == 0)
    System.err.println("No XML-ENC EncryptedData elements found.");

// Convert each org.w3c.dom.Node object to a 
// oracle.security.xmlsec.enc.XEEncryptedData
// object and perform decryption
for (int s = 0, n = encDataList.getLength(); s < n; ++s)
{
    XEEncryptedData = new XEEncryptedData((Element)encDataList.item(s));

    //TODO: Perform decryption of the encrypted data 
    //contained in this element
}

8.3.1.6 The oracle.security.xmlsec.enc.XEEncryptedKey Class

This class represents the EncryptedKey element of the XML Encryption Schema. You can use an instance of this class to encrypt and decrypt cryptographic key material.

When encrypting a key, you create an instance of this class with the following code:

Document doc = Instance of org.w3c.dom.Document;
XEEncryptedKey encKey = XEEncryptedKey.newInstance(doc, "MyEncryptedKeyID");

When decrypting a key, you first obtain the XEEncryptedData from an XML document using the code in Example 8-11, then obtain the EncryptedKey elements with the following code:

XEEncryptedData encData;
//Instance of XEEncryptedData is obtained (See Example 8-11

//Get Vector of XEEncryptedKey objects
XEKeyInfo ki = encData.getKeyInfo();
Vector encKeys;
if (ki != null)
    Vector encKeys = encData.getEncryptedKeys();

8.3.1.7 The oracle.security.xmlsec.enc.XEEncryptionMethod Class

This class represents the EncryptionMethod element of the XML encryption schema. It contains the algorithm and parameters used in encrypting data or encrypting a key.

When encrypting, you create an instance of this class with the following code:

String algURI = "String containing the URI of the encryption algorithm";
XEEncryptedObject encObj = Instance of XEEncryptedData or XEEncryptedKey;
XEEncryptionMethod em = encObj.createEncryptionMethod(algURI);

When decrypting, you first obtain an EncryptedData element using Example 8-11, or an EncryptedKey element using Example 8-13, then obtain an EncryptionMethod element with the following code:

XEEncryptedObject encObj;

//Obtain instance of XEEncryptedData (see class example earlier) or
//XEEncryptedKey (see class example earlier)
XEEncryptionMethod em = encObj.getEncryptionMethod();

8.3.1.8 The oracle.security.xmlsec.enc.XECipherData Class

This class represents the CipherData element that provides the encrypted data. It either stores the encrypted data in the CipherValue element or refers to a source containing the data through the CipherReference element. When performing encryption, you create an instance of XEEncryptedData or XEEncryptedKey, then create an instance of XECipherData with the following code:

XEEncryptedObject encObj;

//Create an instance of XEEncryptedData (see class example earlier)
//XEEncryptedKey (see example 8-12)
XECipherData cd = encObj.createCipherData();

When decrypting, you first obtain an EncryptedData element using Example 8-11, or an EncryptedKey element using Example 8-13, then obtain an instance of an XECipherData element with the following code:

XEEncryptedObject encObj;

//Obtain an instance of XEEncryptedData (see example 8-11) or
//XEEncryptedKey (see example 8-13)
XECipherData cd = encObj.getCipherData();

8.3.2.1 The oracle.security.xmlsec.util.XMLURI Interface

This interface defines URI string constants for algorithms, namespaces, and objects. It uses the following naming convention:

• Algorithm URIs begin with "alg_".

• Namespace URIs begin with "ns_".

• Object type URIs begin with "obj_".

8.3.2.2 The oracle.security.xmlsec.util.XMLUtils class

This class contains static utility methods for XML and XML-DSIG. Methods frequently used in applications include the createDocBuilder(), createDocument(), toBytesXML(), and toStringXML() methods.