Verifying the signature using the WSSVerification API

WAS v8.5 > Develop 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 > Verifying consumer signing information to protect message integrity using WSS APIs
Verifying 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. 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 using the dmgr console to verify the signing information. To secure SOAP messages, you must complete the following signature tasks:

Configure the signature information.
Choose the algorithm methods for signature and signature verification.
Verify the signature information.
WebSphere Application Server 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 we 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.
Signature verification parts. Use the signature verification parts to secure messages.

Verification parts Description
keywords
Adds 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 Adds verification parts 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.
Signature verification default behaviors. Several characteristics of the signature verification parts are configured by default.

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 Web Services 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.

To verify the signature in a SOAP message using the WSSVerification API, first ensure 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 JAX-WS, 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.

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

Adds WSSVerification to WSSConsumingContext.
Calls WSSConsumingContext.process() with the SOAP message context.

Results
You 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 that are 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);
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 dmgr console.

Related

Verifying 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

Reference:

Signature verification methods using the WSSVerification API

+
Search Tips | Advanced Search

Verification parts	Description
keywords	Adds 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	Adds verification parts using an XPath expression.
part	Adds the WSSVerifyPart object as a verification part.
header	Adds 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. 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 Web Services 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.