Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop web services - Security (WS-Security) > Develop applications that use Web Services Security > Develop message-level security for JAX-WS web services > Secure web services applications using the WSS APIs at the message level > Secure messages at the response consumer using WSS APIs > Verify consumer signing information to protect message integrity using WSS APIs


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

To secure SOAP messages using the signing verification information, 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 admin 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:

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.

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

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

WAS 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.
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
Secure messages at the response consumer using WSS APIs


Related


Choosing the verify parts methods using the WSSVerifyPart API

+

Search Tips   |   Advanced Search