+

Search Tips   |   Advanced Search

Set the signing information using the WSS APIs


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.

WAS 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 theself with XML digital signature for 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. WAS 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, specify the following:

WAS 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. We 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. WAS 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 WS-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 admin 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:

 

  1. 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.

  2. The WSSSignature API sets the signature method algorithm.

    The default signature method is RSA_SHA1. WAS supports the following pre-configured algorithms:

    WAS does not support the following algorithm for DSA-SHA1: http://www.w3.org/2000/09/xmldsig#dsa-sha1. We cannot use the DSA-SHA1 algorithm 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 specified for the request generator configuration must match the algorithm specified for the request consumer configuration.

  3. The WSSSignature API sets the canonicalization method. The default signature method is EXC_C14N. WAS 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 specified for the generator must match the algorithm for the consumer.

  4. 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:

  5. The WSSSignature API sets the type of security token and sets the type of token reference. WAS 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.

  6. 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.

    WAS 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 we do not specify one of the previous signature types, WAS specifies that the entire <KeyInfo> element is signed, by default.

    If we 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, WAS also signs the referenced token.

    The key information signature type for the generator must match the signature type for the consumer.

  7. The WSSSignature API specifies whether to require signature confirmation. The OASIS WS-Security V1.1 specification defines the use of signature confirmation. If using WS-Security V 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.

  8. 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. We 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>.

  9. The WSSSignPart API specifies the digest method algorithm.

    The digest method algorithm specified within the <DigestMethod> element is used in the <SigningInfo> element. WAS 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

  10. The WSSSignPart API specifies the transform algorithm. The transform algorithm is specified within the <Transform> element and specifies the transform algorithm for the signature. WAS supports the following pre-configured transform algorithms:

    • http://www.w3.org/2001/10/xml-exc-c14n#

    • http://www.w3.org/TR/1999/REC-xpath-19991116

      Do not use this transform algorithm to be compliant with the Basic Security Profile (BSP). Instead use http://www.w3.org/2002/06/xmldsig-filter2 to ensure compliance.

    • http://www.w3.org/2002/06/xmldsig-filter2

    • http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#STR-Transform

    • http://www.w3.org/2002/07/decrypt#XML

    • http://www.w3.org/2000/09/xmldsig#enveloped-signature

    The transform algorithm that you select for the generator must match the transform algorithm that you select for the consumer.

    If both of the following conditions are true, WAS 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.

  11. If we configure the client and server signing information correctly, but receive a Soap body not signed error when running the client, we might need to configure the actor. Set policy sets using the admin 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 we 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);

 

Next steps

You must configure similar signature information for the client-side request consumer (receiver) bindings by completing the following verification tasks:

If signature verification is already configured, configure the encryption and decryption information, or configure the consumer and generator tokens.

 

Related concepts


XML digital signature

 

Related tasks


Set the signature information using the WSSSignature API
Add signed parts using the WSSSignPart API
Set generator signing information to protect message integrity using the WSS APIs

 

Related


Signed parts methods using the WSSSignPart API
Digital signing methods using the WSSSignature API