Encryption methods

For request generator binding settings, the encryption methods include specifying the data and key encryption algorithms to use to encrypt the SOAP message. The WSS API for encryption (WSSEncryption) specifies the algorithm name and the matching algorithm uniform resource identifier (URI) for the data and key encryption methods. If the data and key encryption algorithms are specified, only elements that are encrypted with those algorithms are accepted.

Data encryption algorithms

The data encryption algorithm is used to encrypt parts of the SOAP message, including the body and the signature. Data encryption algorithms specify the algorithm uniform resource identifier (URI) for each type of data encryption algorithms.

The following pre-configured data encryption algorithms are supported:

Data encryption algorithm 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, TRIPLE DES: http://www.w3.org/2001/04/xmlenc#tripledes-cbc

By default, the Java Cryptography Extension (JCE) is shipped with restricted or limited strength ciphers. To use 192-bit and 256-bit AES encryption algorithms, we must apply unlimited jurisdiction policy files.

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, we must check the laws of our country, its regulations, and its policies concerning the import, possession, use, and re-export of encryption software, to determine if it is permitted.

For the AES256-cbc and the AES192-CBC algorithms, we must download the unrestricted Java Cryptography Extension (JCE) policy files from the following website: http://www.ibm.com/developerworks/java/jdk/security/index.html.

The data encryption algorithm configured for encryption for the generator side must match the data encryption algorithm configured for decryption for the consumer side.

Key encryption algorithms

This algorithm is used to encrypt and decrypt keys. This key information is used to specify the configuration needed to generate the key for digital signature and encryption. The signing information and encryption information configurations can share the key information. The key information on the consumer side is used for specifying the information about the key used for validating the digital signature in the received message or for decrypting the encrypted parts of the message. The request generator is configured for the client.

Policy sets do not support symmetric key encryption. If we are using the WSS API for symmetric key encryption, we will not be able to interoperate with web services endpoints using the policy sets.

Key encryption algorithms specify the algorithm uniform resource identifier (URI) of the key encryption method. The following pre-configured key encryption algorithms are supported:

WSS API	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 we 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	A URI of key encryption algorithm, key wrap TRIPLE DES: http://www.w3.org/2001/04/xmlenc#kw-tripledes

For Secure Conversation, additional key-related information must be specified, such as:

• algorithmName
• keyLength

By default, the RSA-OAEP algorithm uses the SHA1 message digest algorithm to compute a message digest as part of the encryption operation. Optionally, we 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, we can specify com.ibm.wsspi.wssecurity.enc.rsaoaep.OAEPparams. The property value is the base 64-encoded value of the octet string.

Important: 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, we must download the unrestricted JCE policy files from the following website: http://www.ibm.com/developerworks/java/jdk/security/index.html.

The key encryption algorithm for the generator must match the key decryption algorithm configured for the consumer.

This example provides sample code for encryption to use the Triple DES for the data encryption method and to use RSA1.5 for the key encryption method:

	  // Get the message context
	  Object msgcontext = getMessageContext();

	  // generate WSSFactory instance
	  WSSFactory factory = WSSFactory.getInstance();		

	  // generate 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 to the encryption
	  SecurityToken token = factory.newSecurityToken(X509Token.class, 
        callbackHandler);

	  // generate WSSEncryption instance to encrypt the SOAP body content
	  WSSEncryption enc = factory.newWSSEncryption(token);
	  enc.addEncryptPart(WSSEncryption.BODY_CONTENT);

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

Choosing encryption methods for generator bindings

Encrypting the SOAP message using the WSSEncryption API