+

Search Tips   |   Advanced Search

Add encrypted parts using the WSSEncryptPart API


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

Use the WSS APIs or configure policy sets using the admin console to enable the encrypted parts. To secure SOAP messages, use the WSS APIs to complete the following encryption tasks, 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.


Table 1. Encrypted parts

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 we can add using keywords are the BODY_CONTENT and SIGNATURE. WAS 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

Encrypted part decisions Default behavior
Which SOAP message parts to encrypt using keywords

Specifies which keywords to use for the encrypted parts. WAS 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 verify the appserver 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. WAS 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 we 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, 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 WS-Security.

 

Next steps

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 admin console.

 

Related concepts


Encrypted SOAP headers

 

Related tasks


Encrypting the SOAP message using the WSSEncryption API
Secure message parts
Set the generator security tokens using the WSS API
Set encryption to protect message confidentiality using the WSS APIs