To configure the client for response decryption for the
consumer binding, specify which data and transform algorithm methods
to use when the client decrypts the SOAP messages.
Before you begin
Prior to completing these steps, read the XML encryption
information to become familiar with encrypting and decrypting SOAP
messages.
To complete decryption configuration to secure SOAP
messages, you must complete the following tasks:
- Configure decryption of the SOAP message parts
- Specify the decryption methods.
You can configure the decryption methods using the WSSDecryption
and WSSDecryptPart APIs. Or you can also configure policy sets using
the administrative console to configure the decryption methods.
About this task
Some of the encryption-related definitions are based on
the XML-Encryption specification. The following information defines
some data encryption-related terms:
- Data encryption method algorithm
- Data encryption algorithms specify the algorithm uniform resource
identifier (URI) of the data encryption method. This algorithm encrypts
and decrypts data in fixed size, multiple octet blocks.
By default,
the Java Cryptography Extension (JCE) is shipped
with restricted or limited strength ciphers. To use 192-bit and 256-bit
Advanced Encryption Standard (AES) encryption algorithms, you must
apply unlimited jurisdiction policy files.
For the AES256-cbc
and the AES192-cbc algorithms, you must download the unrestricted
Java™ Cryptography Extension (JCE) policy files from the following
Web site: http://www.ibm.com/developerworks/java/jdk/security/index.html.
- Key encryption method algorithm
- Key encryption algorithms specify the algorithm uniform resource
identifier (URI) of the key encryption method. The algorithm represents
public key encryption algorithms that are specified for encrypting
and decrypting keys.
By default, the RSA_OAEP algorithm uses the
SHA1 message digest algorithm to compute a message digest as part
of the encryption operation. Optionally, you can use the SHA256 or
SHA512 message digest algorithm by specifying a key encryption algorithm
property. The property name is: com.ibm.wsspi.wssecurity.enc.rsaoaep.DigestMethod.
The property value is one of the following URIs of the digest method:
- http://www.w3.org/2001/04/xmlenc#sha256
- http://www.w3.org/2001/04/xmlenc#sha512
By default, the RSA_OAEP algorithm uses a null string
for the optional encoding octet string for the OAEPParams. You can
provide an explicit encoding octet string by specifying a key encryption
algorithm property. For the property name, you can specify com.ibm.wsspi.wssecurity.enc.rsaoaep.OAEPparams.
The property value is the base 64-encoded value of the octet string.
Important: You can set these digest method and OAEPParams properties
on the generator side only. On the consumer side, these properties
are read from the incoming SOAP message.
For the KW_AES256
and the KW_AES192 key encryption algorithms, you must download the
unrestricted JCE policy files from the following Web site: http://www.ibm.com/developerworks/java/jdk/security/index.html.
Important: Your country of origin
might have restrictions on the import, possession, use, or re-export
to another country, of encryption software. Before downloading or
using the unrestricted policy files, you must check the laws of your
country, its regulations, and its policies concerning the import,
possession, use, and re-export of encryption software, to determine
if it is permitted.
To complete the decryption configuration, you must
specify the algorithm uniform resource identifier (URI) and its usage
type. If the URI is used for multiple usage types, then you must define
the URI to each usage type. WebSphere® Application Server
supports the following decryption usage types:
Table 1. Decryption usage types. These decryption
types are supported by WebSphere Application Server.
Usage types |
Description |
Data encryption |
Specifies the algorithm URI that is used for
both encrypting and decrypting data. Encrypts and decrypts data in
fixed size, multiple octet blocks. |
Key encryption |
Specifies the algorithm URI that is used for
encrypting and decrypting the encryption key. |
To configure the decryption and decrypted part algorithms,
use the WSSDecryption and WSSDecryptPart APIs, or configure policy
sets using the administrative console.
Note: Policy sets do not
support symmetric key encryption. If you are using the WSS API for
symmetric key encryption, you will not be able to interoperate with
Web services endpoints that use policy sets.
If you are using
the WSS APIs, the WSSDecryption and WSSDecryptPart APIs specify which
algorithm methods are used when the client decrypts the SOAP messages.
- Use the WSSDecryption API to configure the data encryption algorithm
and the key encryption algorithm methods.
- Use the WSSDecryptPart API to configure a transform algorithm
method.
The WSS API process completes the following high-level
steps to specify which decryption and decrypted part algorithm methods
to use when configuring the client for response decryption:
Procedure
- Using the WSSDecryption API, adds the required data encryption
algorithm. The data encryption algorithm is used for encrypting
or decrypting parts of a SOAP message. Data decryption algorithms
specify the algorithm uniform resource identifier (URI) of the data
encryption method.
The default data encryption algorithm is AES
128. The data encryption name is AES128, and the URI of the data encryption
algorithm, is http://www.w3.org/2001/04/xmlenc#aes128-cbc. WebSphere Application Server supports the
following pre-configured data decryption algorithms:
- AES128: http://www.w3.org/2001/04/xmlenc#aes128-cbc
The AES
128 algorithm is the default data algorithm method.
- AES256: http://www.w3.org/2001/04/xmlenc#aes256-cbc
To use
this AES 256-cbc algorithm, you must download the unrestricted Java Cryptography Extension (JCE) policy file
from the following Web site: http://www.ibm.com/developerworks/java/jdk/security/index.html.
- AES192: http://www.w3.org/2001/04/xmlenc#aes192-cbc
Do not
use the 192-bit key encryption algorithm if you want your configured
application to be in compliance with the Basic Security Profile (BSP).
To
use this AES 192-cbc algorithm, you must download the unrestricted Java Cryptography Extension (JCE) policy file
from the following Web site: http://www.ibm.com/developerworks/java/jdk/security/index.html.
- TRIPLE_DES: http://www.w3.org/2001/04/xmlenc#tripledes-cbc
- As needed, changes the WSSEncryption API method to specify
another data encryption algorithm. For example, you might
add the following code to change from the default AES 128 algorithm
to the Triple DES algorithm:
dec.addAllowedKeyEncryptionMethod(WSSDecryption.TRIPLE_DES);
- Using the WSSDecryption API, adds the required key encryption
algorithm. The key encryption algorithm is used for encrypting
the key that is used for encrypting the message parts within the SOAP
message. If no key for encrypting the data is needed, then you must
specify WSSDecryption.encryptKey(false).
The key encryption algorithm
that you select for the consumer side must match the key encryption
method that you select for the generator side.
The default key
encryption algorithm value is key wrap RSA_OAEP. The key encryption
name is KW_RSA_OAEP, and the URI of the key encryption algorithm is
http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p. WebSphere Application
Server supports the following pre-configured key encryption algorithms:
- KW_AES128: http://www.w3.org/2001/04/xmlenc#kw-aes128
- KW_AES192: http://www.w3.org/2001/04/xmlenc#kw-aes192
To use
this key wrap AES 192 algorithm, you must download the unrestricted Java Cryptography Extension (JCE) policy file
from the following Web site: http://www.ibm.com/developerworks/java/jdk/security/index.html.
Restriction: Do not use the 192-bit key encryption algorithm
if you want your configured application to be in compliance with the
Basic Security Profile (BSP).
- KW_AES256: http://www.w3.org/2001/04/xmlenc#kw-aes256
To use
this key wrap AES 256-cbc algorithm, you must download the unrestricted Java Cryptography Extension (JCE) policy file
from the following Web site: http://www.ibm.com/developerworks/java/jdk/security/index.html.
- KW_RSA_OAEP: http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p.
The
KW_RSA_OAEP algorithm is the default key algorithm method.
When
running with Software Development Kit (SDK) Version 1.4, the list
of supported key transport algorithms does not include this algorithm.
This algorithm appears in the list of supported key transport algorithms
when running with SDK Version 1.5. See more information at http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
- KW_RSA_15: http://www.w3.org/2001/04/xmlenc#rsa-1_5
- KW_TRIPLE_DES: http://www.w3.org/2001/04/xmlenc#kw-tripledes
Note: For Web Services Secure Conversation, the WSSEncryption
API might specify addition key-related information, such as the:
- As needed, uses the WSSDecryption API method to change
to other key encryption algorithms. For example, you might
add the following code to change from the default key encryption algorithm
KW_RSA_OAEP to the TRIPLE_DES algorithm:
dec.addAllowedKeyEncryptionMethod(WSSDecryption.KW_TRIPLE_DES);
- Using the WSSDecryptPart API, adds a transform algorithm,
as needed. There is no default transform algorithm. However, WebSphere Application Server provides a
pre-configured decrypted part, WSSDecryptPart.TRANSFORM_ATTACHMENT_CIPHERTEXT,
that can be added.
Results
If there is an error condition, a WSSException is provided.
If successful, the API calls the WSSConsumerContext.process(), the
WS-Security header is validated, and the SOAP message is now secured
using Web services security.
Example
The following example provides sample WSS API code for
decrypting the body content as well as changing the data encryption
and key encryption algorithms from the default values:
// Get the message context
Object msgcontext = getMessageContext();
// Generate the WSSFactory instance
WSSFactory factory = WSSFactory.getInstance();
// Generate the WSSConsumingContext instance
WSSConsumingContext gencont = factory.newWSSConsumingContext();
// Generate the callback handler
X509ConsumeCallbackHandler callbackHandler = new
X509ConsumeCallbackHandler(
"",
"enc-sender.jceks",
"jceks",
"storepass".toCharArray(),
"alice",
"keypass".toCharArray(),
"CN=Alice, O=IBM, C=US");
// Generate WSSDecryption instance
WSSDecryption dec = factory.newWSSDecryption(X509Token.class,
callbackHandler);
// Set the candidates for the data encryption method
// DEFAULT : WSSDecryption.AES128
dec.addAllowedEncryptionMethod(WSSDecryption.AES128);
dec.addAllowedEncryptionMethod(WSSDecryption.AES192);
// Set the candidates for the key encryption method
// DEFAULT : WSSDecryption.KW_RSA_OAEP
dec.addAllowedKeyEncryptionMethod(WSSDecryption.KW_TRIPLE_DES);
// Add the WSSDecryption to WSSConsumingContext
concont.add(dec);
// Validate the WS-Security header
concont.process(msgcontext);