Verifying 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). You 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.

Before you begin

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

The WSSVerifyPart is used for specify the transform or digest methods for the verification. Use the WSSVerifyPart API or configure policy sets using the administrative console.

About this task

WebSphere® Application Server 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:

Table 1. Verify parts information. Use the verify parts to secure messages with signing verification information.
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.

Table 2. Verify parts default behaviors. Several characteristics of verify parts are configured by default.
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) Adds 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 that is 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

Procedure

  1. To verify signed parts by using the WSSVerifyPart API, first ensure that the application server is installed.
  2. 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:
    1. Uses WSSFactory.getInstance() to get the WSS API implementation instance.
    2. 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.
    3. Creates the CallbackHandler to use for verification.
    4. Create the WSSVerification object from the WSSFactory instance.
    5. Creates WSSVerifyPart from the WSSFactory instance.
    6. Sets the part to be verified, if the default is not appropriate.
    7. Sets the candidates for the digest method, if the default is not appropriate.
    8. Sets the candidates for the transform method, if the default is not appropriate.
    9. Adds WSSVerifyPart to WSSVerification.
    10. Adds WSSVerification to WSSConsumingContext.
    11. Calls WSSConsumingContext.process() with the SOAPMessageContext.

Results

You 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

You have completed configuring the signed part to be verified.



In this information ...


IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic    

Terms of Use | Feedback

Last updated: Oct 21, 2010 5:30:17 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-nd-iseries&topic=twbs_confsignaturepartcon
File name: twbs_confsignaturepartcon.html