The Web Services
Security application programming interfaces
(WSS API) provide support for securing SOAP message.
Before you begin
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 WebSphere® Application Server 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: You must use the
IBM implementation of the WS-Security standards in the context of
web services.
About this task
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 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 Services 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, you must 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 that is configured by using the administrative console,
or by using the WSS API for configuration.
Using the WSS API,
complete the following high-level steps to secure the SOAP message:
- 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.
- Use the WSSSignPart
API if you want 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 if you want to generate the
signature for the SOAP message using the SHA256 digest method instead
of the default value of SHA1.
-
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.
-
Use
the WSSEncryptPart API if you want to add or change the encrypted
parts to be used for message confidentiality. For
example, if you want to change the data encryption method from the
default value of AES128 to TRIPLE_DES.
No algorithm methods are
required for encrypted parts.
-
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).
-
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.
-
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.
-
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.
-
Use
the WSSDecryptPart API if you want to add or change the decrypted
parts to be used for message confidentiality. For
example, if you want to change the data encryption method from the
default value of AES128 to TRIPLE_DES.
No algorithm methods are
required for decrypted parts.
-
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 that is used
for decryption. The default token is X509Token.
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.