Web Services Security Interoperability between .NET and Oracle Application Server.

Date:  Feb 6, 2006
Author:   Sirish V Vepa


Introduction

SSL could be used to secure the communications. However, the security is bound to the transport channel. The message is not secure once it is received from the peer. To overcome the dependence on transport security, and also meet emerging business requirements, a new standard was developed.

The OASIS standard WS-Security offers a mechanism to authenticate requests in addition to providing integrity and confidentiality of the messages.
This example demonstrates interoperability between a Microsoft .NET Web Service Client and a Web Service hosted in Oracle OC4J, one of the very important facets of the WS-Security.

Prerequisites

What you need to know

  • Web Services - a software component that is described via WSDL and is capable of being accessed via standard network protocol such as HTTP.
  • Simple Object Access Protocol - is a XML based protocol for exchanging information in a decentralized distributed environnment ( SOAP)
  • Web Services Security - defines an open security standard. (WS-Security)
  • XML Digital Signature - defines how to verify the integrity of an XML object
  • XML Encryption - defines encrypting XML Messages.
  • OTN has a few web services samples that are relevant to this example. The basic Web Services Security and Constructing a simple Web Service are good examples.

Software Requirements

Software requirements

  • OracleAS 10.1.3 is installed, available from OTN
  • Sun's JDK 1.4_01 or above
  • Microsoft .NET Framework 1.1 (or above) Software Development Kit Refer to the .NET Framework 1.1 SDK download link
  • Microsoft Web Services Enhancements (WSE) 2.0 SP2 (or above) for Microsoft .NET, available from here
  • Microsoft Visual Studio .NET 2003 (optional for this article) , available here

Notations

Notations used throughout the document

  • %HOWTO_HOME%- The directory where this sample was unzipped.
  • %ORACLE_HOME% - The directory where you installed the Oracle Application Server 10 g.
  • %JAVA_HOME% - The directory where your JDK is installed
  • %WSE_DIR%- The directory where you installed Microsoft Web Services Enhancements v2.0 for Microsoft .NET

Building the Application



Employee Verification Service

Consider you need to provide your employment history as part of a job application to the requesting party (prospective employee). An Employment Verification Service (EVS) provides a secure and an automatic mechanism of sharing this information with the requestor. Given that the employment history may contain personal information such as your Social security number, date of birth, etc, this information should be treated carefully, and as such you perhaps would want to share this information with someone you could trust (a future employee).

In this service, you provide the requestor with a key, which will give access to your employment history to the requestor. The key is a constructed from information known to you, the EVS and the requestor. Thus, it is necessary to protect the key when it is sent over the Internet.

This example is a highly simplified EVS, which checks if there is any employment history at all for the applicant. To sufficiently protect the communication, the request is signed and encrypted. The response is sent in clear.

Signing the request provides message integrity and message authentication (who sent the message?). Requests for employment verification are received only from known employees. Encryption obfuscates the request, and thus is kept a secret from an eavesdropper.

