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.
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.
Table 1. Encryption usage
types. The encryption usage types describe encryptions
methods.
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. These
pre-configuring encryption algorithms are supported by WebSphere Application
Server.
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. These
pre-configured encryption algorithms are supported by WebSphere Application
Server.
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 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).
|
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.