Set WS-Security using the WSS APIs

The WS-Security APIs (WSS API) provide support for securing SOAP message.

Web Service Security supports the following models:

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

  The API model design has been redesigned. The new design is an interface-based model and is based on WS-Security V1.1 standards but the design also includes support for WS-Security V1.0 for securing the SOAP message. The WSS API 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 Service 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 Service 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: Use the IBM implementation of the WS-Security standards in the context of Web services.

These 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 by 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 Service Security run time. However, the security policy that is 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, make sure that 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 by using the admin console, or by 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 we 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 standalone 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 we 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 standalone 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

 

Next steps

The Web Service 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.

WS-Security APIs
WS-Security configuration considerations when using the WSS API

 

Related concepts

WS-Security API model

 

Related tasks

Secure Web services applications using the WSS APIs at the message level