Choosing encryption methods for generator bindings

Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop web services - Security (WS-Security) > Develop applications that use Web Services Security > Develop message-level security for JAX-WS web services > Secure web services applications using the WSS APIs at the message level > Secure messages at the request generator using WSS APIs > Secure messages at the request generator using WSS APIs > Configure encryption to protect message confidentiality using the WSS APIs

Choosing encryption methods for generator bindings

To configure the client for request encryption for the generator binding, specify which encryption methods to use when the client encrypts the SOAP messages.
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.

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, apply unlimited jurisdiction policy files.
For the AES256-cbc and the AES192-cbc algorithms, download the unrestricted Java™ Cryptography Extension (JCE) policy files from the following website: 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 used to encrypt data. The algorithm represents public key encryption algorithms 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. We 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.
We 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, download the unrestricted JCE policy files from the following website: http://www.ibm.com/developerworks/java/jdk/security/index.html.
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, 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.

Encryption usage types. The encryption usage types describe encryptions methods.

Usage types Description
Data encryption Algorithm URI used for both encrypting and decrypting data. Encrypts and decrypts data in fixed size, multiple octet blocks.
Key encryption Algorithm URI used for encrypting and decrypting the encryption key.

Data encryption
WAS supports the following pre-configured data encryption algorithms:

Data encryption algorithms. These pre-configuring encryption algorithms are supported by WAS.

Data encryption name Algorithm URI
WSSEncryption.AES128 (the default value) A URI of data encryption algorithm, AES 128:
WSSEncryption.AES192 A URI of data encryption algorithm, AES 192:
WSSEncryption.AES256 A URI of data encryption algorithm, AES 256:
WSSEncryption.TRIPLE_DES A URI of data encryption algorithm, 3DES: http://www.w3.org.2001/04/xmlenc#tripledes-cbc

Key encryption
WAS supports the following pre-configured key encryption algorithms:

Key encryption algorithms. These pre-configured encryption algorithms are supported by WAS.

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 admin console.
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
Use 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. WAS 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, download the unrestricted Java Cryptography Extension (JCE) policy file from the following website: 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, download the unrestricted Java Cryptography Extension (JCE) policy file from the following website: 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);
Use the WSSEncryption API, adds the required key encryption algorithm. The key encryption algorithm is used for encrypting the key used for encrypting the message parts within the SOAP message. If the encryption key, which is the key 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. WAS 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, download the unrestricted Java Cryptography Extension (JCE) policy file from the following website: 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-aes256
To use this key wrap AES 256-cbc algorithm, download the unrestricted Java Cryptography Extension (JCE) policy file from the following website: 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 SDK v1.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 v1.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

For Web Services Secure Conversation, the WSSEncryption API might specify addition key-related information, such as the:

algorithmName
keyLength
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, to add a transform algorithm, review the WSSEncryptPart API process task.
XML encryption
Encrypting the SOAP message using the WSSEncryption API
Configure generator security tokens using the WSS API
Decrypting SOAP messages using the WSSDecryption API
Configure encryption to protect message confidentiality using the WSS APIs
XML Encryption Syntax and Processing W3C Recommendation 10 December 2002

+
Search Tips | Advanced Search

Usage types	Description
Data encryption	Algorithm URI used for both encrypting and decrypting data. Encrypts and decrypts data in fixed size, multiple octet blocks.
Key encryption	Algorithm URI used for encrypting and decrypting the encryption key.

Data encryption name	Algorithm URI
WSSEncryption.AES128 (the default value)	A URI of data encryption algorithm, AES 128:
WSSEncryption.AES192	A URI of data encryption algorithm, AES 192:
WSSEncryption.AES256	A URI of data encryption algorithm, AES 256:
WSSEncryption.TRIPLE_DES	A URI of data encryption algorithm, 3DES: http://www.w3.org.2001/04/xmlenc#tripledes-cbc

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