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. Use the signing
information to validate parts of a message.Part |
Description |
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. Key information
is used to specify which parts of a message are signed.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.