You can configure the signing information for the client-side
response consumer (receiver) bindings. Signing information is used
to sign and validate parts of a message including the SOAP body, the
timestamp information, and the Username token.
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, read the information about XML digital signature to become
familiar with signing and verifying digital signatures for digital
content.
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.
Before you can verify the signature
and SOAP message signed parts, you must have completed the following
tasks:
- Configured the signature.
- Added signed parts, as needed.
- Chosen the signature and signed parts methods.
About this task
Use the Web Services Security APIs (WSS API) to configure
the signing verification information for the response consumer (client
side) section of the bindings file. Use the WSSVerification or WSSVerifyPart
APIs to configure the client for request signature verification and
to specify which digitally signed message parts to verify.
WebSphere Application Server uses the signing
information on the consumer side to verify the integrity of the received
SOAP message by validating that the message parts (such as the body,
time stamp, and Username token) are signed.
On the client side,
use the WSS APIs, or configure policy sets using the administrative
console to specify which parts of the message are signed and to configure
the key information that is referenced by the key information references.
To verify the signature and signed parts, use the WSSVerification
and WSSVerifyPart APIs.
WebSphere Application Server
provides default values for bindings. However, an administrator must
modify the defaults for a production environment.
The WSSVerification
and WSSVerifyPart APIs complete the following steps to specify which
digitally signed message parts to verify when configuring the client
for response consumer signing:
Procedure
- The WSSVerification API adds the required verify parts
of the SOAP message.
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: <DigestTransform>
and <Transform>.
The
WSSVerification API configures the following parts as verification
parts:
Security token |
Adds information for the security token that is used for
the signature verification. |
SOAP header and the QName as a target |
Adds the SOAP 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 verified. WebSphere Application Server supports the
use of the following keywords:
Keyword |
References |
WSSVerification.ADDRESSING_HEADERS |
The Web Services Addressing (WS-Addressing) headers. |
WSSVerification.BODY |
The SOAP message body. The body is the user data portion
of the message. |
WSSVerification.TIMESTAMP |
The creation and expiration timestamp information. |
- The WSSVerification API adds the required header to the
SOAP message. The header, specified by QName, is a required
verification header.
- The WSSVerification API adds a security token. Adds
information about the security token that is to be used for the signature
verification, such as:
- The class for security token.
- The callback handler
- The name of the JAAS login configuration.
- The WSSVerification API adds the signature method algorithm.
The signature method is the algorithm that is used to convert
the canonicalized <SignedInfo> element in the binding file into
the <SignatureValue> element. The algorithm that is specified
for the consumer, which is the response consumer configuration, must
match the algorithm specified for the request generator configuration. WebSphere Application Server supports the
following pre-configured signature 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).
- The WSSVerification API adds a canonicalization method.
The canonicalization method algorithm is used to canonicalize
the <SignedInfo> element before it is incorporated as part of
the digital signature operation. The canonicalization algorithm that
you specify for the generator must match the algorithm for the consumer.
WebSphere Application Server supports the
following pre-configured canonicalization algorithms:
- The WSSVerification API verifies whether a signature confirmation
is required. 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 WSSVerifyPart API adds a digest method. For
each part reference in the signing information, the API specifies
both a digest method algorithm and a transform algorithm.
WebSphere Application Server supports the
following pre-configured digest algorithms:
- WSSVerifyPart.SHA1: http://www.w3.org/2000/09/xmldsig#sha1
- WSSVerifyPart.SHA256: http://www.w3.org/2001/04/xmlenc#sha256
- WSSVerifyPart.SHA512: http://www.w3.org/2001/04/xmlenc#sha512
- The WSSVerifyPart API adds a transform method. For
each part reference in the signing information, the API specifies
both a digest method algorithm and a transform algorithm.
WebSphere Application Server supports the
following pre-configured transform algorithms:
- WSSVerifyPart.TRANSFORM_EXC_C14N (the default value): http://www.w3.org/2001/10/xml-exc-c14n#
- WSSVerifyPart.TRANSFORM_XPATH2_FILTER: http://www.w3.org/2002/06/xmldsig-filter2
- WSSVerifyPart.TRANSFORM_STRT10: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#STR-Transform
- WSSVerifyPart.TRANSFORM_ENVELOPED_SIGNATURE: http://www.w3.org/2000/09/xmldsig#enveloped-signature
For the WSS APIs, WebSphere Application Server
does not support these algorithms:
- http://www.w3.org/2002/07/decrypt#XML
- http://www.w3.org/TR/1999/REC-xpath-19991116
The transform algorithm for the consumer must match the transform
algorithm for the generator.
Results
You
have completed the steps to configure the signing information for
the client-side response consumer sections of the bindings files.
Example
The following example shows WSS API sample code to verify
the signature and to verify the X.509 token type as the security token:
WSSFactory factory = WSSFactory.getInstance();
WSSConsumingContext concont = factory.newWSSConsumingContext();
// Generate the X.509 Callback Handler on the consumer side
X509ConsumeCallbackHandler callbackhandler = generateCallbackHandler();
WSSVerification ver = factory.newWSSVerification(X509Token.class,
callbackhandler);
concont.add(ver);
What to do next
If not already configured, specify a similar signing information
configuration for the generator bindings.
Next, if already configured,
configure the encryption and decryption information, or configure
the consumer and generator tokens.