Getting Started with Message-Level Encryption on WebLogic Server 9.2

Setup

As shown in Figure 1, SOAPSonar and WebLogic Server are installed on different machines. This configuration is recommended but not necessary – both products may be installed on a single resourceful machine.

Figure1. The setup for getting started with WebLogic Server message-level encryption

In the following steps, we will set up a simple Web service getCreditScore(int ssn) that we load from samples provided with the base WebLogic Server install. The Java class called CreditScoreSerivce.java in package services contains a single operation (WebMethod) as follows:

Copy



package services;
import javax.jws.*;
@WebService
public class CreditScoreService {
 static final long serialVersionUID = 1L;
 /**
 * Returns the credit score for a given SSN. 
 * Returns -1 if an invalid SSN is entered.
 */
 @WebMethod
 public int getCreditScore(int ssn) {
    if (ssn > 0 && ssn < 300000000)
        return 500;
    if (ssn >= 300000000 && ssn < 600000000)
        return 600;
    else if (ssn >= 600000000 && ssn <= 999999999)
        return 700;
    else
 return -1;
 }
}

After loading CreditScoreService.java in the WebLogic Server Workshop, we will publish a WSDL for this class. At design time, this WSDL then can be readily consumed by Java or .NET clients to enable SOAP messaging between the clients and the WebLogic Server. We will then enable a message-level security policy that encrypts the SOAP response from the operation getCreditScore(int ssn). To achieve this, we will also load a Java Key Store with the trusted X.509 certificates and inject X.509 certificates in the SOAP request headers.

Step 1: Enabling a sample Web service through Workshop

Install WebLogic Server. Workshop will also be installed. Start the server with default settings.
File > Import > Existing Projects into Workspace > Select archive file > Browse to the ZIP file BEA_HOME/workshop92/workshop4WP/samples/workspaces/AdvancedWSTutorial/AdvancedWSTutorial.zip and Click Open > Click Finish.
Double-click on CreditScoreWS>src>services.>CreditScoreService.java. The Java file contains a Web service with a single operation getCreditScore(int ssn). The operation code should appear as shown in Figure 2.
Figure2. Loading the sample Web service in Workshop for WebLogic Platform
In the Package Explorer, right-click on the CreditScoreService.java and select Run As>Run on Server. Select the default runtime server BEA WebLogic v9.2 Server.
A window with a test client will open, as shown in Figure 3. You are now ready to send a SOAP request by entering ssn input values for operation getCreditScore.
Figure3. The built-in Web services test client provided with Workshop for WebLogic
As an optional item, you can invoke the getCreditScore operation from a browser through the following URL: http://wlshost:7001/CreditScoreWS/CreditScoreService where wlshost is the hostname (or IP address) of your WebLogic Server.

Voila! At the end of Step 1, you are now able to easily publish a Web service and invoke it from within the built-in test client in Workshop or by using a Web browser.

Step 2: Install and configure SOAPSonar

Workshop for WebLogic Platform, shown in Figure 3 above, includes a convenient embedded SOAP client for sending SOAP requests and reviewing SOAP responses from WebLogic Server. However, it does not provide the ability to load an X.509 certificate in the SOAP header. To enable X.509 certificate stuffing in SOAP request headers, we use a simple .NET client SOAPSonar Enterprise Edition from Crosscheck Networks. A trial of SOAPSonar Enterprise Edition can be downloaded from Crosscheck Networks.

After downloading and installing SOAPSonar, launch the product and load the Web Services Endpoint http://wlshost:7001/CreditScoreWS/CreditScoreService?WSDL, where wlshost is the hostname (or IP address) of your WebLogic Server. SOAPSonar parses the WebLogic WSDL and presents the operations in the left navigation panel. The user can populate the operation Request field, press the submit arrow, and review the SOAP response in the Response Panel.

Figure4. Loading WebLogic Server WSDL in SOAPSonar™ Diagnostic Tool

In subsequent steps, SOAPSonar will be used to inject X.509 certificates in SOAP request headers for WebLogic Server to encrypt SOAP responses using the injected X.509 certificates.

Step 3: Download and install Java Key Store

Download keys.zip. It contains:

A Java Key Store (JKS) DemoTrust.jks. This Java Key Store serves as the "trusted repository" for X.509 certificates such that when an external SOAP client presents these X.509 certificates to the WebLogic Server, they are accepted and trusted by the WebLogic Server for cryptographic operations. If the X.509 client is not present in the DemoTrust.jks, an exception occurs indicating that the X.509 presented by the client is not trusted.
Two X.509v3 public certificates: cert1024.cer and cert2048.cer. The X.509 certificates are used to encrypt SOAP messages and will be loaded in SOAPSonar in Step 4.
Two key pairs: keypair1024.pfx and keypair2048.pfx. These key pairs include the private keys and are not required for setting up SOAP encryption. They are added to the keys.zip file for reference.

