Verify the signature using the WSSVerification API

Verify the signature using the WSSVerification API

We can secure the SOAP messages, without using policy sets for configuration, using the Web Services Security APIs (WSS API). To verify the signing information for the consumer binding sections for the client side request, use the WSSVerification API. We 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 using the console to verify the signing information. To secure SOAP messages, complete the following signature tasks:

Configure 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 methods for describing key information and enables the definition of a new method. XML canonicalization (C14N) is often needed when using 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.

verification parts. Use the signature verification parts
Verification parts Description
keywords
Add required signature parts as targets of verification 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 Add verification parts using an XPath expression.
part Add the WSSVerifyPart object as a verification part.
header Add 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.

default behaviors. Several characteristics of the signature
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. WebSphere Application Server 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. WebSphere Application Server 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 Web Services Security Version 1.1 specification.
The default signature confirmation is false.
Which security token to specify (securityToken)
Add the securityToken object as a signature part. WebSphere Application Server sets the token information to use for verification.
WebSphere Application Server 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.

To verify the signature in a SOAP message using the WSSVerification API, first ensure that the application server is installed.

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:

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

Creates the WSSConsumingContext instance from the WSSFactory instance.

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.

Creates WSSVerification from the WSSFactory instance.

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

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

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

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

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

Add WSSVerification to WSSConsumingContext.

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 Web Services 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);
What to do next

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

Related tasks

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

Signature verification methods using the WSSVerification API

Verification parts	Description
keywords	Add required signature parts as targets of verification 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	Add verification parts using an XPath expression.
part	Add the WSSVerifyPart object as a verification part.
header	Add the header, specified by QName, as a verification part.

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. WebSphere Application Server 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. WebSphere Application Server 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 Web Services Security Version 1.1 specification. The default signature confirmation is false.
Which security token to specify (securityToken)	Add the securityToken object as a signature part. WebSphere Application Server sets the token information to use for verification. WebSphere Application Server 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.