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.
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
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.
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);