11 Oracle XKMS

XKMS (XML Key Management Specification) is a W3C specification for public key management. Oracle XKMS API conforms to this specification. It provides a convenient way to handle public key infrastructures by enabling developers to write XML transactions for digital signature processing.

This chapter contains these topics:

• Understanding Oracle XKMS Features and Benefits

• Setting Up Your Oracle XKMS Environment

• Core Classes and Interfaces

• The Oracle XKMS Java API Reference

11.1 Understanding Oracle XKMS Features and Benefits

Oracle XKMS is a pure Java solution which consists of a toolkit for locating keys and verifying user identities across businesses and applications. It supports the secure, trusted messaging required for web services, and provides a way to sidestep some of the costs and complexity associated with PKI.

Oracle XKMS provides the following features:

• Simplified access to PKI functionality - by implementing the W3C XKMS Standard, Oracle XKMS combines the simplicity of XML with the robustness of PKI. With this toolkit, developers can easily deploy robust application functionality by deploying secure, lightweight client software.

• Supports complete key/certificate life cycle - Oracle XKMS helps enterprise applications locate, retrieve, and validate signature and encryption keys using lightweight Web Services infrastructure.

• Secures XKMS messages using XML Signatures - requests and responses can be digitally signed using Oracle XML toolkit.

• 100% Java with no native methods

• Works with JAXP 1.1 compliant XML parsers

The Oracle XKMS library contains the following packages:

Table 11-1 Packages in the Oracle XKMS Library

Package	Description
oracle.security.xmlsec.xkms	Contains the main XKMS message elements
oracle.security.xmlsec.xkms.xkiss	Contains the classes for the Key Information Service Specification
oracle.security.xmlsec.xkms.xkrss	Contains the classes for the Key Registration Service Specification
oracle.security.xmlsec.xkms.util	Contains constants and utility classes

11.2 Setting Up Your Oracle XKMS Environment

You can setup Oracle XKMS environment by installing Oracle Security Developer Tools and Java Development Kit (JDK), and setting the CLASSPATH variable to all of the required jar and class files.

The Oracle Security Developer Tools are installed with Oracle WebLogic Server in ORACLE_HOME.

In order to use Oracle XKMS, your system must have the following components installed:

• The Java Development Kit (JDK) version 1.6 or higher

• the Oracle XML Security toolkit

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

• osdt_core.jar

• osdt_cert.jar

• osdt_xmlsec.jar

• org.jaxen_1.1.1.jar, which is located in the $ORACLE_HOME/modules/ directory of the security tools distribution. Oracle XML Security relies on the Jaxen XPath engine for XPath processing.

For example, your CLASSPATH might look like this:

C:%ORACLE_HOME%\modules\oracle.osdt_11.1.1\osdt_core.jar;
%ORACLE_HOME%\modules\oracle.osdt_11.1.1\osdt_cert.jar;
%ORACLE_HOME%\modules\oracle.osdt_11.1.1\osdt_xmlsec.jar;
%ORACLE_HOME%\modules\org.jaxen_1.1.1.jar;

See Also:

Setting the CLASSPATH Environment Variable

11.3 Core Classes and Interfaces

Core classes of Oracle XKMS enable you to locate, validate, and recover message requests and results. You can refer the code samples to use the core classes and interfaces of Oracle XKMS.

The core classes are:

• oracle.security.xmlsec.xkms.xkiss.LocateRequest

• Using the oracle.security.xmlsec.xkms.xkiss.LocateResult Class

• Using the oracle.security.xmlsec.xkms.xkiss.ValidateRequest Class

• Using the oracle.security.xmlsec.xkms.xkiss.ValidateResult Class

• Using the oracle.security.xmlsec.xkms.xkrss.RecoverRequest Class

• Using the oracle.security.xmlsec.xkms.xkrss.RecoverResult Class

11.3.1 oracle.security.xmlsec.xkms.xkiss.LocateRequest

The oracle.security.xmlsec.xkms.xkiss.LocateRequest class represents the XKMS LocateRequest element. You can refer examples and create an instance of LocateRequest, and attach RespondWith attribute to LocateRequest.

// Parse the XML document containing the dsig:Signature.
Document sigDoc = //Instance of org.w3c.dom.Document;
 
//Create Query Key Binding
QueryKeyBinding queryKeyBinding = new QueryKeyBinding(sigDoc);
queryKeyBinding.setTimeInstant(new Date());
 
// Create the xkms:LocateRequest.
LocateRequest loc = new LocateRequest(sigDoc, queryKeyBinding);

Client requests of type LocateRequest must include an xkms:RespondWith attribute.

