How-To : Using ORMI/SSL with OC4J

Date: 1/18/06
Author: Jeff Trent/Debu Panda

Introduction

OC4J supports ORMIS using two certificate stores namely Java KeyStore and Oracle Wallet. In this tutorial.This tutorial demonstrates Oracle's support for using RMI/SSL (ORMIS) for looking up remote objects using both mechanisms. Configuring certificate using either Java keytool or Oracle Wallet Manager is beyond the scope of this article. This example includes pre-configured certificates for demonstration purpose.

Configuring OC4J to use ORMIS

To enable, ORMIS you have to make the following changes in the config/rmi.xml

  • Configure the ORMIS port. The default ORMIS port is 23793. 
                                  <rmi-server xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/rmi-server-10_0.xsd"      port="23791"                                       ssl-port="23943"  <!—the default SSL server port for OC4J -->                                      schema-major-version="10"       schema-minor-version="0">
    In an OracleAS managed install, the RMI/RMIS port defined in rmi.xml is ignored. make sure that you have defined port range rmis for your OC4J instance $ORACLE_HOME/opmn/conf/opmn.xml.

     

                                                                      <port id="rmis" range="12701-12800"/>

  • Configure keystore. You can either use Java Keystore or Oracle Wallet based certificates but you cannot enable both of them. You have to add the following element in the rmi.xml: 
                                  <ssl-config keystore="location-to-the-keystore" keystore-password="server-key-password"/>
    The location can either be an absolute path or relative path from the j2ee/home/config directory.
  • OC4J needs to be restarted after making these changes.

Client side requirement

You need the following in the client-side to use ORMIS protocol:

  • You have to provide the client-side certificate information i.e. location of client key and key password as JVM arguments. For example, you have to run the client as follows:
    java -Djavax.net.ssl.keyStore=etc\keystore\client.ks -Djavax.net.ssl.keyStorePassword=clientkey HelloClient
  • You have use ormis protocol in the provider URL as follows in the standalone:
    java.naming.provider.url=ormis://localhost/helloworld
    If you are using a OracleAS install then make sure that your providerURL includes opmn:ormis format as follows: java.naming.provider.url=opmn:ormis//localhost:6003:home/ORMIS

Prerequisites

What you need to know

  • Java Key tool and/or Oracle Wallet
  • RMI

For further information on OC4J, see the following documents on OTN:

Software Requirements

This demonstration requires that the following software components are installed and configured correctly:

Notations

  • %ORACLE_HOME% - The directory where you installed the Oracle Application Server 10g (10.1.3)
  • %JAVA_HOME% - The directory where your JDK is installed
  • %HOWTO_HOME% - The directory where this demo is unzipped

Building the Application

The configuration files are located in the %HOWTO_HOME%/etc directory, including deployment descriptor files such as application.xml.

Running the Application

To run the sample application on a standalone instance of Oracle Application Server 10g 10.1.3 , follow these steps:

1. Examine the Sample File Directories

  • build - temporary directory created during the build
  • log - temporary directory holding build/deploy logs
  • etc - all necessary files to package the application
  • lib - holds the application archives that could be deployed
  • doc - the How-to document and Javadoc's
    • how-to-ORMIS.html - this How-to page
  • src - the source of the demo
    • ejb - contains the sample session bean and client code

2. Configure the Environment

Ensure the following environment variables are defined:

  • %ORACLE_HOME% - The directory where you installed OC4J.
  • %JAVA_HOME% - The directory where you installed the J2SE 5.0
  • %PATH% - Must include %ORACLE_HOME%\ant\bin

 

Configure ORMIS

For using ORMIS, you must configuration changes in the %ORACLE_HOME%/j2ee/home/config/rmi.xml to specify the ORMI/SSL port and key store configuration.

  • Configure the ORMIS port. The default ORMIS port is 23793. 
                                  <rmi-server xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/rmi-server-10_0.xsd"      port="23791"                                       ssl-port="23943"  <!—the default SSL server port for OC4J -->                                      schema-major-version="10"       schema-minor-version="0">
    In an OracleAS managed install, the RMI/RMIS port defined in rmi.xml is ignored. Make sure that you have defined port range rmis for your instance $ORACLE_HOME/opmn/conf/opmn.xml.
  • Configure keystore. You can either use Java Keystore or Oracle Wallet based certificates but you cannot enable both of them. You have to add the following element in the rmi.xml. 
                                  <ssl-config keystore="location-to-the-keystore" keystore-password="server-key-password"/>
    To run this example, we have included a pre-configured sample Oracle Wallet. To use this sample wallet, copy the wallets directory in %HOW_TO_HOME%/etc to %ORACLE_HOME%/j2ee/home
    <ssl-config keystore="../wallets/wallet-server-a/ewallet.p12" keystore-password="serverkey-a"/>

3. Start the Oracle Application Server 10g

Start OC4J stand alone using the following command after you make the above changes.

>%ORACLE_HOME%/bin/oc4j -start

If you are using an OracleAS managed install, start using the following command after you make the above changes.

> %ORACLE_HOME%/opmn/bin/opmnctl startall

4. Generate, Compile, and Deploy the Application

Ant 1.6.2 is shipped with OC4J and you have to set your PATH environment variable to $ORACLE_HOME/ant/bin. On some operating systems, Ant does not currently support the use of environment variables. If this is the case for your operating system, please modify the ant-oracle.xml file located in the %HOWTO_HOME% directory.

Edit ant-oracle.properties (in the demo directory) and ensure the following properties are set to the correct values, as indicated below for OC4J standalone:

  • oc4j.host: host where OC4J is running (default localhost)
  • oc4j.admin.port: RMI port number (default 23791)
  • oc4j.admin.user: admin user name (default oc4jadmin)
  • oc4j.admin.password: admin user password (default welcome)
  • oc4j.binding.module: website name where deployed web modules are bound (default http-web-site)

If you are using OracleAS managed install then you have appropriately change the following properties beside changing oc4j.admin.user and oc4j.admin.password for your managed OC4J instance in OracleAS install.

  • opmn.host: the hostname/IP where OracleAS is running (default localhost)
  • opmn.port: OPMN request port (default 6003) for the OracleAS install
  • oc4j.instance: admin user name (default oc4jadmin)

You have to uncomment appropriate deployer.uri in the ant-oracle.properties and make changes based on your environment i.e. a single instance OC4J or a clustered OC4J instance/group managed by OPMN .

You have to make changes in jndi.properties such as provider.url, principal and credential appropriate to your environment. If you are using OracleAS install, you have to use provider.url in the following format: opmn:ormis://localhost:6003:home/ORMIS.

To build the application, type the following command from the %HOWTO_HOME% directory:

>ant

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

This command will attempt to deploy the application archive if the build is successful. It will first test whether OC4J is running before attempting the deployment operation.

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

5. Run the Application

Run the sample by running the command. Please make sure to change the jndi.properties file for any changes specific to your environment as we described in Client Side requirement section. Change the ant-oracle.xml to have appropriate Oracle Wallet information for your clients if you are not using the default client wallet shipped with the demo.

ant run

You will get the following output:


[java] client started...
[java] using ormis://localhost/helloworld
[java] Hello Scott

Summary

In this document, you should have learned :

  • How to use ORMI/SSL with OC4J
  • Deploy and run a simple application that uses ORMI/SSL

 

Left Curve
Popular Downloads
 Right Curve
Untitled Document