Verify signed parts in SOAP messages using the WSSVerifyPart API

Verify signed parts using the WSSVerifyPart API

To secure SOAP messages on the consumer side, use the Web Services Security APIs (WSS API) to configure the verify parts information for the consumer binding on the response consumer (client side). We can specify which algorithm methods and which parts of the SOAP message are to be verified. Use the WSSVerifyPart API to change the digest method or the transform method. The WSSVerifyPart API is part of the com.ibm.websphere.wssecurity.wssapi.verification package.

To secure SOAP messages using the signing verification information, we must complete one of the following tasks:

Configure the signature verification information using the WSSVerification API.

Configure verify parts using the WSSVerifyPart API, as needed.
The WSSVerifyPart is used for specify the transform or digest methods for the verification. Use the WSSVerifyPart API or configure policy sets using the console.

WAS uses the signing information for the default consumer to verify the signed parts of the message. The WSSVerifyPart API is only supported on the response consumer (requester).
The following table shows the required verification parts when the digital signature security constraint (integrity) is defined:

parts information. Use the verify parts to secure messages
Verify parts information Description
keyword Sets the verify parts using the following keywords:

BODY

ADDRESSING_HEADERS

TIMESTAMP

The WS-Addressing headers are not decrypted but can be signed and verified.
xpath Sets the verify parts using an XPath expression.
header Sets the header, specified by QName, as a required verify part.

For signature verification, certain default behaviors occur. The simplest way to use the WSSVerification API is to use the default behavior (see the example code). The default values are defined by the WSS API for the signing algorithm and the canonicalization algorithm, and the verify parts.

parts default behaviors. Several characteristics of verify
Verify parts decisions Default behavior
Which keywords to specify
The different SOAP message parts to be signed and used for message protection. WebSphere Application Server supports the following keywords:

WSSVerification.BODY

WSSVerification.ADDRESSING_HEADERS

WSSVerification.TIMESTAMP

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

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

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

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

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

Which digest method to use (algorithm) Sets the digest algorithm method. The digest method algorithm specified within the <DigestMethod> element is used in the <SigningInfo> element. The default digest method is SHA1.
WebSphere Application Server supports the following digest method algorithms:

WSSVerifyPart.SHA1: http://www.w3.org/2000/09/xmldsig#sha1

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

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

To verify signed parts using the WSSVerifyPart API, first ensure that the application server is installed.

Use the Web Services Security API to verify the verification in a SOAP message. The WSS API process for verifying the signature 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 the CallbackHandler to use for verification.

Create the WSSVerification object from the WSSFactory instance.

Creates WSSVerifyPart from the WSSFactory instance.

Sets the part to be verified, if the default is not appropriate.

Sets the candidates for the digest method, if the default is not appropriate.

Sets the candidates for the transform method, if the default is not appropriate.

Add WSSVerifyPart to WSSVerification.

Add WSSVerification to WSSConsumingContext.

Calls WSSConsumingContext.process() with the SOAPMessageContext.

Results
We have completed the steps to verify to verify the signed parts on the consumer side. If there is an error condition when verifying the signing information, a WSSException is provided. If successful, the WSSConsumingContext.process() is called, and Web Services Security is verified for the SOAP message.

Example

The following example provides sample code for the WSSVerification API process for verifying the signing information in a SOAP message:
// 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 certStore
      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 callback handler (step: c)  
   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 specified by WSSVerifyPart (step: e)
   WSSVerifyPart verPart = factory.newWSSVerifyPart();

// Set the part to be specified by the keyword (step: f)
   verPart.setRequiredVerifyPart(WSSVerification.BODY);

// Set the candidates for the digest method for verification (step: g)
// DEFAULT : WSSVerifyPart.SHA1
   verPart.addAllowedDigestMethod(WSSVerifyPart.SHA256);

// Set the candidates for the transform method for verification (step: h)
// DEFAULT : WSSVerifypart.TRANSFORM_EXC_C14N : String
   verPart.addAllowedTransform(WSSVerifyPart.TRANSFORM_STRT10);

// Set WSSVerifyPart to WSSVerification (step: i)
   ver.addRequiredVerifyPart(verPart);

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

//Validate the WS-Security header (step: k)
concont.process(msgcontext);
What to do next
We have completed configuring the signed part to be verified.

Related tasks

Configure the consumer security tokens using the WSS API
Verify the signature using the WSSVerification API
Signing and encrypting message parts using policy sets
Add signed parts using the WSSSignPart API

Choose the verify parts methods using the WSSVerifyPart API