This example shows how RespondWith can be added to a LocateRequest:

//Add xkms:RespondWith as X.509 Certificate.
loc.addRespondWith(XKMSURI.respondWith_X509Cert);

11.3.2 Using the oracle.security.xmlsec.xkms.xkiss.LocateResult Class

oracle.security.xmlsec.xkms.xkiss.LocateResult class represents the xkms:LocateResult element. You can create an instance of LocateResult element. If the LocateRequest contains a RespondWith attribute of X509Certificate, you can add an X509 Certificate to the LocateResult element.

Example:

//Parse the XML document containin the dsig:Signature
Document sigDoc = //Instance of org.w3c.doc.Document;
 
// Create the xkms:LocateResult
LocateResult locRes = new LocateResult(sigDoc);
 
//Set ResultMajor to Success.
locRes.setResultCode(XKMSURI.result_major_success, null);

If the LocateRequest contained a RespondWith attribute of X509Certificate, use the following code to add an X509 Certificate to the LocateResult:

//Creating a signature and adding X509 certificate to the KeyInfo element.
X509Certificate userCert = // Instance of java.security.cert.X509Certificate
XSSignature Sig = XSSignature.newInstance(sigDoc, "MySignature");
XSKeyInfo xsInfo = sig.getKeyInfo();
X509Data xData = xsInfo.createX509Data(userCert);
 
//Add X509Data to the KeyInfo
xsInfo.addKeyInfoData(xData);
 
//Set Key Binding and add KeyInfo the the KeyBinding
UnverifiedKeyBinding keyBinding = new UnverifiedKeyBinding(sigDoc);
keyBinding.setKeyInfo(xsInfo);
 
//Add Key Binding to LocateResult
locRes.addKeyBinding(keyBinding);

11.3.3 Using the oracle.security.xmlsec.xkms.xkiss.ValidateRequest Class

The oracle.security.xmlsec.xkms.xkiss.ValidateRequest class represents the XKMS xkms:ValidateRequest element. With this class you can create an instance of xkms:ValidateRequest element.

This example shows how to create an instance of xkms:ValidateRequest:

// Parse the XML document containing the dsig:Signature.
Document sigDoc = //Instance of org.w3c.dom.Document;
 
//Create Query Key Binding
QueryKeyBinding queryKeyBinding = new QueryKeyBinding(sigDoc);
queryKeyBinding.setTimeInstant(new Date());
 
// Create the xkms:ValidateRequest.
ValidateRequest validateReq = new ValidateRequest(sigDoc, queryKeyBinding);

Requests of type ValidateRequest must include an xkms:RespondWith attribute. This example shows how to add RespondWith to a ValidateRequest:

//Add xkms:RespondWith as X.509 Certificate.
validateReq.addRespondWith(XKMSURI.respondWith_X509Cert);

11.3.4 Using the oracle.security.xmlsec.xkms.xkiss.ValidateResult Class

With the oracle.security.xmlsec.xkms.xkiss.ValidateResult class, you can create an instance of ValidateResult. You can also set a status in response to a ValidateRequest.

This example shows how to create an instance of ValidateResult:

//Parse the XML document containin the dsig:Signature
Document sigDoc = //Instance of org.w3c.doc.Document;
 
// Create the xkms:ValidateResult
ValidateResult valRes = new ValidateResult(sigDoc);
 
//Set ResultMajor to Success.
valRes.setResultCode(XKMSURI.result_major_success, null);

Use the following code to set a status in response to a ValidateRequest:

//Create a status element and add reasons.
Status responseStatus = new Status(sigDoc);
responseStatus.addValidReason(XKMSURI.reasonCode_IssuerTrust);
responseStatus.addValidReason(XKMSURI.reasonCode_RevocationStatus);
responseStatus.addValidReason(XKMSURI.reasonCode_ValidityInterval);
responseStatus.addValidReason(XKMSURI.reasonCode_Signature);
 
//Create a xkms:KeyBinding to add status and X509Data
XSKeyInfo xsInfo = 
    // Instance of oracle.security.xmlsec.dsig.XSKeyInfo, 
    // which contains X509Data
KeyBinding keyBinding = new KeyBinding(sigDoc);
keyBinding.setStatus(responseStatus);
keyBinding.setKeyInfo(xsInfo);
 
// Add the key binding to the ValidateResult.
valRes.addKeyBinding(keyBinding);

11.3.5 Using the oracle.security.xmlsec.xkms.xkrss.RecoverRequest Class

