As Published In
Oracle Magazine
March/April 2005

DEVELOPER: Web Services


Guarantee SOAP Message Integrity

By Mike Lehmann

Use digital signatures to check sender identity and ensure that messages remain unaltered.

In my last column, I introduced WS-Security and its implementation in Oracle Application Server 10g Release 10.1.3. The focus was on the basic WS-Security conceptual model, where security—specifically authentication—was carried in the SOAP message rather than in reuse of HTTP protocol authentication.

In this column, the focus changes to digital signatures in WS-Security, which guarantee to the receiver that the sender really did send the message and that the message was not altered en route.

You might think the way to achieve this guarantee is to encrypt the message, but although encryption can guarantee message confidentiality (assurance that no one can read it), it does not guarantee integrity (assurance that it was not changed en route). Further, encryption does not identify the message sender.

Configuring a digital signature on a sender's outbound message involves a simple but powerful technique based on public key cryptography: 

  1. The sender computes a one-way hash value based on the contents of the SOAP message, using one of several well-known hash algorithms. These are called one-way because there is no way to reconstruct the message content from the hash value.

  2. The message uses the hash value along with the sender's cryptographic private key to compute a digital signature.

  3. Upon receiving the message, the receiver uses the sender's public key to compute the validity of the message signature and extracts the hash value. The public key calculation with the digital signature produced by the sender's private key ensures a match with the sender's identity.

  4. Using the same algorithm for determining the hash value against the message content validates that the message was untouched en route to the receiver.

Digital Signatures

The runtime environment for WS-Security in Oracle Application Server—often called a pipeline—involves adding authentication tokens as the message leaves the client, digitally signing the message, and finally encrypting the message. This procedure is followed by a mirror-image set of actions on the server side.

For digital signatures and encryption to work, the client and server must have a store of keys—private keys for digitally signing and encrypting messages and public keys of their respective trusted partners for verifying signatures and decrypting messages. Management of these keys is by a certificate authority, such as that of Oracle Application Server or third-party certificate providers.

The keys must be stored, typically in a certificate store on the client and the server. In J2EE application servers, the storage location is often a standard JDK file called a keystore, and more-sophisticated implementations also support LDAP directory servers such as Oracle Internet Directory as a certificate repository.

Configure the Digital Signature

