Configure signing information using the WSSSignature API

Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop web services - Security (WS-Security) > Develop applications that use Web Services Security > Develop message-level security for JAX-WS web services > Secure web services applications using the WSS APIs at the message level > Secure messages at the request generator using WSS APIs > Secure messages at the request generator using WSS APIs > Configure generator signing information to protect message integrity using the WSS APIs

Configure signing information using the WSSSignature API

We can secure the SOAP messages, without using policy sets for configuration, by using the Web Services Security APIs (WSS API).
To configure the signing information for the generator binding sections for the client-side request, use the WSSSignature API. The WSSSignature API is part of the com.ibm.websphere.wssecurity.wssapi.signature package.
Either you can use the WSS API or you can configure the policy sets by using the admin console to enable the signing information.
To secure SOAP messages, complete the following signing tasks:

Configure the signing information.

Choose the signing methods.

Add or change 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 algorithms such as RSA-SHA1 and HMAC-SHA1.
XML signature defines many methods for describing key information and enables the definition of a new method. XML canonicalization (C14N) is often needed when you use XML signature. Information can be represented in various ways within serialized XML documents. The C14N process is used to canonicalize XML information. Select an appropriate C14N algorithm because the information that is canonicalized depends on this algorithm.
The signing information specifies the integrity constraints that are applied to generated messages. The constraints include specifying which message parts within the generated message must be digitally signed, and the message parts to attach digitally signed Nonce and timestamp elements to. The following signature and related signature part information are configured:

Signature parts information. Use the signature parts to secure messages.

signature parts Description
keyword Add a signature part using keywords. Use the following keywords for the signature parts:

ADDRESSING_HEADERS
BODY
TIMESTAMP

The WS-Addressing headers are not encrypted but can be signed.
xpath Add a signature part by using an XPath expression.
part Add a WSSSignPart object as a target of the signature part.
timestamp Add a WSSTimestamp object as a target of the signature part. When specified, the timestamp information also specifies when the message is generated and when it expires.
header Add the header, specified by QName, as a target of the signature part.
securityToken Add a SecurityToken object as a target of the signature part.

For signing information, certain default behaviors occur. The simplest way to use the WSSSignature API is to use the default behavior (see the example code). The default values are defined by the WSS API for the signing method, the canonicalization method, the security token references, and the signature parts.

Signature default behaviors. Several signature behaviors are configured by default.

Signature decisions Default behavior
Which keywords to use Sets the keywords. WAS supports the following keywords by default:

ADDRESSING_HEADERS
BODY
TIMESTAMP

Which signature method to use Sets the signature algorithm. The default signature method is RSA SHA1. WAS supports the following pre-configured signature methods:

WSSSignature.RSA_SHA1: http://www.w3.org/2000/09/xmldsig#rsa-sha1
WSSSignature.HMAC_SHA1: http://www.w3.org/2000/09/xmldsig#hmac-sha1

