Configure Web Services Security using the WSS APIs

The Web Services Security APIs (WSS API) provide support for securing SOAP message.

Web Service Security supports the following programming models:

• Programming API for securing SOAP message with Web Services Security (WSS API).

  The API programming model design has been redesigned. The new design is an interface-based programming model and is based on Web Services Security Version 1.1 standards but the design also includes support for Web Services Security Version 1.0 for securing the SOAP message. The WSS API programming model implementation is a simplified version, which is based on an early draft proposal of JSR-183, which is the JSR for defining Java API binding for Web Services Security. By design, because the application code is programmed to the interface, any application code that is programmed with the open source implementation should be able to run on the WAS with minimal changes or no changes at all.

• Service Programming Interfaces (SPI) for a service provider

  Similarly, the Web Services Security run time token generation and token consuming SPI have been redesign so that the same security token interface and JAAS Login Module implementation can be used for both the WSS API and the SPI. The WSS SPI for the service provider extend the security token types and provide keys and deriving keys for signing, signature verification, encryption and decryption.

Usage statement: We must use the IBM implementation of the WS-Security standards in the context of web services.

These programming models extend the following functions :

• Security token types and deriving keys for signing

• Signature and verification

• Encryption and decryption

The following figure demonstrates how to use the simplified WSS APIs to secure a SOAP message using XML digital signature and XML encryption.

The configuration model for web services has also been redesigned from a deployment descriptor model to a policy set model. The configuration programming model is based on configuring policy sets using a security policy to specify security constraints.

The functions provided by the policy set configurations are the same as the functions supported by the WSS API for the Web Services Security run time. However, the security policy defined using policy sets has a higher priority over the WSS API. When the WSS API and the policy set are both used in the application, the default behavior is for the security policy from the policy set to be enforced and the WSS API to be ignored. To use the WSS API in the application, verify there is no policy set attached to the application or to the application resources, or make sure there is no security policy in the attached policy set.

Web Service Security can be enabled by either using a policy set configured using the console, or using the WSS API for configuration.

Use the WSS API, complete the following high-level steps to secure the SOAP message:

1. Use the WSSSignature API to configure the signing information for the request generator (client side) binding.

   Different message parts can be specified in the message protection for a request on the generator side. The default required parts are BODY, ADDRESSING_HEADERS, and TIMESTAMP.

   The WSSSignature API also specifies the different algorithm methods to be used with the signature for message protection. The default signature method is RSA_SHA1. The default canonicalization method is EXC_C14N.

2. Use the WSSSignPart API to add or change the signed parts to be used for message protection.

   The default signed parts are WSSSignature.BODY, WSSSignature.ADDRESSING_HEADERS, and WSSSignature.TIMESTAMP.

   The WSSSignPart API also specifies the different algorithm methods to be used if you added or changed the signed parts. The default digest method is SHA1. The default transform method is TRANSFORM_EXC_C14N. For example, use the WSSSignPart API to generate the signature for the SOAP message using the SHA256 digest method instead of the default value of SHA1.

3. Use the WSSEncryption API to configure the encryption information on the request generator side.

   The encryption information on the generator side is used for encrypting an outgoing SOAP message for the request generator (client side) bindings. The default targets of encryption are BODY_CONTENT and SIGNATURE

   The WSSEncryption API also specifies the different algorithm methods to be used to protect message confidentiality. The default data encryption method is AES128. The default key encryption method is KW_RSA_OAEP.

4. Use the WSSEncryptPart API to add or change the encrypted parts to be used for message confidentiality.

   For example, to change the data encryption method from the default value of AES128 to TRIPLE_DES.

   No algorithm methods are required for encrypted parts.

5. Use the WSS API to attach the token on the generator side.

   The requirements for the security token depend on the token type. The JAAS Login Module and the JAAS CallbackHandler are responsible for creating the security token on the generator side. Different stand-alone tokens can be sent in request or response. The default token is the X509Token. The other token that can be used for signing is the DerivedKeyToken, which is used only with Web Services Secure Conversation (WS-SecureConversation).

6. Use the WSSVerification API to verify the signature for the response consumer (client side) binding.

   Different message parts can be specified in the message protection for a response on the consumer side. The required targets for verification are BODY, ADDRESSING_HEADERS, and TIMESTAMP.

   The WSSVerification API also specifies the different algorithm methods to be used for verifying the signature and for message protection. The default signature method is RSA_SHA1. The default canonicalization method is EXC_C14N.

7. Use the WSSVerifyPart API to add or change the verify signed parts to be used for message protection.

   The required verify parts are WSSVerification.BODY, WSSVerification.ADDRESSING_HEADERS, and WSSVerification.TIMESTAMP.

   The WSSVerifyPart API also specifies the different algorithm methods to be used if you added or changed the verification parts. The default digest method is SHA1. The default transform method is TRANSFORM_EXC_C14N.

8. Use the WSSDecryption API to configure the decryption information for the response consumer (client side) binding.

   The decryption information on the consumer side is used for decrypting an incoming SOAP message. The default targets of decryption are BODY_CONTENT and SIGNATURE. The default data encryption method is AES128. The default key encryption method is KW_RSA_OAEP.

   No algorithm methods are required for decryption.

9. Use the WSSDecryptPart API to add or change the decrypted parts to be used for message confidentiality.

   For example, to change the data encryption method from the default value of AES128 to TRIPLE_DES.

   No algorithm methods are required for decrypted parts.

10. Use the WSS API to configure the token on the consumer side.

    The requirements for the security token depend on the token type. The JAAS Login Module and the JAAS CallbackHandler are responsible for validating (authenticating) the security token on the consumer side. Different stand-alone tokens can be sent in request or response.

    The WSS API adds the information for the candidate token used for decryption. The default token is X509Token.

Results

What to do next

The Web Services Security run time token generation and token consuming Service Programming Interfaces (SPI) have been redesign so that the same Security Token interface and JAAS Login Module implementation can be used in both the WSS API and the SPI. See the SPI information for detail descriptions.

Subtopics

• Web Services Security APIs
  The Web Services Security programming model provides APIs (WSS API) for securing the SOAP message. The WSS API model is based on Web Services Security Version 1.1 standards but also includes support for Web Services Security Version 1.0.

• Web Services Security configuration considerations when using the WSS API
  To secure Web Services Security for WebSphere Application Server, we can specify several different configurations using the Web Services Security APIs (WSS API). The Web Services Security specification provides a flexible way to secure web services messages using XML digital signature, XML encryption, and attaching security tokens. We can enable Web Services Security by either configuring a policy set or using the Web Services Security APIs (WSS API). The implementation for WSS API has default values for which message parts are to be signed or encrypted. The default values for the WSS APIs help end users to enable Web Services Security quickly.

Related concepts

Web Services Security API programming model