Using asymmetric cryptography in OWSM

Introduction

It has been somewhat a common practice replicating the same java key store across interacting WLS domains so that web services clients and web services can chat with message protection (WSS - Web Services Security). In that case, OWSM (Oracle Web Services Manager) is able to default to the private key stored in the key store to encrypt the symmetric key used for message encryption/decryption.

While that’s acceptable in developments environments, it might not be in production mode. Organizations may want to eliminate the risk of having the private key shared and compromised in distributed WLS deployments.

This article describes how that can be implemented in OWSM by examining the required OWSM configuration and two sample client applications: one Oracle ADF using a Web Service Data Control and one non-ADF using JAX-WS proxy.

Long story short: web services providers distribute their public key to consumers, who in turn explicitly refer to them when attaching OWSM client-side policies by overriding the keystore.recipient.alias property. Keep reading if you are interested in seeing how that is done.

Configuring the WLS domain hosting the web service

Let’s first understand how OWSM gets the services it needs to work with WSS.

OWSM relies on OPSS (Oracle Platform Security Services) configuration for its required services. By default, OWSM looks for the “default” jpsContext to get a hold of them. We’re interested in credstore and keystore services. OPSS configuration is held in jps-config.xml that sits in $DOMAIN_HOME/config/fmwconfig.

In the snippet below, we’re looking at the default jpsContext in jps-config.xml.

   1: <jpsContexts default="default">

   2:     <!-- This is the default JPS context. All the mendatory services and Login Modules must be configured in this default context -->

   3:     <jpsContext name="default">

   4:         <serviceInstanceRef ref="credstore"/>

   5:         <serviceInstanceRef ref="keystore"/>

   6:         <serviceInstanceRef ref="policystore.xml"/>

   7:         <serviceInstanceRef ref="audit"/>

   8:         <serviceInstanceRef ref="idstore.ldap"/>

   9:     </jpsContext>

Line 5 above tells OWSM to look for the keystore serviceInstance, which is out-of-box defined as:

   1: <!-- KeyStore Service Instance -->

   2:         <serviceInstance name="keystore" provider="keystore.provider" location="./default-keystore.jks">

   3:             <description>Default JPS Keystore Service</description>

   4:             <property name="keystore.type" value="JKS"/>

   5:             <property name="keystore.csf.map" value="oracle.wsm.security"/>

   6:             <property name="keystore.pass.csf.key" value="keystore-csf-key"/>

   7:             <property name="keystore.sig.csf.key" value="sign-csf-key"/>

   8:             <property name="keystore.enc.csf.key" value="enc-csf-key"/>

   9:         </serviceInstance>

It basically says that ./default-keystore.jks is the keystore file holding the certificate keys for WSS.

Likewise, line 6 in the first snippet informs OWSM on the credential store service. The credential store holds the credentials required for accessing the keystore as well as the aliases defined within it. Here’s how the cred store service is configured in jps-config.xml. Notice the location attribute. It points to the current directory. In reality, the credential store (as a file) is materialized as cwallet.sso file in that directory.

   1: <!-- JPS Credential Store Service Instance -->

   2:         <serviceInstance name="credstore" provider="credstoressp" location="./">

   3:             <description>File Based Credential Store Service Instance</description>

   4:         </serviceInstance>

Ok, basic OPSS configuration understood, let’s create an asymmetric key pair for the WLS server hosting the web service.

To execute the subsequent commands, have the keytool tool in your system path.

> keytool -genkeypair -keyalg RSA -alias orakey -keypass welcome1 -keystore default-keystore.jks -storepass welcome1 -validity 3600 

Now default-keystore.jks contains a self-signed certificate whose encrypting algorithm is RSA. RSA will be used for encrypting the symmetric key that encrypts the SOAP message.

Notice the storepass parameter value, which is welcome1. That defines the keystore password. Also notice the alias parameter and keystore parameter values. Those need to be properly seeded in the credential store. Please refer to this article on how to create them.

Next step is exporting the public key to a file.

> keytool -export -keystore default-keystore.jks -alias orakey -file server.crt

Such public key (server.crt) is the one that is distributed to everyone who wants to call in the WSS web services in this WLS domain.

Configuring the WLS domain hosting the web service client

The same jps-config.xml configuration applies to the WLS client domain. But in the client we just need to import the server.crt file containing the server public key into the key store.

> keytool -import -trustcacerts -alias server-public-cert -file server.crt -keystore default-keystore.jks

Notice the alias name: server-public-cert. It defines to where the public key is copied within the key store. You’ll need this name when overriding the keystore.recipient.alias property in the OWSM policy attachment in the web service client application.

Overriding the keystore.recipient.alias property

