Encrypting the SOAP message using the WSSEncryption API
We can secure the SOAP messages, without using policy sets for configuration, using the Web Services Security APIs (WSS API). To configure the client for request encryption on the generator side, use the WSSEncryption API to encrypt the SOAP message. The WSSEncryption API specifies which request SOAP message parts to encrypt when configuring the client.
Use the WSS API or use policy sets on the administrative console to enable encryption and add generator security tokens in the SOAP message. To secure SOAP messages, use the WSS APIs to complete the following encryption tasks, as needed:
- Configure encryption and choose the encryption methods using the WSSEncryption API.
- Configure the encrypted parts, as needed, using the WSSEncryptPart API.
The encryption information on the generator side is used for encrypting an outgoing SOAP message for the request generator (client side) bindings. The client generator configuration must match the configuration for the provider consumer.
Confidentiality settings require that confidentiality constraints be applied to generated messages. These constraints include specifying which message parts within the generated message must be encrypted, and which message parts to attach encrypted Nonce and timestamp elements to.
The following encryption parts can be configured:
| Encryption parts | Description |
|---|---|
| part | Add the WSSEncryptPart object as a target of the encryption part. |
| keyword | Add the encryption parts using keywords. WebSphere Application Server supports the
following keywords:
|
| xpath | Add the encryption part using an XPath expression. |
| signature | Add the WSSignature component as a target of the encrypted part. |
| header | Add the SOAP header, specified by QName, as a target of the encrypted part. |
| securityToken | Add the SecurityToken object as a target of the encrypted part. |
For encryption, certain default behaviors occur. The simplest way to use the WSSEncryption API is to use the default behavior (see the example code).
WSSEncryption provides defaults for the key encryption algorithm, the data encryption algorithm, the security token reference method, and the encryption parts such as the SOAP body content and the signature. The encryption default behaviors include:
| Encryption decisions | Default behavior |
|---|---|
| Which SOAP message parts to encrypt using keywords |
Sets the encryption parts that we can add using keywords. The default encryption parts are the BODY_CONTENT and SIGNATURE. WAS supports using these keywords:
|
| Which data encryption method to choose (algorithm) |
Sets the data encryption method. Both data and key encryption methods can be specified. The default data encryption algorithm method is AES 128. WAS supports these data encryption methods:
|
| Whether to encrypt the key (isEncrypt) |
Specifies whether to encrypt the key. The values are true or false. The default is to encrypt the key (true). |
| Which key encryption method to choose (algorithm) |
Sets the key encryption method. Both data and key encryption methods can be specified. The default key encryption algorithm method is key wrap RSA OAEP. WebSphere Application Server supports these key encryption methods:
|
| Which security token to specify (securityToken) |
Sets the SecurityToken. The default security token type is the X509Token. WAS provides the following pre-configured consumer token types:
|
| Which token reference to use (refType) | Sets the type of the security token reference.
The default token reference is SecurityToken.REF_KEYID. WebSphere Application
Server supports the following token reference types:
|
| Whether to use MTOM (mtomOptimize) | Sets Message Transmission Optimization Mechanism (MTOM) optimization for the encrypted part. |
Tasks
- To encrypt the SOAP message using the WSSEncryption API, first ensure that the application server is installed.
- The WSS API process for encryption performs these process
steps:
- Uses WSSFactory.getInstance() to get the WSS API implementation instance
- Creates the WSSGenerationContext instance from the WSSFactory instance.
- Creates the SecurityToken from WSSFactory used for encryption.
- Creates WSSEncryption from the WSSFactory instance using the SecurityToken. The default behavior of WSSEncryption is to encrypt the body content and the signature.
- Adds a new part to be encrypted in WSSEncryption if the existing part is not appropriate. After addEncryptPart(), addEncryptHeader(), or addEncryptPartByXPath() is called, the default part is cleared.
- Calls the encryptKey(false) if the key is not to be encrypted.
- Sets the data encryption method if the default method is not appropriate.
- Sets the key encryption method if the default method is not appropriate.
- Sets the token reference if the default token reference is not appropriate.
- Adds WSSEncryption to WSSConsumingContext.
- Calls WSSGenerationContext.process() with the SOAPMessageContext.
If there is an error condition during encryption, 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 code using methods defined in WSSEncryption:
// Get the message context
Object msgcontext = getMessageContext();
// Generate the WSSFactory instance (step: a)
WSSFactory factory = WSSFactory.getInstance();
// Generate the WSSGenerationContext instance (step: b)
WSSGenerationContext gencont = factory.newWSSGenerationContext();
// Generate the 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 (step: c)
SecurityToken token = factory.newSecurityToken(X509Token.class, callbackHandler);
// Generate WSSEncryption instance (step: d)
WSSEncryption enc = factory.newWSSEncryption(token);
// Set the part to be encrypted (step: e)
// DEFAULT: WSSEncryption.BODY_CONTENT and WSSEncryption.SIGNATURE
// Set the part specified by the keyword (step: e)
enc.addEncryptPart(WSSEncryption.BODY_CONTENT);
// Set the part in the SOAP Header specified by QName (step: e)
enc.addEncryptHeader(new QName("http://www.w3.org/2005/08/addressing",
"MessageID"));
// Set the part specified by WSSSignature (step: e)
SecurityToken sigToken = getSecurityToken();
WSSSignature sig = factory.newWSSSignature(sigToken);
enc.addEncryptPart(sig);
// Set the part specified by SecurityToken (step: e)
UNTGenerateCallbackHandler untCallbackHandler =
new UNTGenerateCallbackHandler("Chris", "sirhC");
SecurityToken unt = factory.newSecurityToken(UsernameToken.class,
untCallbackHandler);
enc.addEncryptPart(unt, false);
// sSt the part specified by XPath expression (step: e)
StringBuffer sb = new StringBuffer();
sb.append("/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/'
and local-name()='Envelope']");
sb.append("/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/'
and local-name()='Body']");
sb.append("/*[namespace-uri()='http://xmlsoap.org/Ping'
and local-name()='Ping']");
sb.append("/*[namespace-uri()='http://xmlsoap.org/Ping'
and local-name()='Text']");
enc.addEncryptPartByXPath(sb.toString());
// Set whether the key is encrypted (step: f)
// DEFAULT: true
enc.encryptKey(true);
// Set the data encryption method (step: g)
// DEFAULT: WSSEncryption.AES128
enc.setEncryptionMethod(WSSEncryption.TRIPLE_DES);
// Set the key encryption method (step: h)
// DEFAULT: WSSEncryption.KW_RSA_OAEP
enc.setEncryptionMethod(WSSEncryption.KW_RSA15);
// Set the token reference (step: i)
// DEFAULT: SecurityToken.REF_KEYID
enc.setTokenReference(SecurityToken.REF_STR);
// Add the WSSEncryption to the WSSGenerationContext (step: j)
gencont.add(enc);
// Process the WS-Security header (step: k)
gencont.process(msgcontext);
The X509GenerationCallbackHandler does not need the key password because the public key is used for encryption. We do not need a password to obtain the public key from the Java keystore.
What to do next
If we have not previously specified which encryption methods to choose, use the WSS API or configure the policy sets using the administrative console to choose the data and key encryption algorithm methods.
Related: