Decrypting SOAP messages using the WSSDecryption API

Decrypting SOAP messages using the WSSDecryption API

We can secure the SOAP messages, without using policy sets for configuration, 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.

We 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, we must have completed the following decryption tasks:

Encrypted the SOAP message.

Chosen the decryption method.

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:

Decryption parts Description
part Add the WSSDecryptPart object as a target of the decryption part.
keyword Add the decryption part using keywords. WebSphere Application Server supports the following keywords:

BODY_CONTENT

SIGNATURE

USERNAME_TOKEN

xpath Add the decryption part using an XPath expression.
verification Add the WSSVerification instance as a target of the decryption part.
header Add 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:

decisions. Several decryption part characteristics are
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 specified which message parts to decrypt, 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 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

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:

Uses WSSFactory.getInstance() to get the WSS API implementation instance.

Creates the WSSConsumingContext instance from the WSSFactory instance. The WSSConsumingContext must always be called in a JAX-WS client application.

Creates the callback handler for the consumer side.

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.

Add the parts to be decrypted, if the default is not appropriate.

Add the candidates of the data encryption methods to use for decryption.

Add the candidates of the key encryption methods to use for decryption.

Add the candidates of the security token to use for decryption.

Calls WSSDecryption.encryptKey(false) if the application does not want the key to be encrypted in the incoming message.

Add WSSDecryption to WSSConsumingContext.

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.

Related concepts

Encrypted SOAP headers

Related tasks

Choose decryption methods for the consumer binding
Configure the consumer security tokens using the WSS API
Secure message parts using the administrative console
Encrypting the SOAP message using the WSSEncryption API

Decryption methods

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

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 specified which message parts to decrypt, 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 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