The oracle.security.xmlsec.xkms.xkrss.RecoverRequest class represents the XKMS RecoverRequest element. With this class, you can create an instance of RecoverRequest. You can also add the Authentication and RecoverKeyBinding elements to RecoverRequest.

This example shows how to create an instance of RecoverRequest:

// Parse the XML document containing the dsig:Signature.
Document sigDoc = //Instance of org.w3c.dom.Document;
 
// Create the xkms:RecoverRequest
RecoverRequest recReq = new RecoverRequest(sigDoc);
 
//Set RespondWith to PrivateKey, so that the RecoverResult 
contains the private key.
recReq.addRespondWith(XKMSURI.respondWith_PrivateKey);

A RecoverRequest must include the Authentication and RecoverKeyBinding elements. These can be added with the following code:

//Create an instance of XSSignature.
XSSignature sig = 
    //Instance of oracle.security.xmlsec.dsig.XSSignature
 
//Create an instance of Authentication element.
Authentication auth = new Authentication(sigDoc);
 
//Set key binding authentication.
auth.setKeyBindingAuthentication(sig);
 
//Set Authentication for the RecoverRequest.
recReq.setAuthentication(auth);
 
//Add RecoverKeyBinding to RecoverRequest.
RecoverKeyBinding recKeyBind = new RecoverKeyBinding(sigDoc);
 
//Add Key Info on the key to be recovered.
XSKeyInfo xsInfo = 
    //Instance of oracle.security.xmlsec.dsig.XSKeyInfo
recKeyBind.setKeyInfo(xsInfo);
 
//Adding status, as known to the key holder, to the KeyBinding
Status keyStatus = new Status(sigDoc);
keyStatus.setStatusValue(XKMSURI.kbs_Indeterminate);
recKeyBind.setStatus(keyStatus);
 
//Adding RecoverKeyBinding to RecoverRequest.
recReq.setKeyBinding(recKeyBind);

11.3.6 Using the oracle.security.xmlsec.xkms.xkrss.RecoverResult Class

The oracle.security.xmlsec.xkms.xkrss.RecoverResult class represents the xkms:RecoverResult element. With this class, you can create an instance of RecoverResult. You can set KeyBinding for RecoverResult. You can also set the recovered PrivateKey into the RecoverResult.

This example shows how to create an instance of RecoverResult:

// Parse the XML document containing the dsig:Signature.
Document sigDoc = //Instance of org.w3c.dom.Document;
 
// Create the xkms:RecoverResult
RecoverResult recResult = new RecoverResult(sigDoc);
 
//Set ResultMajor to Success.
recResult.setResultCode(XKMSURI.result_major_success, null);

The KeyBinding needs to be set for a RecoverResult. You can accomplish this with the following code:

//Create a xkms:KeyBinding to add status and X509Data
XSKeyInfo xsInfo = 
    //Instance of oracle.security.xmlsec.dsig.XSKeyInfo, 
    //which contains X509Data
KeyBinding keyBinding = new KeyBinding(sigDoc);
keyBinding.setKeyInfo(xsInfo);
 
//Create a status element and add reasons.
//Status is set to Invalid because the service can decide
//to revoke the key binding in the case of recovery.

Status responseStatus = new Status(sigDoc);
responseStatus.addInvalidReason(XKMSURI.reasonCode_IssuerTrust);
responseStatus.addInvalidReason(XKMSURI.reasonCode_RevocationStatus);
responseStatus.addInvalidReason(XKMSURI.reasonCode_ValidityInterval);
responseStatus.addInvalidReason(XKMSURI.reasonCode_Signature);
responseStatus.setStatusValue(XKMSURI.kbs_Invalid);
 
keyBinding.setStatus(responseStatus);
 
//Set KeyBinding into RecoverResult
recResult.addKeyBinding(keyBinding);

Finally, this example shows how to set the recovered PrivateKey into the RecoverResult:

//Create an Instance of dsig:XEEncryptedData
XEEncryptedData encryptedData = //Instance of 
oracle.security.xmlsec.enc.XEEncryptedData
 
//Create an instance of oracle.security.xmlsec.xkms.xkrss.PrivateKey
PrivateKey privKey = new PrivateKey(sigDoc);
privKey.setEncryptedData(encryptedData);
 
//Add PrivateKey to RecoverResult
recResult.setPrivateKey(privKey);

11.4 The Oracle XKMS Java API Reference

The Oracle Fusion Middleware Java API Reference for Oracle Security Developer Tools guide explains the classes, interfaces, and methods available in Oracle XKMS API.

You can access the guide at:

Oracle Fusion Middleware Java API Reference for Oracle Security Developer Tools