With this context in mind, rather than starting in Oracle JDeveloper (as I illustrated in previous articles) and configuring a service for digital signatures, I work from the inbound server side back to the outbound client side. Using the same HR Service example as in my previous columns, first I go to the Application Server Control Web services page (found on your local OC4J installation at http://127.0.0.1:1810/console/ias/oc4j/webservices) and navigate to the EmpServicePort administration page. Then I edit the inbound security settings as shown in Figure 1.

 

figure 1
Figure 1: Setting up the digital signature configuration for the EmpService using Application Server Control


The second tab of the security settings enables administrators to configure message integrity, otherwise known as the digital signature configuration. They can simply state that messages must be signed in order to be processed, and they can declare support for several standard algorithms for processing digital signatures, including DSA-SH1, HMAC-SHA1, RSA-MD5, and RSA-SHA1.

To make things simple for certificate management, I use a sample keystore shipped with Oracle Application Server 10g Release 10.1.3, oraks.jks, located in the <ORACLE_HOME>\j2ee\config directory. It comes with a certificate pregenerated for digital signatures—orasign—and a certificate pregenerated for encryption—oraenc. By going to the Keystore and Identity Certificates screen of Application Server Control, you can select the default keystore.

The result of this configuration is shown in Listing 1, in the wsmgmt.xml file, the runtime repository of the security policy configuration. It illustrates the rendering of the timestamp and signature algorithms checked in Figure 1 in XML in the <inbound> subelement of the HR-Emp-WS <port> configuration. The keystore configuration of oraks.jks is set within the <runtime> element at the bottom of the wsmgmt.xml file.

Code Listing 1: XML configuration of the digital signature on the EmpService 

                               
<wsmgmt xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation
="http://xmlns.oracle.com/oracleas/schema/oracle-webservices-management-10_0.xsd">
  <port app="HR-Emp-WS" web="WebServices" service="EmpService" port="EmpServicePort">
    <runtime enabled="security">
      <security>
        <inbound>
          <verify-signature>
            <signature-methods>
              <signature-method>DSA-SHA1</signature-method>
              <signature-method>HMAC-SHA1</signature-method>
              <signature-method>RSA-MD5</signature-method>
              <signature-method>RSA-SHA1</signature-method>
            </signature-methods>
            <tbs-elements>
     <tbs-element name-space="http://schemas.xmlsoap.org/soap/envelope/" localpart="Body"/>
            </tbs-elements>
            <verify-timestamp expiry="60" created="true"/>
          </verify-signature>
        </inbound>
      </security>
    </runtime>
  </port>
  <runtime>
    <security>
      <key-store path="C:\oc4j1013\j2ee\config\oraks.jks" name="oracle-keystore" type="JKS" 
store-pass="->default.keystore.config/oraks.jks"/>
      <signature-key alias="orasign" key-pass="->default.key.orasign"/>
      <encryption-key alias="oraenc" key-pass="->default.key.oraenc"/>
<jaas-loginmodule-config>oracle.security.wss.jaas.JAASAuthManager</jaas-loginmodule-config>
      <nonce-config cache-ttl="300" clock-skew="300"/>
    </security>
  </runtime>
</wsmgmt>

                            

Configure the Client, Send the Message

To configure a client, you must create a symmetric configuration file on the client. Oracle JDeveloper 10g Release 10.1.3 provides the symmetric screens where the client—the sender, in this case—sets up the digital signature generation. Figure 2, shows the declaration of the keystore used on the client (in this case, the same keystore, for simplicity) to generate the digital signature in Oracle JDeveloper.

 

figure 2
Figure 2


Having set up both the client and the server for digital signatures, the message can be sent and inspected on the wire, by using the same Web service client—althought the client-side configuration is different from the server-side configuration. Listing 2, in the online version of this column, shows the client-side configuration of the service, a mirror image of that on the server.

Code Listing 2: Client-side digital signature configuration 

                               
<?xml version = '1.0' encoding = 'UTF-8'?>
<port-info xmlns="http://xmlns.oracle.com/oracleas/schema/oracle-webservices-client-10_0.xsd">
   <runtime xmlns="" enabled="security">
      <security>
         <key-store path="C:j1013ee.jks"
                    store-pass="oracle"/>
         <signature-key alias="orasign" key-pass="orasign"/>
         <inbound/>
         <outbound>
            <signature>
               <signature-method>
                  RSA-SHA1
               </signature-method>
               <tbs-elements>
                  <tbs-element local-part="Body"
                               name-space="http://schemas.xmlsoap.org/soap/envelope/"/>
               </tbs-elements>
               <add-timestamp created="true" expiry="60"/>
            </signature>
         </outbound>
      </security>
   </runtime>
   <operations xmlns="">
      <operation name="getEmpSalary"/>
   </operations>
</port-info>

                            

Listing 3, also in the online version of this column, shows the digital signature attached to the outbound message. Note that digital signatures do not alter the message content itself. At the bottom of the listing, you still see the message data—in this case, employee number 7902—and the message headers contain information about the algorithm used for encryption and the digital signature itself.

Code Listing 3: Outbound message from the client

Next Steps in Security

Next Steps


DOWNLOAD
Oracle Application Server 10g Release 10.1.3 Developer Preview

This article has taken you to the next level of WS-Security with a brief introduction to digital signatures, which focus on confirming the identity of the sender and guaranteeing message integrity. You can use an equivalent configuration with the same public key cryptography approach to encrypt actual message content. To work through the example in this article, download the Oracle Application Server 10g Release 10.1.3 Developer Preview from OTN.

My next column will show how to apply security to non-Oracle Web services by using the Web Services gateway as a security policy enforcement point.


Mike Lehmann is Oracle's director of product management for J2EE and Web services. You can read his blog at radio.weblogs.com/0132036/ .


Send us your comments