The DSA-SHA1 digital signature method (http://www.w3.org/2000/09/xmldsig#dsa-sha1) is not supported.
Which canonicalization method to use Sets the canonicalization algorithm. The default canonicalization method is EXC C14N. WAS supports the following pre-configured canonicalization methods:

WSSSignature.EXC_C14N; http://www.w3.org/2001/10/xml-exc-c14n#
WSSSignature.C14N: http://www.w3.org/2001/10/xml-c14n#

Whether signature confirmation is required Sets whether to require signature confirmation. The default value is false. Signature confirmation is defined in the OASIS Web Services Security v1.1 specification. If required, the value of your signature confirmation is stored in order to use it to validate the signature confirmation after receiving back the message that generated the signature confirmation in the response message. This method is for the requestor side.
Which security token to use Sets the SecurityToken. The token type specifies which type of token to use for signing and validating messages. The X.509 token is the default token type.
WAS provides the following pre-configured consumer token types:

Derived Key Token
X509 tokens

We can also create custom token types, as needed.
Which token reference to set Sets the refType. SecurityToken.REF_STR is the default value for the type of token reference. WAS supports these pre-configured token references types:

SecurityToken.REF_STR
SecurityToken.REF_KEYID
SecurityToken.REF_EMBEDDED
SecurityToken.REF_THUMBPRINT

If WSSSignature.requireSignatureConfirmation() is called, then the WSSSignature API expects that the response message will include the signature confirmation.

Procedure

To configure the signing information in a SOAP message by using the WSS API, first ensure that the application server is installed.
Use the WSSSignature API to sign the message parts and specify the algorithms in a SOAP message. The WSS API process for signature follows these process steps:

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

Creates the WSSGenerationContext instance from the WSSFactory instance. WSSGenerationContext must be called in a JAX-WS client application.

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

Creates WSSSignature from the WSSFactory instance using the SecurityToken. The default behavior of WSSSignature is to sign these signature parts: BODY, ADDRESSING_HEADERS, and TIMESTAMP.

Adds the part to be signed, if the default part is not appropriate. If the digest method or transform method is changed, creates WSSSignPart and add it to WSSSignature.

Creates WSSSignaturePart to WSSSignature. Calls the requiredSignatureConfirmation() method, if the signature confirmation is to be applied.
Sets the canonicalization method, if the default is not appropriate.
Sets the signature method, if the default is not appropriate.
Sets the token reference, if the default is not appropriate.

Adds WSSSignature to WSSGenerationContext.
Calls WSSGenerationContext.process() with the SOAPMessageContext.

Results
You have completed the steps to configure the signature for the generator section of the bindings. If there is an error condition when signing the message parts, 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 methods that are defined in the WSSignature API.
// Get the message context    Object msgcontext = getMessageContext();

// Generate the com.ibm.websphere.wssecurity.wssapi.WSSFactory instance  (step: a)
   WSSFactory factory = com.ibm.websphere.wssecurity.wssapi.WSSFactory.getInstance();

// Generate the WSSGenerationContext instance  (step: b)
   WSSGenerationContext gencont = factory.newWSSGenerationContext();

// Generate the 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 to be used for the signature  (step: c)
   SecurityToken token = factory.newSecurityToken(X509Token.class,
        callbackHandler);

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

// Set the part to be signed  (step: e)
// DEFAULT: WSSSignature.BODY, WSSSignature.ADDRESSING_HEADERS,
//          and WSSSignature.TIMESTAMP.

// Set the part in the SOAP Header specified by QName  (step: e)
      sig.addSignHeader(new
                        QName("http://www.w3.org/2005/08/addressing",
                        "MessageID"));

// Set the part specified by the keyword  (step: e)
      sig.addSignPart(WSSSignature.BODY);

// Set the part specified by SecurityToken  (step: e)
   UNTGenerateCallbackHandler untCallbackHandler = new
      UNTGenerateCallbackHandler("Chris", "sirhC");
      SecurityToken unt = factory.newSecurityToken(UsernameToken.class,
         untCallbackHandler);
      sig.addSignPart(unt);

// Set the part specified by WSSSignPart  (step: e)
   WSSSignPart sigPart = factory.newWSSSignPart();
      sigPart.setSignPart(WSSSignature.TIMESTAMP);
      sigPart.setDigestMethod(WSSSignPart.SHA256);
      sig.addSignPart(sigPart);

// Set the part specified by WSSTimestamp  (step: e)
   WSSTimestamp timestamp = factory.newWSSTimestamp();
      sig.addSignPart(timestamp);

// 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']");
      sig.addSignPartByXPath(sb.toString());

// Set to apply the signature confirmation  (step: f)
      sig.requireSignatureConfirmation();

// Set the canonicalization method  (step: g)
// DEFAULT: WSSSignature.EXC_C14N
      sig.setCanonicalizationMethod(WSSSignature.C14N);

// Set the signature method  (step: h)
// DEFAULT: WSSSignature.RSA_SHA1
      sig.setSignatureMethod(WSSSignature.HMAC_SHA1);

// Set the token reference  (step: i)
// DEFAULT: SecurityToken.REF_STR
      sig.setTokenReference(SecurityToken.REF_KEYID);

// Add the WSSSignature to WSSGenerationContext  (step: j)
   gencont.add(sig);

// Generate the WS-Security header  (step: k)
gencont.process(msgctx);
The X509GenerationCallbackHandler needs the key password because the private key is used for signing.

What to do next

Next, chose the algorithm methods if you want a method that is different from the default values. If the algorithm methods do not need to be changed, next use the WSSVerification API to verify the signature and specify the algorithm methods in the consumer section of the binding. Note that the WSSVerification API is only supported on the response consumer (client side).
XML digital signature
Signature confirmation
Configure generator security tokens using the WSS API
Verify the signature using the WSSVerification API
Configure generator signing information to protect message integrity using the WSS APIs

Related

Digital signing methods using the WSSSignature API

+
Search Tips | Advanced Search

signature parts	Description
keyword	Add a signature part using keywords. Use the following keywords for the signature parts: ADDRESSING_HEADERS BODY TIMESTAMP The WS-Addressing headers are not encrypted but can be signed.
xpath	Add a signature part by using an XPath expression.
part	Add a WSSSignPart object as a target of the signature part.
timestamp	Add a WSSTimestamp object as a target of the signature part. When specified, the timestamp information also specifies when the message is generated and when it expires.
header	Add the header, specified by QName, as a target of the signature part.
securityToken	Add a SecurityToken object as a target of the signature part.

Signature decisions	Default behavior
Which keywords to use	Sets the keywords. WAS supports the following keywords by default: ADDRESSING_HEADERS BODY TIMESTAMP
Which signature method to use	Sets the signature algorithm. The default signature method is RSA SHA1. WAS supports the following pre-configured signature methods: WSSSignature.RSA_SHA1: http://www.w3.org/2000/09/xmldsig#rsa-sha1 WSSSignature.HMAC_SHA1: http://www.w3.org/2000/09/xmldsig#hmac-sha1 The DSA-SHA1 digital signature method (http://www.w3.org/2000/09/xmldsig#dsa-sha1) is not supported.
Which canonicalization method to use	Sets the canonicalization algorithm. The default canonicalization method is EXC C14N. WAS supports the following pre-configured canonicalization methods: WSSSignature.EXC_C14N; http://www.w3.org/2001/10/xml-exc-c14n# WSSSignature.C14N: http://www.w3.org/2001/10/xml-c14n#
Whether signature confirmation is required	Sets whether to require signature confirmation. The default value is false. Signature confirmation is defined in the OASIS Web Services Security v1.1 specification. If required, the value of your signature confirmation is stored in order to use it to validate the signature confirmation after receiving back the message that generated the signature confirmation in the response message. This method is for the requestor side.
Which security token to use	Sets the SecurityToken. The token type specifies which type of token to use for signing and validating messages. The X.509 token is the default token type. WAS provides the following pre-configured consumer token types: Derived Key Token X509 tokens We can also create custom token types, as needed.
Which token reference to set	Sets the refType. SecurityToken.REF_STR is the default value for the type of token reference. WAS supports these pre-configured token references types: SecurityToken.REF_STR SecurityToken.REF_KEYID SecurityToken.REF_EMBEDDED SecurityToken.REF_THUMBPRINT