Since the response is a 'yes/no', confirming whether the applicant has an employment history or not, and is not meaningful to an eavesdropper (we don't know for whom the request was sent!!!), the response is sent in the clear.

The EVS is represented as a Web Service hosted in OC4J. The client is a .NET client. The web service method exists represents the request/response between the .NET client and OC4J. The figure below illustrates this scenario.

Protecting the Requests

The request needs to be signed and encrypted. The signing operation is performed using a private key. Hence, the .NET client requires a private key accessible to it. Encryption utilizes the recipient's public key. Thus, the .NET client also requires the recipient's public key.

Conversely, to verify the request, the client's public key must be accessible to OC4J, and to decrypt the message, the Web Service must use the decryption private key. As part of building the application, we need to distribute the public keys to the respective counterparts (OC4J and .NET client).

WSE ships with a few sample test certificates. For this example, .NET Client for XML signing will use the WSE2QuickStartClient Certificate.

 

This Web Service also ships with a test certificate oc4j_webservice_decrkey that is used for decrypting the request. The figure below shows the desired setup.

 

Examining the Sample File Directories

List the contents of the ZIP file, for example

  • how-to-wss-interop/src/ - contains all source code for the example.
    • client/ 
      • Client.java-Test Java web service client for the WSS-Interop example.
    • webservice/
      • EmployeeVerificationImpl.java - Web Service Implementation.
    • dotn
      • VerificationService/
        • Client.cs- .NET C# Client source Code
        • build.bat- batch file to compile the Client
  • how-to-jazn/ etc/
    • clientConfig.xml - Java Web Service Client Security Policy Configuration.
    • serverConfig.xml - Web Services Security Policy Configuration.
    • service.jks - Java Key Store used by the Web Service.
    • client.jks- Java Key Store used by the Java Web Service client
  • how-to-wss-interop/doc/
    • Readme.html - This document.
  • how-to-wss-interop/build.xml - An Ant build file.  

Configuring the Environment

ant-oracle.properties
  • oracle.home - the root directory of oracle installation.  Defaults to ORACLE_HOME environment variable.
  • java.home -  the root directory of JDK installation.  Defaults to JAVA_HOME environment variable.
  • oracleas.host - the hostname of the platform on which the OC4J instance is running.  Defaults to localhost.
  • oracleas.http.port - the port on which the OC4J HTTP listener is listening.  Defaults to 8888.
  • oracleas.admin.port  - the port on which the OC4J administration processor is listening.  Defaults to 23791.
  • oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
  • oracleas.admin.password - the password for the OC4J administrator.  Defaults to " welcome".
  • oracleas.binding.module - the name of the HTTP web site to which the deployed application is bound.  Defaults to " default-web-site".
%ORACLE_HOME%/ant/bin

Configuring the Environment for a Managed OracleAS Instance

g
  • oracleas.http.port - the port on which the Oracle HTTP Server (OHS) is listening.
  • oracleas.admin.port  - The OPMN request port, as specified in opmn.xml, the default value is 6003.  You can also check the OPMN request port using the following command: %ORACLE_HOME%/opmn/bin/opmnctl status -port
  • oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
  • oracleas.deployer.uri - the URI to use to do the different administration operation (deployment, undeployment). The file contains different URI depending of the topology of your application: stand alone OC4J, Managed Single Node or Managed Cluster. You just need to un-comment the URI that matches your toplogy.
  • oracleas.oc4j.instance - This is the managed OC4J instance where the application will be deployed or undeployed.

Configuring Certificates in the Microsoft Client.

 

Installing the Signing Key

The WSE client will use the Windows store to access the X.509 Certificates and the corresponding private keys. The certificates are located under %WSE_DIR%\v2.0\Samples\Sample Test Certificates . Refer to instructions under %WSE_DIR%\v2.0\Samples\Sample Test Certificates\readme.htm . Install the Client certificate whose subject name is WSE2QuickStartClient. This installs the signing key for the .NET client.

NOTE If you are using WSE v3.0, the certificates can be installed by running a setup batch file. Refer to the instructions in %WSE_DIR%\v3.0\Samples\readme.htm .

Installing the Encryption Key

The public key corresponding to the decryption key used by the web service must be installed in the Microsoft client. This is accomplished by first exporting the public key from the Java Key Store used by the web service. Issue the following command.

keytool -export -file c:\temp\service.cer -alias oc4j_service_decrkey -keystore %HOWTO_HOME%\etc\service.jks -storepass oracle

The certificate is exported to the file c:\temp\service.cer.

From a Windows Explorer, double-click on this file, and click on Install Certificate.

Import the certificate into the Personal store.

 

Configuring the Web Service Java Key Store.

%HOWTO_HOME%

 

Exporting the Signing Key

  1. Open the Microsoft Management Console (MMC) by running mmc.exe.

     

  2. Click on File -> Add/Remove Snap-In, click the Add button and select the Certificates snap-in option.

  3. Close the dialog and return to the MMC console.

     

  4. Navigate to the Personal store and select the WSE2QuickStartClient certificate.

  5.  

  6. Right click the WSE2QuickStartClient and select All Tasks->Export. Do not export the private key. Select DER encoded export type. Export to c:\temp\wse_client.cer.

     

  7. As part of the signature verification process in OC4J, the signer (and the certificate chain) must be trusted by OC4J, if not, the signature verification will fail. The WSE2QuickStartClient certificate has been issued by a test Certificate Authority (CA). This CA must first be exported from the Microsoft Key store and imported into the Java Key store.

     

    • Double-Click on WSE2QuickStartClient
    • Select Certification Path
    • Select Root Agency
    • Click on View Certificate
    • Select Details
    • Select Copy to File
    • Following the Wizard prompts. For the file export format, choose DER Encoded binary format.
    • Export file to c:\temp\mstest_rootca.cer
    • Exit from MMC.

     

  8. To import the certificates into the Web Service Java Key Store, issue the following command:

    keytool -import -file C:\temp\wse_client. cer -alias wse_client -keystore service.jks -storepass oracle

    When prompted to trust the certificate, enter yes

    keytool -import -file C:\temp\mstest_ca.cer -alias wse_rootca -keystore service.jks -storepass oracle

    When prompted to trust the certificate, enter yes

Starting the OC4J Instance

g

  • Stand Alone Installation: %ORACLE_HOME%/bin/oc4j start
    Note that the oc4j command expects the JAVA_HOME environment variable to point to a full JDK installation.

  • OracleAS Managed Installation: %ORACLE_HOME%/opmn/bin/opmnctl startall

Generating, Compiling and Deploying the Web Service

The web service is created using a bottom up approach. Using a Java Class, a WSDL is constructed, and from the WSDL, the Web Service is created. The web service is packaged as part of a J2EE application archive and deployed to OC4J. Creating a Web Service using this approach is discussed in an OTN sample 'How-to: Construct and Use Simple Web Services' (click on this link to locate this sample).

Security policies such as encryption and signing requirements for inbound and outbound messages are expressed in an XML file configured along with the Web Service. The file %HOWTO_HOME%\etc\serverConfig.xml contains all the policy requirements for this web service.

Since the Web Service requires that the request is signed and encrypted, the inbound policy declaration is expressed as

<runtime enabled="security"> <security> <key-store path="META-INF/service.jks" store-pass="oracle"/> <encryption-key alias="oc4j_service_decrkey" key-pass="service_secret123"/>
<inbound> ...

The inbound messages must be signed. The following XML fragment expresses this

<verify-signature>
  <signature-methods>
   <signature-method>RSA-SHA1</signature-method>
 </signature-methods>
   ...

RSA-SHA1 is the default signature method in OC4J, if the algorithm is not specified.

The request body is also decrypted. The following XML fragment expresses this

 <decrypt>
   <encryption-methods>
    <encryption-method>AES-128</encryption-method>
     </encryption-methods>
     <keytransport-methods>
     <keytransport-method>RSA-1_5</keytransport-method>
     </keytransport-methods>
     ...
 </decrypt>

ASE-128 is the default encryption algorithm for OC4J and WSE. The encryption method need not mentioned in the serverConfig.xml file, but is listed in this example for demonstration purpose only. Finally, the key transport algorithm is set to RSA15. Thus, messages exchanged between the .NET client and the Web Service hosted in OC4J should be interoperable.

To build and deploy the web service, type the following command from the %HOWTO_HOME% directory:

  • ant

You should now have the newly created EmployeeVerification.ear in your %HOWTO_HOME%/lib directory.

This command would also attempt to deploy the web service if the build is successful. It will first test whether OC4J is running.

Note that you can also deploy the application separately . Ensure the %ORACLE_HOME% environment variable is defined, and from the %HOWTO_HOME% directory, type the command:

ant deploy

Configuring .NET client to sign and encrypt the request

%HOWTO_HOME%\src\dotn\EmployeeVerificationServiceClient.cs hereWSE X.509 Certificate Tool
  1. Run the WSE X.509 Certificate Tool.

     

  2. Set the Certificate Location to 'Current User', and Store Name to 'Personal'. Click on Open Certificate. Select WSE2QuickStartClient and click on OK.

     

  3. The Windows Key Identifier (Base64 Encoded) is displayed as shown below.

    The value is hard coded in the Client code ( Client.cs )

     // base64 encoding of the Windows Key Identifier.
     String signKey = "gBfo0147lM6cKnTbbMSuMVvmFY4=";

     

  4. Repeat the above steps to verify the key identifier value for the encryption key is correctly set. The value is hardcoded in Client.cs

     // base64 encoding of the Windows Key Identifier.
     String encryptKey = "4UJqUr7kho+JSeFdfETLtrPkWLE=";

NOTEClient.cs

Building the .NET client

The .NET client code includes a Visual Studio Project file. The code could be compiled using Visual Studio, or, using the supplied batch file %HOWTOHOME%\src\dotn\VerificationServices\build.bat. Executing the batch file, from the VerificationServices directory. The client executable is created in the current directory. If the batch file is executed, make certain the Path, Include and Lib environment variables required by the .NET SDK are correctly setup. Set the Path, Include and Lib environment variables by running SDKVars.bat, located in the SDK\v1.1\Bin directory.

Running the Application

Running the .NET Client

The .NET Web Service Client program is executed by running the Client.exe executable. The output should look similar to this screen shot

 

Running the Java Client

%HOWTO_HOME%\src\client %HOWTO_HOME%\etc\clientConfig.xml ant cli-build

To run the client, execute ant cli-run . The output should look similar to this screen shot.

The warning messages issued by the client runtime can be ignored, since the Java Keystore used by the client ( client.jks), contains certificates that do not have the subjectKeyIdentifier (version 1 X.509 certificate). This should not be an issue in a production environment using X.509 v3 certificates.

Summary

  • The need for Web Services Security.
  • Public Key Infrastructure requirements to enable secure communications in a distributed environment.
  • Demonstrated Web Services Security interoperability.
    • The client was created using Microsoft .NET Framework.
    • The Web Service was developed using Oracle WebServicesAssember tools and Oracle Application Server.
    • The .NET client is able to send a signed/encrypted SOAP request to the Web Service hosted in OC4J.
Left Curve
Popular Downloads
 Right Curve
Untitled Document