Decrypting SOAP messages using the WSSDecryption API

Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop web services - Security (WS-Security) > Develop applications that use Web Services Security > Develop message-level security for JAX-WS web services > Secure web services applications using the WSS APIs at the message level > Secure messages at the response consumer using WSS APIs > Configure decryption methods to protect message confidentiality using the WSS APIs

Decrypting SOAP messages using the WSSDecryption API

We 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.
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, 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. Use the decryption parts to secure messages.

Decryption parts Description
part Add the WSSDecryptPart object as a target of the decryption part.
keyword Add the decryption part using keywords. WAS 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:

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. WAS supports using these keywords:

WSSDecryption.BODY_CONTENT
WSSDecryption.SIGNATURE
WSSDecryption.USERNAME_TOKEN

After you specify 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 value is to encrypt the key (true).
Which data decryption algorithm to choose (method) The default data decryption algorithm method is AES128. WAS 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. WAS 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. WAS 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:

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.

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

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

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

Adds 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.

Adds 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 to add decrypted parts for the consumer message.
Encrypted SOAP headers
Choosing decryption methods for the consumer binding
Configure the consumer security tokens using the WSS API
Secure message parts
Encrypting the SOAP message using the WSSEncryption API
Choosing decryption methods for the consumer binding

Related

Decryption methods

+
Search Tips | Advanced Search

Decryption parts	Description
part	Add the WSSDecryptPart object as a target of the decryption part.
keyword	Add the decryption part using keywords. WAS 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. WAS supports using these keywords: WSSDecryption.BODY_CONTENT WSSDecryption.SIGNATURE WSSDecryption.USERNAME_TOKEN After you specify 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 value is to encrypt the key (true).
Which data decryption algorithm to choose (method)	The default data decryption algorithm method is AES128. WAS 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. WAS 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. WAS provides the following pre-configured consumer token types: Derived key token X509 tokens