XKMS (XML Key Management Specification) is a W3C specification for public key management. 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:
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 12-1 Packages in the Oracle XKMS Library
| Package | Description |
|---|---|
|
|
Contains the main XKMS message elements |
|
|
Contains the classes for the Key Information Service Specification |
|
|
Contains the classes for the Key Registration Service Specification |
|
|
Contains constants and utility classes |
The Oracle Security Developer Tools are installed with Oracle WebLogic Server in ORACLE_HOME. This section explains how to set up your environment for Oracle XKMS. It contains these topics:
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.
To set your CLASSPATH on Windows:
In your Windows Control Panel, select System.
In the System Properties dialog, select the Advanced tab.
Click Environment Variables.
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.
Add the full path and file names for all of the required jar and class files to the CLASSPATH.
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;
Click OK.
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/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;
This section provides information and code samples for using the key classes and interfaces of Oracle XKMS. The core classes are:
This class represents the XKMS LocateRequest element.
Example 12-1 shows how to create an instance of LocateRequest:
Example 12-1 Creating an Instance of 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.
Example 12-2 shows how RespondWith can be added to a LocateRequest:
This class represents the xkms:LocateResult element.
Example 12-3 shows how to create an instance of LocateResult:
Example 12-3 Creating an Instance of LocateResult
//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:
Example 12-4 Adding an X509 Certificate to 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);
This class represents the XKMS xkms:ValidateRequest element.
Example 12-5 shows how to create an instance of xkms:ValidateRequest:
Example 12-5 Creating an Instance of 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. Example 12-6 shows how to add RespondWith to a ValidateRequest:
This class represents the XKMS ValidateResult element.
Example 12-7 shows how to create an instance of ValidateResult:
Example 12-7 Creating 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:
Example 12-8 Setting a Response Status for 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);
This class represents the XKMS RecoverRequest element.
Example 12-9 shows how to create an instance of RecoverRequest:
Example 12-9 Creating 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:
Example 12-10 Adding Authentication and RecoverKeyBinding to a RecoverRequest
//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);
This class represents the xkms:RecoverResult element.
Example 12-11 shows how to create an instance of RecoverResult:
Example 12-11 Creating an Instance of xkms: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:
Example 12-12 Creating a Key Binding for a RecoverResult
//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, Example 12-13 shows how to set the recovered PrivateKey into the RecoverResult:
Example 12-13 Setting the Recovered Private Key into 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);
The Oracle XKMS Java API Reference (Javadoc) is available at:
Oracle Fusion Middleware XKMS Java API Reference for Oracle Security Developer Tools