+

Search Tips   |   Advanced Search

Set the signature information using the WSSSignature API


We can secure the SOAP messages, without using policy sets for configuration, by using the WS-Security APIs (WSS API). To configure the signature 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 we can use the WSS API or we can configure the policy sets by using the admin console to enable the signing information. To secure SOAP messages, complete the following signature tasks:

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:


Table 1. signature parts information

signature parts Description
keyword Adds 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 Adds a signature part by using an XPath expression.
part Adds a WSSSignPart object as a target of the signature part.
timestamp Adds 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 Adds the header, specified by QName, as a target of the signature part.
securityToken Adds 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.


Table 2. Signature default behaviors

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 WS-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.

 

  1. To configure the signing information in a SOAP message by using the WSS API, first verify the appserver is installed.

  2. 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:

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

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

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

    4. 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.

    5. 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.

    6. Creates WSSSignaturePart to WSSSignature. Calls the requiredSignatureConfirmation() method, if the signature confirmation is to be applied.

    7. Sets the canonicalization method, if the default is not appropriate.

    8. Sets the signature method, if the default is not appropriate.

    9. Sets the token reference, if the default is not appropriate.

    10. Adds WSSSignature to WSSGenerationContext.

    11. Calls WSSGenerationContext.process() with the SOAPMessageContext.

 

Results

we 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 WS-Security is applied to the SOAP message.

 

Example

The following example provides sample code that uses methods defined in the WSSignature API. 

// Get the message context
   Object msgcontext = getMessageContext();


// Generate the WSSFactory instance  (step: a)
   WSSFactory factory = 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.

 

Next steps

Next, chose the algorithm methods if we 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).

 

Related concepts


XML digital signature
Signature confirmation

 

Related tasks


Set the generator security tokens using the WSS API
Verifying the signature using the WSSVerification API
Set generator signing information to protect message integrity using the WSS APIs

 

Related


Digital signing methods using the WSSSignature API