Apache WSS4J API Overview

Contents



API Overview

WSS4J can be used as a library to provide an API for WS-Security processing. In this case WSS4J does not need to be used with Axis, or even be a part of a deployed web application. The WSS4J API can be invoked directly to create WS-Security headers or process them given a SOAP Envelope DOM Document.

Following is an overview of the main classes and methods for the WSS4J API. Please refer to the java docs for the complete API documentation.

org.apache.ws.security.WSSecurityEngine

Action

 Method
Get an instance of security engine 
public static org.apache.ws.security.WSSecurityEngine getInstance()
Description

 Get a singleton instance of security engine class. If you need to get an instance configured for an older spec (different namespaces) then use the other method which takes org.apache.ws.security.WSSConfig
Parameters
Returns

 
org.apache.ws.security.WSSecurityEngine
 Processes WS-Security Headers in a SOAP Envelope


Action

 Method
Verify WSS Headers

 
java.util.Vector processSecurityHeader
(


    org.w3c.dom.Document doc,


    java.lang.String actor,


    javax.security.auth.callback.CallbackHandler cb,


    org.apache.ws.security.components.crypto.Crypto crypto


    ) throws org.apache.ws.security.WSSecurityException
Description

 Takes a SOAP Envelope as a W3C Document and verifies the WSS Headers.  This includes Username Token processing, Signature verification, decryption and timestamp verification. In the case of encrypted elements, decryption is performed live on the passed document, i.e., it is transformed into the decrypted format.
Parameters

 
doc
 the SOAP Envelope as W3C DOM Document
actor the engine works on behalf of this actor. Refer to the SOAP specification about actor or role, this may be null.
cb

 a callback hander to the caller to resolve passwords during encryption and UsernameToken handling, this may be null.
crypto

 the object that implements the access to the keystore and the handling of certificates. A default implementation is included: org.apache.ws.security.components.crypto.Merlin
Returns

 
java.util.Vector
 Vector of org.apache.ws.security.WSSecurityEngineResult, this has the information resulting from the processing, such as the principal, SAML token, etc.


org.apache.ws.security.message.WSBaseMessage

Action

 Method
Set the Signature/Encryption parts

 
public void setParts(java.util.Vector parts)
Description

 Takes a vector of org.apache.ws.security.WSEncryptionPart.
Parameters

 
doc
 the SOAP Envelope as W3C DOM Document
crypto

 the object that implements the access to the keystore and the handling of certificates. A default implementation is included: org.apache.ws.security.components.crypto.Merlin
Returns

 
org.w3c.dom.Document
 the SOAP Envelope Signed. The signed elements depend on the signature parts that are specified by the WSBaseMessage.setParts(java.util.Vector parts) method


org.apache.ws.security.message.WSSignEnvelope (extends WSBaseMessage)

Action

 Method
Signs a SOAP Envelope

 
public org.w3c.dom.Document build(


    org.w3c.dom.Document doc,


    org.apache.ws.security.components.crypto.Crypto crypto


    ) throws org.apache.ws.security.WSSecurityException
Description

 Takes a SOAP Envelope as a W3C Document and adds WSS Signature header to it. The signed elements depend on the signature parts that are specified by the WSBaseMessage.setParts(java.util.Vector parts) method. By default, SOAP Body is signed
Parameters

 
doc
 the SOAP Envelope as W3C DOM Document
crypto

 the object that implements the access to the keystore and the handling of certificates. A default implementation is included: org.apache.ws.security.components.crypto.Merlin
Returns

 
org.w3c.dom.Document
 the SOAP Envelope signed.


org.apache.ws.security.message.WSAddTimestamp (extends WSBaseMessage)

Action

 Method
Add a Timestamp Token to a SOAP Envelope 
public org.w3c.dom.Document build
(


    org.w3c.dom.Document doc,


    int ttl)
Description

 Takes a SOAP Envelope as a W3C Document and adds a Timestamp header to it. Please refer to the WS specification 1.0. chapter 10 / appendix A.2

Parameters

 
doc
 the SOAP Envelope as W3C DOM Document 
ttl
 (time to live) This is the time difference in seconds between the Created and the Expires in Timestamp, set to zero if Expires should not be added.
Returns

 
org.w3c.dom.Document
 the SOAP Envelope with the Timestamp added


org.apache.ws.security.message.WSEncryptBody (extends WSBaseMessage)

Action

 Method