Note: JKS DemoTrust.jks password is: DemoTrustKeyStorePassPhrase. All key pairs provided in keys.zip have the same password: password. You will not need to use the key pair password since this password is required for accessing the private key in this article. We focus on encryption that requires a public key embedded in the X.509 certificate.

To load DemoTrust.jks:

Backup the original DemoTrust.jks located in BEA_HOME/weblogic92/server/lib/ and replace it with the DemoTrust.jks that is provided in the keys.zip.
Restart WebLogic Sever from the Workshop for WebLogic Platform.

Caution: If any changes are made to the JKS, WebLogic Sever should be restarted.

Step 4: Configuring SOAP encryption in WebLogic Server

WebLogic Server provides granular message-level encryption. Any part of the SOAP body can be encrypted. As shown in Figure 1, a SOAP Request with an X.509 certificate embedded in the SOAP header is sent to the WebLogic Server. The SOAP Response Body is returned encrypted.

To enable SOAP response encryption as shown in Figure 1, the Administrator simply enables a WS-Policy-based configuration that tells WebLogic Server to encrypt the SOAP response for the selected Web service. This configuration is accomplished with the following simple steps:

Start Admin Console: Log into the WebLogic Administration Console http://localhost:7001/console. The default id and passwords are both set to: weblogic.
Navigate to WS-Policy: On the Home Page, Lock & Edit. Then under Domain Structure in the Left Navigation panel, navigate to Deployments > CreditScoreEAR > CreditScoreServiceService > Configuration > WS-Policy.
Configure WS-Policy: Expand CreditScoreServiceSoapPort and click on getCreditScore. Click Next to move to the Outbound SOAP Message, then select the Encrypt.xml policy and move it to the chosen policy panel on the right as shown in Figure 5. Click Finish. Select and Save the Deployment Plan Meta-INF and Activate.
Figure5. Configure encryption policy for an outbound message
Update: From the Home Page, Lock & Edit. Then under Domain Structure in the Left Navigation panel, navigate to Deployments. Select CreditScoreEAR and click Update. Activate the changes.

At the end of Step 4, your WebLogic Server is ready to encrypt SOAP responses for the getCreditScore operation. Try sending a SOAP request using Workshop as shown in Figure 3. WebLogic Server will complain. It now expects the SOAP request to contain a trusted X.509 certificate that it requires to encrypt the SOAP response.

In addition to the Encrypt.xml policy, WebLogic Server also includes pre-packaged policies such as Auth.xml for specifying client authentication policies, Sign.xml for setting SOAP message signature policies, and DefaultReliability.xml for configuring reliable message properties such retransmission intervals.

Step 5: Configuring SOAPSonar

This step enables SOAPSonar to send SOAP requests with X509 tokens in the SOAP header. The tasks are described below:

Load X.509 into SOAPSonar: Move keys.zip file to the client machine running SOAPSonar. Extract X509 certificates to a folder. Click on Tools > PKI Management. Right-click on MY and select Load Certificate. Load certificates cert1024.cer and cert2048.cer.
Inject X.509 in SOAP header: In the SOAPSonar Request Panel, select the Tasks Tab. Select the WS-Tokens drop-down and Add WSS X509 Tokens. Click on the WSS X509 Token Task. A panel shown in Figure 6 appears that lets users select an X.509 certificate. Select the cert1024 certificate loaded in the previous step.

Figure6. Configure X.509 injected in the SOAP request header from SOAPSonar

Functional Tests

To ensure that we have properly configured WebLogic Server for SOAP encryption, we now run a few of simple functional tests. In the first test, we use SOAPSonar to submit a SOAP request without an X.509 certificate embedded in it. You can do this by turning off the WS X509 Token Task in SOAPSonar. As expected, we get a SOAP Fault that indicates that the endpoint, WebLogic Server, requires an X.509 token:

Copy



<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
 <soapenv:Header />
 <soapenv:Body>
     <soapenv:Fault>
     <faultcode>soapenv:Server</faultcode>
     <faultstring>Failed to get token for tokenType: 
     http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3</faultstring>
     </soapenv:Fault>
 </soapenv:Body>
</soapenv:Envelope>

In the second functional test, we turn the WS X509 Token Task in SOAPSonar back on and send a SOAP request with an X.509 certificate cert1024 that is registered with DemoTrust.jks. Figure 7 shows the request message with the SOAP Body and the X.509 embedded in the SOAP Header.

Figure 7. SOAP request with X.509 embedded in header

When SOAPSonar makes the SOAP request with the embedded X.509, WebLogic Server parses the SOAP request, extracts the X.509 token from the SOAP header, and checks with the trust key store, DemoTrust.jks, whether the presented X.509 is registered as a trusted X.509 certificate. Since the X.509 certificate cert1024 is registered as a trusted certificate, WebLogic Server proceeds to apply the SOAP Body encryption policy configured in Step 4. The result of the encryption policy is shown in Figure 8.

Figure 8. Message response with encrypted SOAP body content

