10 Oracle Web Services Security

10.2.2.1 Setting the CLASSPATH on Windows

To set the CLASSPATH on Windows:

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 of the required jar 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\osdt_saml.jar;
   C:\ORACLE_HOME\jlib\jaxen.jar;
   C:\ORACLE_HOME\jlib\osdt_wss.jar;
   
   

6. Click OK.

10.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 of 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/osdt_saml.jar:\
$ORACLE_HOME/jlib/jaxen.jar:\
$ORACLE_HOME/jlib/osdt_wss.jar:

10.3.1.1 The oracle.security.xmlsec.wss.WSSecurity Class

The oracle.security.xmlsec.wss.WSSecurity class represents the top-level security element of the WSS SOAP Message Security schema. Creating an instance of this class is the first step in creating a new security header or in validating an existing security header.

To create a new security header, you create a new instance of the WSSecurity class by calling the static newInstance() method:

WSSecuritysig = WSSecurity.newInstance("MySecurityHeaderID");

Example 10-1 shows how to obtain security elements from an XML document in order to perform security processing:

1. Obtain an org.w3c.dom.NodeList object that contains all the security elements as instances of org.w3c.dom.Node.

2. Iterate through the NodeList and convert each node to an instance of WSSecurity.

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

// Get list of all WSS Security elements in the document.
NodeList secList = 
    doc.getElementsByTagNameNS(WSSURI.ns_wsse, "Security");
if (secList.getLength() == 0)
    System.err.println("No wsse:Security elements found.");

// Convert each org.w3c.dom.Node object to an 
// oracle.security.xmlsec.wss.WSSecurity object and perform verification
for (int s = 0, n = secList.getLength(); s < n; ++s)
{
    WSSecurity sec = new WSSecurity((Element)sigList.item(s));

    //Process the wsse:Security header
    ...
}

10.3.1.2 The oracle.security.xmlsec.wss.soap.WSSOAPEnvelope Class

The oracle.security.xmlsec.wss.soap.WSSOAPEnvelope class represents the SOAP message. As with WSSecurity, you must use this class to create SOAP messages as well as for parsing and validation.

To create a SOAP message, you can create an instance of this class with the code shown in Example 10-2:

WSSOAPEnvelope env = 
    new WSSOAPEnvelope.newInstance(XMLUtils.createDocBuilder());
WSSecurity mySecHdr ......
env.addSecurity(mySecHdr);

When processing the message, you can obtain the Security element from the top-level SOAP message with the code shown in Example 10-3:

WSSOAPEnvelope env;

//Get List of Security headers
ArrayList l = (ArrayList)senv.getSecurity(null, false);
WSSecurity sec = (WSSecurity)l.get(0);
//Get List of Encrypted Keys
ArrayList r = (ArrayList) sec.getEncryptedKeys();
XEEncryptedKey xk = (XEEncryptedKey) r.get(0);
//Decrypt and Replace message contents
PrivateKey pk .... // Decryption Key
sec.decrypt (xk, pk);

10.3.1.3 The oracle.security.xmlsec.wss.WSSElement Class

oracle.security.xmlsec.wss.WSSElement is the base class for WSS Security elements. It supports reference elements with local Id and wsu:Id attributes for referencing them. All WSS schema elements, including tokens, extend this element.

10.3.2.1 The oracle.security.xmlsec.wss.utils.WSSURI Interface

The oracle.security.xmlsec.wss.utils.WSSURI interface defines URI string constants for algorithms, namespaces, and objects.

10.3.2.2 The oracle.security.xmlsec.wss.utils.WSSTokenUtils Class

The oracle.security.xmlsec.wss.utils.WSSTokenUtils class contains static utility methods for WSS security token. Some of the methods that may be frequently used in an application include:

• createSecurityToken()

• createSecurityTokenReference()

• createUsernameToken()

• createBinarySecurityToken()

• createBinarySecurityEncoder()

• createTimestamp()

10.3.2.3 The oracle.security.xmlsec.wss.utils.WSSUtils Class

The oracle.security.xmlsec.wss.utils.WSSUtils class contains static utility methods for WSS. Some methods that may be frequently used in applications include:

• addWsuIdToElement()

• createTextFromChild()

• insertChildElementWithText()

• prependChild()

• encodeBinary()

• decodeBinary()