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
Encrypting the SOAP message using the WSSEncryption API
We can secure the SOAP messages, without using policy sets for configuration, by 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.
We can 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. WAS 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 you 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) | Whether to encrypt the key. The values are true or false. The default value 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. WAS 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. WAS supports the following token reference types:
|
| Whether to use MTOM (mtomOptimize) | Sets Message Transmission Optimization Mechanism (MTOM) optimization for the encrypted part. |
Procedure
- 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.
- Uses WSSFactory.getInstance() to get the WSS API implementation instance
Results
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 that are 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. You 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.
Encrypted SOAP headers
Choosing encryption methods for generator bindings
Secure message parts
Decrypting SOAP messages using the WSSDecryption API
Configure encryption to protect message confidentiality using the WSS APIs
Configure signing information using the WSSSignature API
Related
Encryption methods