You can configure the signing information for the client-side request
generator (sender) bindings. Signing information is used to sign and validate
parts of a message including the SOAP body, the timestamp information, and
the Username token. To configure the client for request signing, specify which
message parts to digitally sign when configuring the client.
Before you begin
WebSphere Application Server uses XML digital signature with existing
algorithms such as RSA, HMAC, and SHA1. XML signature defines many methods
for describing key information and enables the definition of a new method.
Prior to completing these steps, familiarize yourself with XML digital signature for signing
and verifying digital signatures for digital content.
About this task
By including XML signature in SOAP messages, the following issues
are realized: message integrity and authentication. Integrity refers
to digital signature whereas confidentiality refers to encryption. Integrity
decreases the risk of data modification while the data is transmitted across
the Internet. WebSphere Application Server uses the signing information for
the default generator to sign parts of the message, such as the body, time
stamp, and Username token.
For the signing information, you must specify
the following:
- Which parts of the message are to be signed.
- The key information that is referenced by the key information for the
signing keys.
- The signing algorithms.
WebSphere Application Server provides default values for bindings.
However, an administrator must modify the defaults for a production environment.
The
WSSSignature API configures the following parts as signature parts:
Table 1. Pre-configured signature parts
Security token object |
This object authenticates the client. If this option
is specified, then the message is signed. You can digitally sign the message
using a security token if a login configuration authentication method is selected. |
WSSTimestamp object |
This object adds a time stamp to a message. The time
stamp determines if the message is valid based on the time that the message
is sent and then received. |
WSSSignature Part object |
This object adds the signature parts to a message. |
SOAP header and the QName as a target |
This signature part adds the header, specified by QName,
as a verification part. |
The WSS APIs allow the use of keywords or an XPath expression to
specify which parts of the message are to be signed. WebSphere Application
Server supports the use of the following keywords:
Table 2. Supported
signature keywords
Keyword |
References |
ADDRESSING_HEADERS |
The Web Services Addressing (WS-Addressing)
headers. |
BODY |
The SOAP message body. The body is the user
data portion of the message. |
TIMESTAMP |
The creation and expiration timestamp information. |
The Web Services Security API (WSS API) are used to configure the
signing information for the request generator (client side) section of the
bindings file. To configure the signing information on the client side, use
the WSS APIs or configure policy sets for signing using the administrative
console.
If configuring using the WSS APIs, the WSSSignature and WSSSignPart
APIs complete the following steps to specify which message parts to digitally
sign when configuring the client for request generator signing:
Procedure
- The WSSSignature API adds the required parts of the SOAP message
to digitally sign. Either a keyword or an XPath expression can
be used to specify the required encryption parts.
- The WSSSignature API sets the signature method algorithm.
The default signature method is RSA_SHA1. WebSphere Application Server
supports the following pre-configured algorithms:
WebSphere Application Server does not support the following algorithm
for DSA-SHA1: http://www.w3.org/2000/09/xmldsig#dsa-sha1. You cannot use the
DSA-SHA1 algorithm if you want to be compliant with the Basic Security Profile
(BSP).
Any ds:SignatureMethod/@Algorithm element in a signature is based
on a symmetric key and must have a value of RSA-SHA1 or HMAC-SHA1.
The
algorithm that is specified for the request generator configuration must match
the algorithm that is specified for the request consumer configuration.
- The WSSSignature API sets the canonicalization method. The
default signature method is EXC_C14N. WebSphere Application Server supports
the following pre-configured algorithms:
- The URI of the exclusive canonicalization algorithm, EXC_C14N: http://www.w3.org/2001/10/xml-exc-c14n#.
- The URI of the inclusive canonicalization algorithm, C14N: http://www.w3.org/2001/10/xml-c14n#.
The canonicalization algorithm that you specify for the generator
must match the algorithm for the consumer.
- The WSSSignature API adds a security token. The API
adds information about the security token that is to be used for the signature,
such as:
- The class for security token.
- The callback handler
- The name of the JAAS login configuration.
- The WSSSignature API sets the type of security token and sets the
type of token reference. WebSphere Application Server supports
the following pre-configured token references:
- SecurityToken.REF_STR
Represents the security token reference as a token
reference type.
- SecurityToken.REF_KEYID
Represents the key identifier reference as a
token reference type.
- SecurityToken.REF_EMBEDDED
Represents the embedded reference as a token
reference type.
- SecurityToken.REF_THUMBPRINT
Represents the thumbprint reference as
a token reference type.
- If SecurityToken.REF_KEYID is set as the type of token reference,
the WSSSignature API sets the key information signature type and configures
the key information that is referenced by the key information references.
WebSphere Application Server supports the following:
- Specifying that the KeyInfo element is not signed.
- Specifying that the entire <KeyInfo> element is signed.
- Specifying that the child elements <Keyinfochildelements> of the <KeyInfo>
element are signed.
If you do not specify one of the previous signature types, WebSphere
Application Server specifies that the entire <KeyInfo> element is signed,
by default.
If you select Keyinfo or Keyinfochildelements and you select
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#STR-Transform
as the transform algorithm in a subsequent step, WebSphere Application Server
also signs the referenced token.
The key information signature type
for the generator must match the signature type for the consumer.
- The WSSSignature API specifies whether to require signature confirmation.
The OASIS Web Services Security (WS-Security) Version 1.1 specification
defines the use of signature confirmation. If you are using WS-Security Version
1.0, this function is not available.
The signature confirmation value is
stored in order to validate the signature confirmation with it after the receiving
message is returned. This method is called if the response message is expected
to attach the signature confirmation into the SOAP message.
- The WSSSignPart API specifies the part reference. The
part reference specifies which parts of the message to digitally sign.
The part reference refers to the message part that is digitally signed. The
part attribute refers to the name of the <Integrity> element when the <PartReference>
element is specified for the signature. You can specify multiple <PartReference>
elements within the <SigningInfo> element. The <PartReference> element
has two child elements when it is specified for the signature verification: <DigestTransform>
and <Transform>.
- The WSSSignPart API specifies the digest method algorithm.
The digest method algorithm specified within the <DigestMethod> element
is used in the <SigningInfo> element.
WebSphere Application Server supports
the following pre-configured digest algorithms:
- http://www.w3.org/2000/09/xmldsig#sha1
- http://www.w3.org/2001/04/xmlenc#sha256
- http://www.w3.org/2001/04/xmlenc#sha512
- The WSSSignPart API specifies the transform algorithm. The
transform algorithm is that is specified within the <Transform> element
and specifies the transform algorithm for the signature. WebSphere Application
Server supports the following pre-configured transform algorithms:
The transform algorithm that you select for the generator must match
the transform algorithm that you select for the consumer.
Important: If
both of the following conditions are true, WebSphere Application Server signs
the referenced token:
- You previously selected the Keyinfo or the Keyinfochildelements option
- You select http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#STR-Transform
as the transform algorithm.
- If you configure the client and server signing information correctly,
but receive a Soap body not signed error when running the
client, you might need to configure the actor. Configure policy
sets using the administrative console to configure the same actor strings
for the Web service on the server, which processes the request and sends the
response back.
The actor information on both the client and server must
refer to the same exact string. When the actor fields on the client and server
match, the request or response is acted upon instead of being forwarded downstream.
The actor might be different when you have Web services acting as a gateway
to other Web services. However, in all other cases, make sure that the actor
information matches on the client and server. When Web services are acting
as a gateway and they do not have the same actor configured as the request
passing through the gateway, Web services do not process the message from
a client. Instead, these Web services send the request downstream. The downstream
process that contains the correct actor string processes the request. The
same situation occurs for the response. Therefore, it is important that you
verify that the appropriate client and server actor fields are synchronized.
Results
After the WSSSignature and WSSSignPart APIs complete these steps,
the signing information is configured for the generator sections of the bindings
files.
Example
The following example shows WSS API sample code to configure the
signature, to generate the callback handler, and to specify the X.509 token
type as the security token:
WSSFactory factory = WSSFactory.getInstance();
// Instantiate a generation context
WSSGenerationContext gencont = factory.newWSSGenerationContext();
// Generate the callback handler and specify the X.509 token
X509GenerateCallbackHandler callbackhandler = generateCallbackHandler();
SecurityToken token = factory.newSecurityToken(X509Token.class,
callbackHandler);
// Set the signature information
WSSSignature sig = factory.newWSSSignature(token);
// Add the header using QName
sig.addSignHeader(new QName("http://www.w3.org/2005/08/addressing", "To"));
sig.addSignHeader(new QName("http://www.w3.org/2005/08/addressing", "MessageID"));
sig.addSignHeader(new QName("http://www.w3.org/2005/08/addressing", "Action"));
// Apply the signature
gencont.add(sig);
// Secure the message
gencont.process(msgctx);
What to do next
You must configure similar signature information for the client-side
request consumer (receiver) bindings by completing the following verification
tasks:
- Verify the signature
- Choose the signature algorithm methods.
- Change or add signed parts, as needed.
If signature verification is already configured, configure the
encryption and decryption information, or configure the consumer and generator
tokens.