Skip Headers

Oracle® Security Developer Tools Reference 10g Release 3 (10.1.3) B25372-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 10 Oracle Web Services Security

Oracle Web Services Security provides a framework of authorization and authentication for interacting with a web service using XML-based messages. This chapter provides information about key features and benefits of Oracle Web Services Security, and describes how to install and use the SDK.

This chapter contains these topics:

- Oracle Web Services Security Features and Benefits

- Setting Up Your Oracle Web Services Security Environment

- Classes and Interfaces

- The Oracle Web Services Security API Reference

## 10.1 Oracle Web Services Security Features and Benefits

Oracle Web Services Security is a pure Java solution which provides the following features:

- Support for the SOAP Message Security standard

- Support for the Username Token Profile standard

- Support for the X.509 Certificate Token Profile standard

- Support for the SAML Assertion Token standard

### 10.1.1 Oracle Web Services Security Packages

The Oracle Web Services Security library contains the following packages:

Table 10-1 Packages in the Oracle Web Services Security Library

Package | Description
--- | ---
oracle.security.xmlsec.wss | Contains general-purpose Oracle Web Services Security classes, including interfaces for token and reference creation and validation
oracle.security.xmlsec.wss.encoding | Contains classes for encoding and decoding algorithms required to support Web Services processing
oracle.security.xmlsec.wss.saml | Contains core classes supporting SAML assertion tokens
oracle.security.xmlsec.wss.soap | Contains core classes supporting the creation and parsing of SOAP messages with WSS security headers
oracle.security.xmlsec.wss.transforms | Contains classes implementing the transformation algorithms defined in Oracle Web Services Security
oracle.security.xmlsec.wss.username | Contains classes supporting the creation and parsing of username tokens
oracle.security.xmlsec.soap | Contains SOAP utility classes
oracle.security.xmlsec.wss.x509 | Contains core classes supporting X.509 certificate tokens
oracle.security.xmlsec.wss.utils | Contains Oracle Web Services Security utility classes

### 10.1.2 Related Documentation

The following resources provide more information about Web Services Security:

- OASIS WSS SOAP Message Security Specification

- OASIS WSS Username Token Profile Specification

- OASIS WSS X.509 Certificate Token Profile Specification

- OASIS WSS SAML Assertion Token Profile Specification

See Also: Links to these documents are available in Appendix A, "References".

## 10.2 Setting Up Your Oracle Web Services Security Environment

This section explains how to set up your environment for Oracle Web Services Security. It contains these topics:

- System Requirements for Oracle Web Services Security

- Setting the CLASSPATH Environment Variable

### 10.2.1 System Requirements for Oracle Web Services Security

In order to use Oracle Web Services Security, you must have the following components:

- Java Development Kit (JDK) version 1.2.2 or higher

- A JAXP-compatible XML parser and XSLT processor.

Oracle Web Services Security has been tested with the following implementations:

- Apache Xalan-Java (with Xerces-J)

- Oracle XDK for Java

For questions regarding compatibility with other parsers, visit `http://www.oracle.com/technology/documentation`.

### 10.2.2 Setting the CLASSPATH Environment Variable

Your `CLASSPATH` environment variable must contain the full path and file names to all of the required jar and class files. Make sure the following items are included in your `CLASSPATH`:

- `osdt_core.jar`

- `osdt_cert.jar`

- `osdt_xmlsec.jar`

- `osdt_saml.jar`

- The `jaxen.jar` file (Jaxen XPath engine, included with your Oracle XML Security distribution)

  Note: Oracle XML Security relies on the Jaxen XPath engine for XPath processing. Note that the Jaxen library included in this distribution is a modified version of the Jaxen 1.0 FCS release. If your `CLASSPATH` also includes an earlier Jaxen release, you must ensure that the Oracle XML Security version appears first.

- `osdt_wss.jar`

- The appropriate XML parser and XSLT processor implementations, unless you have installed them in your JRE's /lib/ext or /lib/endorsed directory

#### 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 Classes and Interfaces

This section describes classes and interfaces in the Oracle Web Services Security API. It contains these topics:

- Core Classes and Interfaces

- Supporting Classes and Interfaces

### 10.3.1 Core Classes and Interfaces

This section describes the core classes in the Oracle Web Services Security API and provides examples of their use.

#### 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`.

Example 10-1 Obtaining Security Elements from an XML Document

    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:

Example 10-2 Creating a SOAP Envelope

    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:

Example 10-3 Obtaining the Security Element for a SOAP Message

    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 Supporting Classes and Interfaces

This section describes supporting classes and interfaces in the Oracle Web Services Security API.

#### 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()`

## 10.4 The Oracle Web Services Security API Reference

The Oracle Web Services Security API Reference (Javadoc) is available at:

Oracle Security Developer Tools Web Services Security Java API Reference