Encrypt a SOAP Envelope

 
public org.w3c.dom.Document build(


    org.w3c.dom.Document doc,


    org.apache.ws.security.components.crypto.Crypto crypto


    ) throws org.apache.ws.security.WSSecurityException
Description

 Takes a SOAP Envelope as a W3C Document and adds WSS Encryption header to it. Unlike what the class name might imply, this can be used to encrypt elements in the SOAP Header, such as Username Tokens or other arbitrary elements. The encrypted elements depend on the signature parts that are specified by the WSBaseMessage.setParts(java.util.Vector parts) method. By default, SOAP Body is encrypted
Parameters

 
doc
 the SOAP Envelope as W3C DOM Document
crypto

 the object that implements the access to the keystore and the handling of certificates. A default implementation is included: org.apache.ws.security.components.crypto.Merlin
Returns

 
org.w3c.dom.Document
 the SOAP Envelope encrypted.


org.apache.ws.security.message.WSAddUsernameToken (extends WSBaseMessage)

Action

 Method
Add a Username Token to a SOAP Envelope

 
public org.w3c.dom.Document build(


    org.w3c.dom.Document doc,


    java.lang.String username,


    java.lang.String password)
Description

 Takes a SOAP Envelope as a W3C Document and adds a Username Token header to it. Use setPasswordType(java.lang.String pwType) to choose between plain text passwords and digested ones.
Parameters

 
doc
 the SOAP Envelope as W3C DOM Document
username

 the username to use
password

 the password to use (a plain text string)
Returns

 
org.w3c.dom.Document
 the SOAP Envelope with the username token header added


org.apache.ws.security.message.WSSAddSAMLToken (extends WSBaseMessage)

Action

 Method
Add a SAML Token to a SOAP Envelope 
public org.w3c.dom.Document build(


    org.w3c.dom.Document doc,


    org.opensaml.SAMLAssertion assertion)
Description

 Takes a SOAP Envelope as a W3C Document and adds a SAML Assertion Token header to it. Please refer to the OpenSAML documentation on how to construct SAML assertions.
Parameters

 
doc
 the SOAP Envelope as W3C DOM Document 
assertion
 the SAML assertion to add
Returns

 
org.w3c.dom.Document
 the SOAP Envelope with the SAML assertion header added


Examples

Sign the SOAP Body

Document envelope = ...

WSSignEnvelope signer = new WSSignEnvelope();

Crypto crypto = CryptoFactory.getInstance("crypto.properties");

Vector parts = new Vector();

WSEncryptionPart part = new WSEncryptionPart(soapConstants.getBodyQName().getLocalPart(),

                                             soapConstants.getEnvelopeURI(),

                                             "Content");

parts.add(part);

signer.setParts(parts); // this is optional since the body is signed by default

envelope = signer.build(envelope, crypto);

Encrypt the SOAP Body

Document envelope = ...

WSEncryptBody encryptor = new WSEncryptBody();

Crypto crypto = CryptoFactory.getInstance("crypto.properties");

Vector parts = new Vector();

WSEncryptionPart part = new WSEncryptionPart(soapConstants.getBodyQName().getLocalPart(),

                                             soapConstants.getEnvelopeURI(),

                                             "Content");

parts.add(part);

encryptor.setParts(parts); // this is optional since the body is encrypted by default

envelope = encryptor.build(envelope, crypto);

Process WSS Header and Check the Results

Document envelope = ...

WSSecurityEngine secEngine = WSSecurityEngine.getInstance();

Crypto crypto = CryptoFactory.getInstance("crypto.properties");

// javax.security.auth.callback.CallbackHandler

// please refer to the tests for examples of callback handlers

CallbackHandler cb = new MyCallbackHandler();

Vector results = secEngine.processSecurityHeader(envelope, null, cb, crypto);

for (int i = 0; i < results.size(); i++) {

    WSHandlerResult hResult = (WSHandlerResult)results.get(i);

    String actor = hResult.getActor();

    Vector hResults = hResult.getResults();

    for (int j = 0; j < hResults.size(); j++) {

        WSSecurityEngineResult eResult = (WSSecurityEngineResult)hResults.get(j);

        // Note: an encryption action does not have an associated principal

        // only Signature and UsernameToken actions return a principal

        if (eResult.getAction() != WSConstants.ENCR) {

            System.out.println(eResult.getPrincipal().getName());

        }

    }

}