In this example, our client application is an ADF one that invokes the web service via an ADF Web Service Data Control. I won’t go into the details of defining the data control here. That’s something that can be found in the ADF Developers Guide available at OTN or in JDeveloper itself.

Once the data control is defined, follow these steps:

1 - In Applications Navigator, click the DataControls.dcx file:

2 - In the DataControls.dcx structure, right click the ADF Data Control Web Service and then click Define Web Service Security… option:

3 – In the Edit Data Control Policies window, choose oracle/wss11_username_token_with_message_protection_client_policy. It will allow the client to propagate a fixed identity to the web service at the same time providing WSS to the entire SOAP message. Take a bit of time to read the policy description. It is worth it.

Do notice that choosing such policy implies that the web service is configured with the corresponding OWSM server-side policy.



4 – Click the Override Properties button.

The csf-key property defined the key in the credential store that holds the user to be propagated to the web service in the UsernameToken header.

In order to create it, execute the following wlst online command in the client WLS domain:

> createCred(map=”oracle.wsm.security”,key=”manager-key”,user=”my-wife”,password=”yesdear”)

If you click the New Key.. button, you have the opportunity to define it right here (thus avoiding the wlst command above) and it will be pushed to the WLS domain credential store when you deploy your application (this “pushing credentials”  feature can be disabled if you want).

keystore.recipient.alias is what we’re really interested in this article. It references the alias name for the server public key in the WLS client domain’s key store.

What if my client application is a non-ADF one?

If you had a JAX-WS proxy in a non-ADF client application, this is how you would do it.

Notice line 25. There we’re overriding the keystore.recipient.alias.

   1: …

   2: import java.net.MalformedURLException;

   3: import java.net.URL;

   4: import javax.xml.namespace.QName;

   5: import javax.xml.parsers.DocumentBuilderFactory;

   6: import javax.xml.ws.BindingProvider;

   7: import oracle.j2ee.ws.common.jaxws.ServiceDelegateImpl;

   8: import oracle.webservices.ClientConstants;

   9: import oracle.wsm.security.util.SecurityConstants;

  10: import org.w3c.dom.Element;

  11: …

  12:         String endpoint = "http://127.0.0.1:7101/context-root/GreetingsAppModuleService";

  13:  

  14:         URL wsdlURL = new URL(endpoint+"?WSDL");

  15:  

  16:        ServiceDelegateImpl serviceDelegate = new ServiceDelegateImpl(wsdlURL, new QName("http://xmlns.oracle.com/trunk/owsm/", "GreetingsAppModuleService"), oracle.webservices.OracleService.class);

  17:        MyAppModuleService port = serviceDelegate.getPort(new QName("http://xmlns.oracle.com/trunk/owsm/", "GreetingsAppModuleServiceSoapHttpPort"), GreetingsAppModuleService.class );

  18:        

  19:         InputStream isClientPolicy = this.getClass().getResourceAsStream("client-policy.xml");

  20:        

  21:         try {

  22:           ((BindingProvider)port).getRequestContext().put(ClientConstants.CLIENT_CONFIG, fileToElement(isClientPolicy));

  23:           ((BindingProvider)port).getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpoint);

  24:           ((BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSS_CSF_KEY, "manager-key");

  25:           ((BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSS_RECIPIENT_KEY_ALIAS, "server-public-cert");

  26:         }

  27:         catch (Exception ex) {

  28:           ex.printStackTrace();

  29:         }

  30:        

  31:  

  32:         return port.sayHello(name);

  33:  

  34:     public static Element fileToElement(InputStream f) throws IOException, Exception {

  35:        DocumentBuilderFactory builderFactory = DocumentBuilderFactory.newInstance();

  36:        builderFactory.setValidating(false);

  37:        builderFactory.setNamespaceAware(true);

  38:        builderFactory.setIgnoringElementContentWhitespace(true);

  39:        builderFactory.setIgnoringComments(true);

  40:        return builderFactory.newDocumentBuilder().parse(f).getDocumentElement();

  41:     }

The client-policy.xml would be:

   1: <?xml version="1.0" encoding="UTF-8"?>

   2: <oracle-webservice-clients>

   3:    <webservice-client>

   4:        <port-info>

   5:            <policy-references>

   6:                <policy-reference uri="oracle/wss11_username_token_with_message_protection_client_policy" category="security"/>

   7:             </policy-references>

   8:        </port-info>

   9:    </webservice-client>

  10: </oracle-webservice-clients>

Conclusion

In this article I showed how to use real asymmetric cryptography in OWSM by examining the keystore configuration details and looked at how web services client applications should be configured to support it. I believe this is a very important topic, since it eliminates the risk of having a single private key shared across WLS domains that participates in web services interactions.