Configure signing information using the WSSSignature API
We can secure the SOAP messages, without using policy sets for configuration, using the Web Services Security APIs (WSS API). To configure the signing information for the generator binding sections for the client-side request, use the WSSSignature API. The WSSSignature API is part of the com.ibm.websphere.wssecurity.wssapi.signature package.
Either we can use the WSS API or we can configure the policy sets using the console to enable the signing information. To secure SOAP messages, you must complete the following signing tasks:
- Configure the signing information.
- Choose the signing methods.
- Add or change signed parts, as needed.
WAS 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 signing information specifies the integrity constraints that are applied to generated messages. The constraints include specifying which message parts within the generated message must be digitally signed, and the message parts to attach digitally signed Nonce and timestamp elements to. The following signature and related signature part information are configured:
signature parts Description keyword Add a signature part using keywords. Use the following keywords for the signature parts:
- ADDRESSING_HEADERS
- BODY
- TIMESTAMP
The WS-Addressing headers are not encrypted but can be signed.
xpath Add a signature part by using an XPath expression. part Add a WSSSignPart object as a target of the signature part. timestamp Add a WSSTimestamp object as a target of the signature part. When specified, the timestamp information also specifies when the message is generated and when it expires. header Add the header, specified by QName, as a target of the signature part. securityToken Add a SecurityToken object as a target of the signature part. For signing information, certain default behaviors occur. The simplest way to use the WSSSignature API is to use the default behavior (see the example code). The default values are defined by the WSS API for the signing method, the canonicalization method, the security token references, and the signature parts.
Signature decisions Default behavior Which keywords to use Sets the keywords. WebSphere Application Server supports the following keywords by default:
- ADDRESSING_HEADERS
- BODY
- TIMESTAMP
Which signature method to use Sets the signature algorithm. The default signature method is RSA SHA1. WebSphere Application Server supports the following pre-configured signature methods:
- WSSSignature.RSA_SHA1: http://www.w3.org/2000/09/xmldsig#rsa-sha1
- WSSSignature.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 Sets the canonicalization algorithm. The default canonicalization method is EXC C14N. WebSphere Application Server supports the following pre-configured canonicalization methods:
- WSSSignature.EXC_C14N; http://www.w3.org/2001/10/xml-exc-c14n#
- WSSSignature.C14N: http://www.w3.org/2001/10/xml-c14n#
Whether signature confirmation is required Sets whether to require signature confirmation. The default value is false. Signature confirmation is defined in the OASIS Web Services Security Version 1.1 specification. If required, the value of the signature confirmation is stored in order to use it to validate the signature confirmation after receiving back the message that generated the signature confirmation in the response message. This method is for the requestor side. Which security token to use Sets the SecurityToken. The token type specifies which type of token to use for signing and validating messages. The X.509 token is the default token type.
WebSphere Application Server provides the following pre-configured consumer token types:
- Derived Key Token
- X509 tokens
We can also create custom token types, as needed.
Which token reference to set Sets the refType. SecurityToken.REF_STR is the default value for the type of token reference. WebSphere Application Server supports these pre-configured token references types:
- SecurityToken.REF_STR
- SecurityToken.REF_KEYID
- SecurityToken.REF_EMBEDDED
- SecurityToken.REF_THUMBPRINT
If WSSSignature.requireSignatureConfirmation() is called, then the WSSSignature API expects that the response message will include the signature confirmation.
- To configure the signing information in a SOAP message using the WSS API, first ensure that the application server is installed.
- Use the WSSSignature API to sign the message parts and specify the algorithms in a SOAP message. The WSS API process for signature follows these process steps:
- Uses WSSFactory.getInstance() to get the WSS API implementation instance.
- Creates the WSSGenerationContext instance from the WSSFactory instance. WSSGenerationContext must be called in a JAX-WS client application.
- Creates the SecurityToken from WSSFactory to configure the key for signing.
- Creates WSSSignature from the WSSFactory instance using the SecurityToken. The default behavior of WSSSignature is to sign these signature parts: BODY, ADDRESSING_HEADERS, and TIMESTAMP.
- Add the part to be signed, if the default part is not appropriate. If the digest method or transform method is changed, creates WSSSignPart and add it to WSSSignature.
- Creates WSSSignaturePart to WSSSignature. Calls the requiredSignatureConfirmation() method, if the signature confirmation is to be applied.
- Sets the canonicalization method, if the default is not appropriate.
- Sets the signature method, if the default is not appropriate.
- Sets the token reference, if the default is not appropriate.
- Add WSSSignature to WSSGenerationContext.
- Calls WSSGenerationContext.process() with the SOAPMessageContext.
Results
You have completed the steps to configure the signature for the generator section of the bindings. If there is an error condition when signing the message parts, a WSSException is provided. If successful, the WSSGenerationContext.process() is called, and Web Services Security is applied to the SOAP message.
Example
The following example provides sample code that uses methods defined in the WSSignature API.
// Get the message context Object msgcontext = getMessageContext(); // Generate the com.ibm.websphere.wssecurity.wssapi.WSSFactory instance (step: a) WSSFactory factory = com.ibm.websphere.wssecurity.wssapi.WSSFactory.getInstance(); // Generate the WSSGenerationContext instance (step: b) WSSGenerationContext gencont = factory.newWSSGenerationContext(); // Generate the callback handler X509GenerateCallbackHandler callbackHandler = new X509GenerateCallbackHandler( "", "dsig-sender.ks", "jks", "client".toCharArray(), "soaprequester", "client".toCharArray(), "CN=SOAPRequester, OU=TRL, O=IBM, ST=Kanagawa, C=JP", null); // Generate the security token to be used for the signature (step: c) SecurityToken token = factory.newSecurityToken(X509Token.class, callbackHandler); // Generate the WSSSignature instance (step: d) WSSSignature sig = factory.newWSSSignature(token); // Set the part to be signed (step: e) // DEFAULT: WSSSignature.BODY, WSSSignature.ADDRESSING_HEADERS, // and WSSSignature.TIMESTAMP. // Set the part in the SOAP Header specified by QName (step: e) sig.addSignHeader(new QName("http://www.w3.org/2005/08/addressing", "MessageID")); // Set the part specified by the keyword (step: e) sig.addSignPart(WSSSignature.BODY); // Set the part specified by SecurityToken (step: e) UNTGenerateCallbackHandler untCallbackHandler = new UNTGenerateCallbackHandler("Chris", "sirhC"); SecurityToken unt = factory.newSecurityToken(UsernameToken.class, untCallbackHandler); sig.addSignPart(unt); // Set the part specified by WSSSignPart (step: e) WSSSignPart sigPart = factory.newWSSSignPart(); sigPart.setSignPart(WSSSignature.TIMESTAMP); sigPart.setDigestMethod(WSSSignPart.SHA256); sig.addSignPart(sigPart); // Set the part specified by WSSTimestamp (step: e) WSSTimestamp timestamp = factory.newWSSTimestamp(); sig.addSignPart(timestamp); // 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']"); sig.addSignPartByXPath(sb.toString()); // Set to apply the signature confirmation (step: f) sig.requireSignatureConfirmation(); // Set the canonicalization method (step: g) // DEFAULT: WSSSignature.EXC_C14N sig.setCanonicalizationMethod(WSSSignature.C14N); // Set the signature method (step: h) // DEFAULT: WSSSignature.RSA_SHA1 sig.setSignatureMethod(WSSSignature.HMAC_SHA1); // Set the token reference (step: i) // DEFAULT: SecurityToken.REF_STR sig.setTokenReference(SecurityToken.REF_KEYID); // Add the WSSSignature to WSSGenerationContext (step: j) gencont.add(sig); // Generate the WS-Security header (step: k) gencont.process(msgctx);The X509GenerationCallbackHandler needs the key password because the private key is used for signing.
What to do next
Next, chose the algorithm methods if we want a method that is different from the default values. If the algorithm methods do not need to be changed, next use the WSSVerification API to verify the signature and specify the algorithm methods in the consumer section of the binding. Note that the WSSVerification API is only supported on the response consumer (client side).
Related concepts
XML digital signature Signature confirmation
Related tasks
Configure generator security tokens using the WSS API Verify the signature using the WSSVerification API
Digital signing methods using the WSSSignature API