You can secure the SOAP messages, without using policy sets for configuration, by 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 you can use the WSS API or you can configure the policy sets by using the administrative console to enable the signing information. To secure SOAP messages, you must complete the following signing 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 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 | Adds a signature part using keywords. Use
the following keywords for the signature parts:
|
xpath | Adds a signature part by using an XPath expression. |
part | Adds a WSSSignPart object as a target of the signature part. |
timestamp | Adds 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 | Adds the header, specified by QName, as a target of the signature part. |
securityToken | Adds 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:
|
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:
|
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:
|
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 your 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:
You 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:
|
If WSSSignature.requireSignatureConfirmation() is called, then the WSSSignature API expects that the response message will include the signature confirmation.
The following example provides sample code that uses methods that are defined in the WSSignature API.
// Get the message context Object msgcontext = getMessageContext(); // Generate the WSSFactory instance (step: a) WSSFactory factory = 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);
Next, chose the algorithm methods if you 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).
In this information ...Related tasks
Related reference
| IBM Redbooks, demos, education, and more(Index) |