The SOAP response in Figure 8 shows the SOAP body is encrypted with the content placed in the EncryptedData element. The X.509 token data shows that cert1024 certificate is used for the encryption. The content in the SOAP body response is now confidential and can be decrypted only to the original data format by anyone with a private key. Within a SOA, SOAP decryption may occur at a consumer, producer, or intermediary gateway such as AquaLogic Service Bus.

For the third and final functional test, select the cert2048 in SOAPSonar, as show in Figure 6, to inject it into the SOAP request header. On submitting the request with cert2048 embedded in it, you get:

Copy



<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
 <soapenv:Header />
 <soapenv:Body>
 <soapenv:Fault xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
 <faultcode>wsse:InvalidSecurityToken</faultcode>
 <faultstring>Security token failed to validate. 
 weblogic.xml.crypto.wss.SecurityTokenValidateResult@314c3b[status: false][msg [
 [
 Version: V1
 Subject: CN=cert2048, OU=development, O="software, inc.", L=waltham, ST=ma, C=us
 Signature Algorithm: SHA1withRSA, OID = 1.2.840.113549.1.1.5

The response is a SOAP fault indicating the security token presented was invalid. This occurs since cert2048 was not registered with DemoTrust.jks as a trusted certificate. To add certificates to a Java Key Store, download keytool, a command-line utility by Sun Microsystems. Remember to restart WebLogic Server for changes to the Java Key Store to take effect.

Performance Characteristics

The WebLogic Server platform provides message-level encryption and signatures by using public and private keys. Users have an option of picking key pairs depending on corporate security policies. Small key sizes are efficient but are less secure. Larger key sizes are more secure but end up chewing considerable computational resources. Figure 9 shows a normalized graph of SOAP encryption for different key sizes plotted on the x-axis. All observations are normalized to the 512-bit key size since 512 bit key is the smallest key size tested and therefore has the highest performance (and lowest security). Starting from 512 at 100%, increasing the key size for encrypting the SOAP message, one should expect performance degradation owing to higher overhead of cryptographic operations.

Encryption Performance based on Key Size

Figure 9. Relative key size profile for message-level encryption in WebLogic Server

Key size recommendations

Large key size operations, especially private key operation required for signatures (and decryption) are computationally expensive. Public key operations required for encryption and signature verification are not as computationally intensive as their private key counterparts. Key sizes beyond 2048 bits are rarely used in practice and unless there is a strong reason to do so, one should stick to either 1024- or 2048-bit keys for Signatures and Encryption. BEA recommends 1024 or higher key sizes.

Consider using a crypto accelerator such as nCipher Hardware when larger than 1024-bit key sizes are necessary. Instructions for configuring the nCipher JCE provider are available in Securing WebLogic Server.

Interoperability Assessment

SOAPSonar is a .NET-based client that interacts seamlessly with the Java-based WebLogic Server. The seamless interoperability is evident across multiple aspects of this Web services interaction:

The WSDL generated by WebLogic Server is readily consumed and parsed by .NET-based clients, such as SOAPSonar.
The WSDL generated by WebLogic Server passes all WS-I Basic Profile Interoperability tests conducted by SOAPSonar.
The WS-Security 1.0 X.509 Token Profile was used to generate the SOAP request with the embedded X.509 certificate in the SOAP header using SOAPSonar. This request was then seamlessly digested by WebLogic Server.

Summary

This article shows you how to set up message-level encryption for WebLogic Server, and how WebLogic Server provides the necessary granularity to encrypt SOAP messages. Understanding key management and fundamentals of PKI is essential for setting up message-level encryption policies. Equally essential is making trust management an integral part of corporate security policies. Knowing which X.509 keys are valid and trusted is essential for establishing trust, and systems like transport-level security and message-level security are only as good as the handling and management of corporate cryptographic keys.

The .NET and Java platforms interoperate surprisingly well. SOAP messages assembled by a .NET-based client, SOAPSonar, are readily digested by the Java-based WebLogic Server 9.2. More impressive is the ability for WebLogic Server to consume SOAP messages with X.509 embedded in SOAP requests generated from a .NET-based client.

The power of interoperable and granular message-level encryption is now available to ensure that data privacy is enforced beyond transport protocols. Within a SOA, privacy-related policies can now be tested and enforced at the message level, ensuring that, regardless of the transport security, information is protected from intentional or inadvertent leaks.

References

Understanding PKI - Concepts, Standards and Deployment Considerations, 2nd Edition by Carlisle Adam and Steve Lloyd
WS-I Basic Profile 1.1 - profile to enable conforming platforms to interoperate
WS-Security 1.0 - Web services security specification of security token exchange, encryption-decryption, and signature-verification

Mamoon Yunus is CTO of Forum Systems and a pioneer of SOA Gateways and Firewalls. Prior to Forum, Mamoon was at webMethods where he developed XML-based technology.

Rick White is the co-founder of Fusion Multisystems and also the co-founder of Forum Systems. Previously, Rick was the co-founder of Phobos Corporation, a traffic management solutions company that was acquired by Sonicwall.