Decrypting SOAP messages using the WSSDecryption API

You can secure the SOAP messages, without using policy sets for configuration, by using the Web Services Security APIs (WSS API). To configure the client for decryption on the response (client) consumer side, use the WSSDecryption API to decrypt the SOAP messages. The WSSDecryption API specifies which request SOAP message parts to decrypt when configuring the client.

Before you begin

You can use the WSS API or use policy sets on the administrative console to enable decryption and add consumer security tokens in the SOAP message. To secure SOAP messages, you must have completed the following decryption tasks:

Encrypted the SOAP message.
Chosen the decryption method.

About this task

The decryption information on the consumer side is used for decrypting an incoming SOAP message for the response consumer (client side) bindings. The client consumer configuration must match the configuration for the provider generator.

Confidentiality settings require that confidentiality constraints be applied to generated messages.

The following decryption parts can be configured:

Table 1. Decryption parts . Use the decryption parts to secure messages.
Decryption parts	Description
part	Adds the WSSDecryptPart object as a target of the decryption part.
keyword	Adds the decryption part using keywords. WebSphere® Application Server supports the following keywords: BODY_CONTENT SIGNATURE USERNAME_TOKEN
xpath	Adds the decryption part using an XPath expression.
verification	Adds the WSSVerification instance as a target of the decryption part.
header	Adds the SOAP header, specified by QName, as a target of the decryption part.

For decryption, certain default behaviors occur. The simplest way to use the WSS API for decryption is to use the default behavior (see the example code). WSSDecryption provides defaults for the key encryption algorithm, the data encryption algorithm, and the decryption parts such as the SOAP body content and the signature. The decryption default behaviors include:

Table 2. Decryption decisions . Several decryption part characteristics are configured by default.
Decryption decisions	Default behavior
Which parts to decrypt	The default decryption parts are the BODY_CONTENT and SIGNATURE. WebSphere Application Server supports using these keywords: WSSDecryption.BODY_CONTENT WSSDecryption.SIGNATURE WSSDecryption.USERNAME_TOKEN After you specify which message parts to decrypt, you must specify which method to use when decrypting the consumer request message. For example, if both signature and body content are applied for encryption, then the SOAP message parts that are decrypted include the same parts.
Whether to encrypt the key (isEncrypt)	The default value is to encrypt the key (`true`).
Which data decryption algorithm to choose (method)	The default data decryption algorithm method is AES128. WebSphere Application Server supports these data encryption methods: WSSDecryption.AES128: http://www.w3.org/2001/04/xmlenc#aes128-cbc WSSDecryption.AES192: http://www.w3.org/2001/04/xmlenc#aes192-cbc WSSDecryption.AES256: http://www.w3.org/2001/04/xmlenc#aes256-cbc WSSDecryption.TRIPLE_DES: http://www.w3.org/2001/04/xmlenc#tripledes-cbc
Which key decryption method to choose (algorithm)	The default key decryption algorithm method is key wrap RSA OAEP. WebSphere Application Server supports these key encryption methods: WSSDecryption.KW_AES128: http://www.w3.org/2001/04/xmlenc#kw-aes128 WSSDecryption.KW_AES192: http://www.w3.org/2001/04/xmlenc#kw-aes192 WSSDecryption.KW_AES256: http://www.w3.org/2001/04/xmlenc#kw-aes256 WSSDecryption.KW_RSA_OAEP: http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p WSSDecryption.KW_RSA15: http://www.w3.org/2001/04/xmlenc#rsa-1_5 WSSDecryption.KW_TRIPLE_DES: http://www.w3.org/2001/04/xmlenc#kw-tripledes
Which security token to specify	The default security token type is the X509 token. WebSphere Application Server provides the following pre-configured consumer token types: Derived key token X509 tokens

Procedure

To decrypt the SOAP message using the WSSDecryption API, first ensure that the application server is installed.
The WSS API process for decryption performs these process steps:
1. Uses WSSFactory.getInstance() to get the WSS API implementation instance.
2. Creates the WSSConsumingContext instance from the WSSFactory instance.
  The WSSConsumingContext must always be called in a JAX-WS client application.
3. Creates the callback handler for the consumer side.
4. Creates WSSDecryption with the class for the security token and the callback handler from the WSSFactory instance.
  The default behavior of WSSDecryption is to assume that the body content and the signature are encrypted.
