Verifying the signature using the WSSVerification API

We can secure the SOAP messages, without using policy sets for configuration, by using the WS-Security APIs (WSS API). To verify the signing information for the consumer binding sections for the client side request, use the WSSVerification API. You must also specify which algorithm methods and which signature parts of the SOAP message are to be verified. The WSSVerification API is part of the com.ibm.websphere.wssecurity.wssapi.verification package.

Use the WSS APIs, or configure the policy sets by using the admin console to verify the signing information. To secure SOAP messages, complete the following signature tasks:

• Set the signature information.

• Choose the algorithm methods for signature and signature verification.

• Verify the signature information.

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 following table shows the required and optional binding information when the digital signature security constraint (integrity) is defined.

Table 1. Signature verification parts

Verification parts	Description
keywords	Adds required signature parts as targets of verification by using keywords . Different message parts can be specified in the message protection for request on the generator side. Use the following keywords for the required signature verification parts: ADDRESSING_HEADERS BODY TIMESTAMP The WS-Addressing headers are not encrypted but can be signed.
xpath	Adds verification parts by using an XPath expression.
part	Adds the WSSVerifyPart object as a verification part.
header	Adds the header, specified by QName, as a verification part.

For signature verification information, certain default behaviors occur. The simplest way to use the WSSVerification API is to use the default behavior.

The default values are defined by the WSS API for the digest method, the transform method, the security token, and the required verification parts.

Table 2. Signature verification default behaviors

Signature verification decisions	Default behavior
Which signature method to use (algorithm)	Sets the signature algorithm method. Both the data encryption and the signature and the canonicalization can be specified. The default signature method is RSA SHA1. WAS supports the following pre-configured signature methods: WSSVerification.RSA_SHA1: http://www.w3.org/2000/09/xmldsig#rsa-sha1 WSSVerification.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 (algorithm)	Sets the canonicalization algorithm method. Both the data encryption and the signature and the canonicalization can be specified. The default signature method is EXC_C14N. WAS supports the following pre-configured canonicalization methods: WSSVerification.EXC_C14N: http://www.w3.org/2001/10/xml-exc-c14n# WSSVerification.C14N: http://www.w3.org/2001/10/xml-c14n#
Whether signature confirmation is required	If the WSSSignature API specifies that signature confirmation is required, then the WSSVerification API verifies the signature confirmation value in the response message that has the signature confirmation value attached to it when received. Signature confirmation is defined in the OASIS WS-Security V1.1 specification. The default signature confirmation is false.
Which security token to specify (securityToken)	Adds the securityToken object as a signature part. WAS sets the token information to use for verification. WAS supports the following pre-configured tokens for signing: X.509 Token Derived Key Token Information required for tokens include the class for the token, the callback handler information, and the name of the JAAS login module.

 

1. To verify the signature in a SOAP message by using the WSSVerification API, first verify the appserver is installed.

2. Use the WSSVerification API to set the message parts to be verified and to specify the algorithms in a SOAP message. The WSS API process for signature verification follows these process steps:

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

   2. Creates the WSSConsumingContext instance from the WSSFactory instance.

   3. Ensures that WSSConsumingContext is called in the JAX-WS Provider implementation class. Due to the nature of the JAX-WS programming model, a JAX-WS provider needs to be implemented and must call the WSSConsumingContext to verify the SOAP message signature.

   4. Creates WSSVerification from the WSSFactory instance.

   5. Adds the part to be verified. If the digest method or the transform method are changed, create WSSVerifyPart and set it into WSSVerification.

   6. Sets the candidates of the canonicalization method, if the default is not appropriate.

   7. Sets the candidates of the signature method, if the default is not appropriate.

   8. Sets the candidate security token, if the default is not appropriate.

   9. Calls the requireSignatureConfirmation(), if the signature confirmation is applied.

   10. Adds WSSVerification to WSSConsumingContext.

   11. Calls WSSConsumingContext.process() with the SOAP message context.

 

Results

we have completed the steps to verify the signature for the consumer section of the bindings. If there is an error condition, a WSSException is provided. If successful, the WSSConsumingContext.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 WSSVerification API:

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


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


