Add encrypted parts using the WSSEncryptPart API

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

We 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:

• Configure encryption and choose the encryption methods using the WSSEncryption API.

• Configure the encrypted parts using the WSSEncryptpart API, as needed.

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.

Encrypted parts	Description
part	Add the WSSEncryptPart object as a target of the encryption part.
keyword	Add the encrypted parts using keywords. The default encryption parts that we can add using keywords are the BODY_CONTENT and SIGNATURE. WebSphere Application Server supports using these keywords: BODY_CONTENT SIGNATURE
xpath	Add the encrypted part using an XPath expression.
signature	Add the WSSSignature component as a target of the encrypted part. WSSSignature is applicable only if the SOAP message contains a signature element.
header	Add the SOAP header, specified by QName, as a target of the encrypted part.
securityToken	Add 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:

part decisions. Several encrypted message parts are set

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	WAS does not specify any transform method by default. Specify a transform method only if using SOAP with Attachments.

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. Add 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 to encrypt the security token, the signature, and the body content, we must call addEncryptPart(securityToken, false), addEncryptPart(WSSEncryption.SIGNATURE), and addEncryptPart(WSSEncrypyion.BODY_CONTENT).

   7. Sets the transform method.

   8. Add WSSEncryptPart to WSSEncryption.

   9. Add 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, 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.

Related concepts

Encrypted SOAP headers

Related tasks

Configure encryption to protect message confidentiality using the WSS APIs

Encrypting the SOAP message using the WSSEncryption API

Secure message parts using the administrative console

Configure generator security tokens using the WSS API