To configure the client for request encryption for the generator
binding, you must specify which encryption methods to use when the client
encrypts 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
specify which algorithm methods are to be used when the client encrypts the
SOAP messages, complete the following tasks:
- Use the WSSEncryption API to configure the data encryption algorithm and
the key encryption algorithm methods.
- Use the WSSEncryptPart API to configure a transform algorithm method,
if needed. The default is no transform algorithm.
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 method to encrypt the key that is used to encrypt data. 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.
Table 1. Encryption 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. |
Data encryption
WebSphere Application Server supports
the following pre-configured data encryption algorithms:
Table 2. Data
encryption algorithms
Data encryption name |
Algorithm URI |
WSSEncryption.AES128 (the default value) |
A URI of data encryption algorithm, AES 128: http://www.w3.org/2001/04/xmlenc#aes128-cbc |
WSSEncryption.AES192 |
A URI of data encryption algorithm, AES 192: http://www.w3.org/2001/04/xmlenc#aes192-cbc |
WSSEncryption.AES256 |
A URI of data encryption algorithm, AES 256: http://www.w3.org/2001/04/xmlenc#aes256-cbc |
WSSEncryption.TRIPLE_DES |
A URI of data encryption algorithm, 3DES: http://www.w3.org.2001/04/xmlenc#tripledes-cbc |
Key encryption
WebSphere Application Server supports
the following pre-configured key encryption algorithms:
Table 3. Key
encryption algorithms
Key encryption name |
Algorithm URI |
WSSEncryption.KW_AES128 |
A URI of key encryption algorithm, key wrap AES 128:
http://www.w3.org/2001/04/xmlenc#kw-aes128 |
WSSEncryption.KW_AES192 |
A URI of key encryption algorithm, key wrap AES 192:
http://www.w3.org/2001/04/xmlenc#kw-aes192 Note: 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).
|
WSSEncryption.KW_AES256 |
A URI of key encryption algorithm, key wrap AES 256:
http://www.w3.org/2001/04/xmlenc#kw-aes256 |
WSSEncryption.KW_RSA_OAEP (the default value) |
A URI of key encryption algorithm, key wrap RSA OAEP:
http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p |
WSSEncryption.KW_RSA15 |
A URI of key encryption algorithm, key wrap RSA 1.5:
http://www.w3.org/2001/04/xmlenc#rsa-1_5 |
WSSEncryption.KW_TRIPLE_DES |
http://www.w3.org/2001/04/xmlenc#kw-tripledes |
To configure the encryption and encrypted part algorithm methods,
use the WSSEncryption API, 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.
The
WSS API process completes the following high-level steps to specify which
encryption methods to use when configuring the client for request encryption:
Procedure
- Using the WSSEncryption API, adds the required data encryption
algorithm. The data encryption algorithm is used for encrypting
or decrypting parts of a SOAP message. Data encryption algorithms specify
the algorithm uniform resource identifier (URI) of the data encryption method.
The
client generator configuration must match the configuration for the provider
consumer.
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 encryption algorithms:
- AES 128: http://www.w3.org/2001/04/xmlenc#aes128-cbc
The AES 128 algorithm
is the default data algorithm method.
- AES 192: 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.
- AES 256: 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.
- TRIPLEDES: 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:
// Default data encryption algorithm: AES128
WSSEncryption enc = factory.newWSSEncryption(x509t);
enc.setEncryptionMethod(EncryptionMethod.TRIPLEDES_CBC);
gencont.add(enc);
- Using the WSSEncryption 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 the encryption
key, which is the key that is used for encrypting the message parts, is not
encrypted, then the decryption API selects false to match the encryption
key.
The client generator configuration must match the configuration for
the provider consumer.
The default key encryption algorithm value is
key wrap RSA OAP. 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 AES 256: http://www.w3.org/2001/04/xmlenc#kw-aes256To 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 RSA15: 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:
Results
If there is an error condition, a WSSException is provided. If successful,
the API calls the WSSGenerationContext.process(), the WS-Security header is
generated, and the SOAP message is now secured using Web services security.
Example
The following example provides sample WSS API code using WSSEncryption.setEncryptionMethod()
and WSSEncryption.setKeyEncryptionMethod().
// Get the message context
Object msgcontext = getMessageContext();
// Generate the WSSFactory instance
WSSFactory factory = WSSFactory.getInstance();
// Generate the WSSGenerationContext instance
WSSGenerationContext gencont = factory.newWSSGenerationContext();
// Generate callback handler
X509GenerateCallbackHandler callbackHandler = new
X509GenerateCallbackHandler(
"",
"enc-sender.jceks",
"jceks",
"storepass".toCharArray(),
"bob",
null,
"CN=Bob, O=IBM, C=US",
null);
// Generate the security token used for encryption
SecurityToken token = factory.newSecurityToken(X509Token.class , callbackHandler);
// Generate WSSEncryption instance
WSSEncryption enc = factory.newWSSEncryption(token);
// Set the data encryption method
// DEFAULT: WSSEncryption.AES128
enc.setEncryptionMethod(WSSEncryption.TRIPLE_DES);
// Set the key encryption method
// DEFAULT: WSSEncryption.KW_RSA_OAEP
enc.setEncryptionMethod(WSSEncryption.KW_RSA15);
// Add the WSSEncryption to the WSSGenerationContext
gencont.add(enc);
// Generate the WS-Security header
gencont.process(msgcontext);
What to do next
Next, if you want to add a transform algorithm, review the WSSEncryptPart
API process task.