5. Adds the parts to be decrypted, if the default is not appropriate.
6. Adds the candidates of the data encryption methods to use for decryption.
7. Adds the candidates of the key encryption methods to use for decryption.
8. Adds the candidates of the security token to use for decryption.
9. Calls WSSDecryption.encryptKey(false) if the application does not want the key to be encrypted in the incoming message.
10. Adds WSSDecryption to WSSConsumingContext.
11. Calls WSSConsumingContext.process() with the SOAPMessageContext

Results

If there is an error condition during decryption, a WSSException is provided. If successful, the WSSConsumingContext.process() is called, and Web Services Security is applied to the SOAP message.

Example

The following example provides sample code for decrypting the SOAP message body content:

// Get the message context
   Object msgcontext = getMessageContext();

// Generate the WSSFactory instance (step: a)
   WSSFactory factory = WSSFactory.getInstance();

// Generate the WSSConsumingContext instance (step: b)
   WSSConsumingContext gencont = factory.newWSSConsumingContext();

// Generate the callback handler (step: c)
   X509ConsumeCallbackHandler callbackHandler = new 
       X509ConsumeCallbackHandler(
                                  "",
                                  "enc-sender.jceks",
                                  "jceks", 
                                  "storepass".toCharArray(), 
                                  "alice", 
                                  "keypass".toCharArray(), 
	"CN=Alice, O=IBM, C=US");

// Generate the WSSDecryption instance (step: d)
   WSSDecryption dec = factory.newWSSDecryption(X509Token.class, 
                                                callbackHandler);

// Set the part to be encrypted (step: e)
// DEFAULT: WSSEncryption.BODY_CONTENT and WSSEncryption.SIGNATURE

// Set the part to be encrypted (step: e)
// DEFAULT: WSSEncryption.BODY_CONTENT and WSSEncryption.SIGNATURE

// Set the part specified by the keyword (step: e)
      dec.addRequiredDecryptPart(WSSDecryption.BODY_CONTENT);

// Set the part in the SOAP Header specified by QName (step: e)
    dec.addRequiredDecryptHeader(new 
       QName("http://www.w3.org/2005/08/addressing", 
       "MessageID"));

// Set the part specified by WSSVerification  (step: e)
   X509ConsumeCallbackHandler verifyCallbackHandler = 
      getCallbackHandler();
   WSSVerification ver = factory.newWSSVerification(X509Token.class, 
                                                    verifyCallbackHandler);
      dec.addRequiredDecryptPart(ver);

// Set the part specified by XPath expression (step: e)
      StringBuffer sb = new StringBuffer();
         sb.append("/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' 
            and local-name()='Envelope']");
         sb.append("/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' 
            and local-name()='Body']");
         sb.append("/*[namespace-uri()='http://xmlsoap.org/Ping' 
            and local-name()='Ping']");
         sb.append("/*[namespace-uri()='http://xmlsoap.org/Ping' 
            and local-name()='Text']");
      dec.addRequiredDecryptPartByXPath(sb.toString());

// Set the part in the SOAP header to be decrypted specified by QName (step: e)
      dec.addRequiredDecryptHeader(new 
          QName("http://www.w3.org/2005/08/addressing", 
          "MessageID"));

// Set the candidates for the data encryption method (step: f)
// DEFAULT : WSSDecryption.AES128
      dec.addAllowedEncryptionMethod(WSSDecryption.AES128);
      dec.addAllowedEncryptionMethod(WSSDecryption.AES192);

// Set the candidates for the key encryption method (step: g)
// DEFAULT : WSSDecryption.KW_RSA_OAEP
      dec.addAllowedKeyEncryptionMethod(WSSDecryption.KW_TRIPLE_DES);

// Set the candidate security token to used for the decryption (step: h)
   X509ConsumeCallbackHandler callbackHandler2 = getCallbackHandler2();
      dec.addToken(X509Token.class, callbackHandler2);

// Set whether or not the key should be encrypted in the incoming SOAP message (step: i) 
// DEFAULT: true
      dec.encryptKey(true);

// Add the WSSDecryption to the WSSConsumingContext (step: j)
   concont.add(dec);

// Validate the WS-Security header (step: k)
concont.process(msgcontext);

What to do next

Next, use the WSSDecryptPart API or configure the policy sets using the administrative console to add decrypted parts for the consumer message.