+

Search Tips   |   Advanced Search

Decrypting the SOAP message using the WSSDecryption API


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

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

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

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

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:

 

  1. To decrypt the SOAP message using the WSSDecryption API, first verify the appserver is installed.

  2. 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 WS-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);

 

Next steps

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

 

Related concepts


Encrypted SOAP headers

 

Related tasks


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

 

Related


Decryption methods