Adding encrypted parts using the WSSEncryptPart API

You can secure the SOAP messages, without using policy sets for configuration, by using the Web Services Security APIs (WSS API). To configure encrypted parts for the request generator (client side) bindings, use the WSSEncryptPart API to define and add to the listing of elements in the encrypted part. WSSEncryptPart is an interface that is part of the com.ibm.websphere.wssecurity.wssapi.encryption package.

Before you begin

You can use the WSS APIs or configure policy sets using the administrative console to enable the encrypted parts. To secure SOAP messages, use the WSS APIs to complete the following encryption tasks, as needed:

About this task

Confidentiality settings require that confidentiality constraints be applied to generated messages. These constraints include specifying which message parts within the generated message must be encrypted, and which message parts to attach encrypted elements to. The encryption information on the generator side is used for encrypting an outgoing SOAP message. The request generator is configured for the client.

The WSSEncryptPart API specifies information related to encrypted parts and sets the encrypted parts that have been added for message confidentiality protection. Use the WSSEncryptPart to set the transform method and to specify the part to which the transform method is to be applied. Sets the transform method only if using SOAP with Attachments. The WSSEncryptPart is usually not needed except, in some case for tasks such as setting the transform method.

The encrypted parts and related information displayed in the following table are used to protect the confidentiality of messages.

Table 1. Encrypted parts. Use encrypted parts to secure messages.
Encrypted parts Description
part Adds the WSSEncryptPart object as a target of the encryption part.
keyword

Adds the encrypted parts using keywords. The default encryption parts that you can add using keywords are the BODY_CONTENT and SIGNATURE. WebSphere® Application Server supports using these keywords:

  • BODY_CONTENT
  • SIGNATURE
xpath Adds the encrypted part by using an XPath expression.
signature Adds the WSSSignature component as a target of the encrypted part.

WSSSignature is applicable only if the SOAP message contains a signature element.

header Adds the SOAP header, specified by QName, as a target of the encrypted part.
securityToken Adds the SecurityToken object as a target of the encrypted part.

For encrypted parts, certain default behaviors occur. The simplest way to use the WSSEncryptPart API is to use the default behavior. The WSSEncryptPart API provides defaults for specifying the transform algorithm, setting objects as targets, specifying the encrypted parts, such as: the SOAP body content and the signature.

The encryption default behaviors include:

Table 2. Encrypted part decisions. Several encrypted message parts are set by default.
Encrypted part decisions Default behavior
Which SOAP message parts to encrypt using keywords

Specifies which keywords to use for the encrypted parts. WebSphere Application Server sets the following SOAP message parts by default for encryption:

  • WSSEncryption.BODY_CONTENT
  • WSSEncryption.SIGNATURE
Which transform method to add

WebSphere Application Server does not specify any transform method by default. Specify a transform method only if using SOAP with Attachments.

Procedure

  1. To encrypt the SOAP message parts using the WSSEncryptPart API, first ensure that the application server is installed.
  2. The WSS API process using WSSEncryptPart follows these process steps:
    1. Uses WSSFactory.getInstance() to get the WSS API implementation instance.
    2. Creates the WSSGenerationContext instance from the WSSFactory instance.
    3. Creates the SecurityToken from WSSFactory to configure the encryption.
    4. Creates WSSEncryption from the WSSFactory instance using SecurityToken.
    5. Creates WSSEncryptPart from WSSFactory.
    6. Adds the parts to be encrypted and to be applied with the transform in WSSEncryptPart. WebSphere Application Server sets these encrypted parts by default for WSSEncryptPart: the BODY_CONTENT and SIGNATURE. After you add other encrypted parts, the default values are no longer valid. For example, if you call addEncryptPart(securityToken, false), only the security token is encrypted, and not the signature and body content. So if you want to encrypt the security token, the signature, and the body content, you must call addEncryptPart(securityToken, false), addEncryptPart(WSSEncryption.SIGNATURE), and addEncryptPart(WSSEncrypyion.BODY_CONTENT).
    7. Sets the transform method.
    8. Adds WSSEncryptPart to WSSEncryption.
    9. Adds WSSEncryption to WSSGenerationContext.
    10. Calls WSSGenerationContext.process() with the SOAPMessageContext.

Results

If there is an error condition during encryption of the message parts, a WSSException is provided. If successful, the API calls the WSSGenerationContext.process(), the WS-Security header is generated, and the SOAP message is now secured using Web Services Security.

What to do next

After enabling encrypted parts for the request generator (client side) binding, you must specify the same parts to be decrypted for the response consumer (client side) bindings. Next, to configure decryption and decrypted parts, use the WSS APIs or configure policy sets using the administrative console.




In this information ...


Related concepts

IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic Task topic    

Terms of Use | Feedback

Last updatedLast updated: Sep 19, 2011 6:15:55 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=matt&product=was-express-dist&topic=twbs_confwssencryptsecretkey
File name: twbs_confwssencryptsecretkey.html