Add signed parts to SOAP messages using the WSSSignPart API

Add signed parts using the WSSSignPart API

We can secure the SOAP messages, without using policy sets for configuration, using the Web Services Security APIs (WSS API). To configure parts to be signed for the request generator (client side) bindings, use the WSSSignPart API to protect the integrity of messages and to configure the digest and transform algorithm methods. The WSSSignPart API is part of the com.ibm.websphere.wssecurity.wssapi.signature package.

Either we can use the WSS API or we can configure the policy sets using the console to configure the signing information. To secure SOAP messages using the signing information, you must complete one of the following tasks:

Configure the signature information

Configure signed parts, as needed.

WAS uses the signing information for the default generator to sign parts of the message, and uses XML digital signature with existing digest and transform algorithms (for example, SHA1 or TRANSFORM_EXC_C14N).
The signing information specifies the integrity constraints that are applied to generated messages. The signed parts are used to protect the integrity of messages. We can specify the signed parts to add for message integrity protection.
The following table shows the required signed parts when the digital signature security constraint (integrity) is defined:

Signed parts Description
keyword Add signed parts using keywords. WebSphere Application Server supports the following keywords for signed parts:

BODY

ADDRESSING_HEADERS

TIMESTAMP
The WS-Addressing headers are not encrypted but can be signed.
xpath Add the required signed parts by using an XPath expression.
header Add the header, specified by QName, as a signed part.
timestamp Add a WSSTimestamp object as a signed part. If specified, the timestamp information specifies when the message is generated and when it expires.

Different message parts can be specified in the message protection for request on the generator side. WSSSignPart allows for adding a transform algorithm, setting a digest method, setting objects as targets, specifying whether an element, and the signed parts, such as: the SOAP body, the WS-Addressing header, and timestamp information.
For signing information, certain default behaviors occur. The simplest way to use the WSSSignPart API is to use the default behavior (see the example code). The signed parts default behaviors include:

behavior of signed parts. Several signed part characteristics
Signature decisions Default behavior
Which SOAP message parts to sign
WebSphere Application Server supports the following SOAP message parts to be signed and used for message protection:

WSSSignature.BODY

WSSSignature.ADDRESSING_HEADERS

WSSSignature.TIMESTAMP

Which digest method to use
Sets the digest algorithm method. The digest method algorithm specified within the <DigestMethod> element is used in the <SigningInfo> element.
WebSphere Application Server supports the following pre-configured digest methods:

WSSSignPart.SHA1 (the default value): http://www.w3.org/2000/09/xmldsig#sha1

WSSSignPart.SHA256: http://www.w3.org/2001/04/xmlenc#sha256

WSSSignPart.SHA512: http://www.w3.org/2001/04/xmlenc#sha512

Which transform algorithms to use Add the transform method. The transform algorithm is specified within the <Transform> element and specifies the transform algorithm for the signature.
WebSphere Application Server supports the following pre-configured transform algorithms:

WSSSignPart.TRANSFORM_EXC_C14N (the default value): http://www.w3.org/2001/10/xml-exc-c14n#

WSSSignPart.TRANSFORM_XPATH2_FILTER: http://www.w3.org/2002/06/xmldsig-filter2
Use this transform method to ensure compliance with the Basic Security Profile (BSP).

WSSSignPart.TRANSFORM_STRT10: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#STR-Transform

WSSSignPart.TRANSFORM_ENVELOPED_SIGNATURE: http://www.w3.org/2000/09/xmldsig#enveloped-signature

To enable Web Services Security using the WSS API (WSSSignPart), first ensure that the application server is installed.

Use the WSSSignPart API to sign the message parts and specify the algorithms in a SOAP message. The WSS API process for signed parts follows these process steps:

Uses WSSFactory.getInstance() to get the WSS API implementation instance.

Creates the WSSGenerationContext instance from the WSSFactory instance.

Creates the SecurityToken from WSSFactory to configure the key for signing.

Creates WSSSignature from the WSSFactory instance using the SecurityToken.

Creates WSSSignPart from the WSSFactory instance.

Sets the part to be signed and the digest method or transform method specified by step g or step h if the default is not appropriate.

Sets the digest method if the default is not appropriate.

Sets the transform method if the default is not appropriate.

Add WSSSignPart to WSSSignature. After any WSSSignPart is set to WSSSignature, the default parts to be signed, which are specified in WSSSignature, are ignored.

Add WSSSignature to WSSGenerationContext.

Calls WSSGenerationContext.process() with the SOAPMessageContext.

Results
You have completed the steps to configure the signed parts for the generator section of the bindings files. If there is an error condition, a WSSException is provided. If successful, the WSSGenerationContext.process() is called, and Web Services Security is applied to the SOAP message.

Example

The following example provides sample code that uses all of methods defined in the WSSSignPart API:
// Get the message context    Object msgcontext = getMessageContext();

// Generate the WSSFactory instance  (step: a)
   WSSFactory factory = WSSFactory.getInstance();  

// Generate WSSGenerationContext instance  (step: b)
   WSSGenerationContext gencont = factory.newWSSGenerationContext();
  
// Generate callback handler
   X509GenerateCallbackHandler callbackHandler = new 
      X509GenerateCallbackHandler
      "", "dsig-sender.ks", "jks", 
      "client".toCharArray(), 
      "soaprequester", 
      "client".toCharArray(), 
      "CN=SOAPRequester, OU=TRL, O=IBM, ST=Kanagawa, C=JP", null);

// Generate the security token used to the signature  (step: c)
   SecurityToken token = factory.newSecurityToken(X509Token.class, callbackHandler);

// Generate WSSSignature instance (step: d)
   WSSSignature sig = factory.newWSSSignature(token);

// Set the part specified by WSSSignPart  (step: e)
   WSSSignPart sigPart = factory.newWSSSignPart();

// Set the part specified by WSSSignPart  (step: f)
   sigPart.setSignPart(WSSSignature.BODY);

// Set the digest method specified by WSSSignPart  (step: g)
   sigPart.setDigestMethod(WSSSignPart.SHA256);

// Set the transform method specified by WSSSignPart  (step: h)
   sigPart.setTransformMethod(WSSSignPart.TRANSFORM_STRT10);

// Add the part specified by WSSSignPart  (step: i)
   sig.addSignPart(sigPart);

// Add the WSSSignature to the WSSGenerationContext  (step: j)
   gencont.add(sig);
  
// Generate the WS-Security header  (step: k)
gencont.process(msgcontext);
The X509GenerationCallbackHandler needs the key password because the private key is used for signing.

What to do next

Use the WSSVerifyPart API or configure policy sets using the console to verify the signed parts on the consumer side.

Related tasks

Configure signing information using the WSSSignature API
Verify signed parts using the WSSVerifyPart API
Signing and encrypting message parts using policy sets

Signed parts methods using the WSSSignPart API

Signed parts	Description
keyword	Add signed parts using keywords. WebSphere Application Server supports the following keywords for signed parts: BODY ADDRESSING_HEADERS TIMESTAMP The WS-Addressing headers are not encrypted but can be signed.
xpath	Add the required signed parts by using an XPath expression.
header	Add the header, specified by QName, as a signed part.
timestamp	Add a WSSTimestamp object as a signed part. If specified, the timestamp information specifies when the message is generated and when it expires.