// Generate the WSSConsumingContext instance (step: b)
   WSSConsumingContext concont = factory.newWSSConsumingContext();



// Generate the certificate list
   String certpath = "c:/WebSphere/AppServer/etc/ws-security/samples/intca2.cer";

// The location of the X509 certificate file
   X509Certificate x509cert = null;
      try {
        InputStream is = new FileInputStream(certpath);
        CertificateFactory cf = CertificateFactory.getInstance("X.509");
        x509cert = (X509Certificate)cf.generateCertificate(is);
        } catch(FileNotFoundException e1){
          throw new WSSException(e1);
        } catch (CertificateException e2) {
          throw new WSSException(e2);
        }
      Set<Object> eeCerts = new HashSet<Object>();
        eeCerts.add(x509cert);  

// Create the certificate store
    java.util.List<CertStore> certList = new java.util.ArrayList<CertStore>();
    CollectionCertStoreParameters certparam = new CollectionCertStoreParameters(eeCerts);
    CertStore cert = null;
    try {
      cert = CertStore.getInstance("Collection", certparam, "IBMCertPath");
    } catch (NoSuchProviderException e1) {
      throw new WSSException(e1);
    } catch (InvalidAlgorithmParameterException e2) {
      throw new WSSException(e2);
    } catch (NoSuchAlgorithmException e3) {
      throw new WSSException (e3);
    }
    if(certList != null ){
      certList.add(cert);
    }

// Generate the callback handler
    X509ConsumeCallbackHandler callbackHandler = new X509ConsumeCallbackHandler(
        "dsig-receiver.ks", 
        "jks",         "server".toCharArray(), 
        certList, 
        java.security.Security.getProvider("IBMCertPath")
    );


// Generate the WSSVerification instance (step: d)
   WSSVerification ver = factory.newWSSVerification(X509Token.class, callbackHandler);


// Set the part to be verified (step: e)

// DEFAULT: WSSVerification.BODY, WSSSignature.ADDRESSING_HEADERS, 

// and WSSSignature.TIMESTAMP.


// Set the part in the SOAP header to be specified by QName (step: e)
      ver.addRequiredVerifyHeader(new QName("http://www.w3.org/2005/08/addressing", "MessageID"));


// Set the part to be specified by the keyword (step: e)
      ver.addRequiredVerifyPart(WSSVerification.BODY);


// Set the part to be specified by WSSVerifyPart (step: e)
   WSSVerifyPart verPart = factory.newWSSVerifyPart();
      verPart.setRequiredVerifyPart(WSSVerification.BODY);
      verPart.addAllowedDigestMethod(WSSVerifyPart.SHA256);
      ver.addRequiredVerifyPart(verPart);


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



// Set one or more canonicalization method candidates for verification (step: f)

// DEFAULT : WSSVerification.EXC_C14N
     ver.addAllowedCanonicalizationMethod(WSSVerification.C14N);
     ver.addAllowedCanonicalizationMethod(WSSVerification.EXC_C14N);


// Set one or more signature method candidates for verification (step: g)

// DEFAULT : WSSVerification.RSA_SHA1
     ver.addAllowedSignatureMethod(WSSVerification.HMAC_SHA1);


// Set the candidate security token to used for the verification (step: h)
   X509ConsumeCallbackHandler callbackHandler2 = getCallbackHandler2();
     ver.addToken(X509Token.class, callbackHandler2);



// Set the flag to require the signature confirmation (step: i)
    ver.requireSignatureConfirmation();


// Add the WSSVerification to the WSSConsumingContext (step: j)
   concont.add(ver);


//Validate the WS-Security header (step: k) concont.process(msgcontext);

 

Next steps

After verifying the signature and setting algorithm methods for the SOAP message, we can set either the digest method or the transform method. To set these methods, use the WSSVerifyPart API, or configure policy sets using the admin console.

 

Related tasks

Verifying the signed parts using the WSSVerifyPart API
Set the consumer security tokens using the WSS API
Signing and encrypting message parts using policy sets
Set the signature information using the WSSSignature API
Secure messages at the response consumer using WSS APIs

 

Related

Signature verification methods using the WSSVerification API