You can secure the SOAP messages, without using policy sets for configuration, by 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 by using the administrative console to verify the signing information. To secure SOAP messages, you must complete the following signature tasks:
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 you 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.
Verification parts | Description |
---|---|
keywords | Adds required signature parts as targets
of verification by 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:
|
xpath | Adds verification parts by 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 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:
|
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:
|
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) | Adds 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:
|
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, you can set either the digest method or the transform method. If you want to set these methods, use the WSSVerifyPart API, or configure policy sets using the administrative console.
In this information ...Related tasks
Related reference
| IBM Redbooks, demos, education, and more(Index) |