Skip Headers

Oracle Application Server Containers for J2EE Services Guide 10g (9.0.4) Part Number B10326-01 |
| Home | Contents | Index

# 6
J2EE Interoperability

This chapter describes Oracle Application Server Containers for J2EE (OC4J) support for allowing EJBs to invoke one another across different containers using the standard Remote Method Invocation (RMI)/Internet Inter-Orb Protocol (IIOP) protocol.

This chapter covers the following topics:

- Introduction to RMI/IIOP

- Switching to Interoperable Transport

- Configuring OC4J for Interoperability

## Introduction to RMI/IIOP

Java Remote Method Invocation (RMI) enables you to create distributed Java-based to Java-based applications, in which the methods of remote Java objects can be invoked from other Java virtual machines (JVMs), possibly on different hosts.

Version 2.0 of the EJB specification adds features that make it easy for EJB-based applications to invoke one another across different containers. You can make your existing EJB interoperable without changing a line of code: simply edit the bean's properties and redeploy. "Switching to Interoperable Transport" discusses redeployment details.

EJB interoperability consists of the following:

- Transport interoperability through CORBA IIOP (Internet Inter-ORB Protocol, where ORB is Object Request Broker)

- Naming interoperability through the CORBA CosNaming Service (CORBA Object Service Naming, part of the OMG CORBA Object Service specification)

- Security interoperability through Common Secure Interoperability Version 2 (CSIv2)

- Transaction interoperability through the CORBA Transaction Service (OTS)

OC4J furnishes the first three of these features.

### Transport

By default, OC4J EJBs use RMI/Oracle Remote Method Invocation (ORMI), a proprietary protocol, to communicate as described in Chapter 5, "Oracle Remote Method Invocation".

Note: For the OC4J 10g (9.0.4) implementation, load balancing and failover are supported only for ORMI, not IIOP.

In OC4J, you can easily convert an EJB to use RMI/IIOP, making it possible for EJBs to invoke one another across different EJB containers. This chapter describes configuring and using RMI/IIOP.

### Naming

OC4J supports the CORBA CosNaming service. OC4J can publish `EJBHome` object references in a CosNaming service and provides a JNDI CosNaming implementation that allows applications to look up JNDI names using CORBA. You can write your applications using either the JNDI or CosNaming APIs.

### Security

OC4J supports Common Secure Interoperability Version 2 (CSIv2), which specifies different conformance levels; OC4J complies with the EJB specification, which requires conformance level 0.

### Transactions

The EJB2.0 specification stipulates an optional transactional interoperability feature. Conforming implementations must choose one of the following:

- Transactionally interoperable: transactions are supported between beans that are hosted in different J2EE containers.

- Transactionally noninteroperable: transactions are supported only among beans in the same container.

The current release of OC4J is transactionally noninteroperable, so, when a transaction spans EJB containers, OC4J raises a specified exception.

### Client-Side Requirements

In order to access EJBs, you must do the following on the client-side:

1. Download the `oc4j_client.zip` file from `http://otn.oracle.com/software/products/ias/devuse.html`

2. Unzip it into a client-side directory (for example, `d:\oc4jclient`)

3. Add `d:\oc4jclient\oc4jclient.jar` to your CLASSPATH

The oc4j_client.zip file contains all the JAR files required by the client (including `oc4jclient.jar` and `optic.jar`). These JARs contain the classes necessary for client interaction. You only need to add `oc4jclient.jar` to your CLASSPATH because all other JAR files required by the client are referenced in the `oc4jclient.jar` manifest classpath.

If you download this file into a browser, you must grant certain permissions as described in the "Granting Permissions" section of the Security chapter in the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide.

### The rmic.jar Compiler

To invoke or be invoked by CORBA objects, RMI objects must have corresponding stubs, skeletons, and IDL. Use the `rmic.jar` compiler to generate stubs and skeletons from Java classes or to generate IDL, as described in "Configuring OC4J for RMI".

For use with RMI/IIOP, be sure to compile using the `-iiop` option.

## Switching to Interoperable Transport

In OC4J, EJBs use RMI/ORMI, a proprietary protocol, to communicate (as described in Chapter 5, "Oracle Remote Method Invocation"). You can convert an EJB to use RMI/IIOP, making it possible for EJBs to invoke one another across EJB containers.

Note: RMI/IIOP support is based on the CORBA 2.3.1 specification. Applications that were compiled using earlier releases of CORBA may not work correctly.

The following four sections provide details on making the conversions.

### Simple Interoperability in a Standalone Environment

Follow these steps to convert an EJB to use RMI/IIOP in a standalone environment:

1. Restart OC4J with the `-DGenerateIIOP=true` flag.

2. Deploy your application using `admin.jar`. You must obtain the client's stub JAR file using the `-iiopClientJar` switch. Here is an example:

       java -jar $J2EE_HOME/admin.jar ormi://localhost admin welcome -deploy -file filename

        -deployment_name application_name -iiopClientJar stub_jar_filename

   Note: You must use the `-iiopClientJar` switch to enable interoperability (IIOP) for the application you are deploying. In OC4J, interoperability is enabled on a per-application basis.

3. Change the client's `classpath` to include the stub JAR file that was obtained during deployment by running `admin.jar` with the `-iiopClientJar` switch.

   A copy of the stub JAR file that were generated by OC4J can also be found in the server's deployment directory at:

       application_deployment_directory/appname/ejb_module/module_iiopClient.jar

4. Edit the client's JNDI property `java.naming.provider.url` to use a `corbaname` URL instead of an `ormi` URL. For details on the `corbaname` URL, see "The corbaname URL".

   Note: IIOP stub and tie class code generation occurs at deployment time, unlike ORMI stub generation, which occurs at runtime. This is why you must add the JAR file to the `classpath` yourself. If you run in the server, a list of generated classes required by the server and IIOP stubs is made available automatically.

5. (Optional) To make the bean accessible to CORBA applications, run `rmic.jar` to generate IDL (the Interface Description Language) describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.

### Advanced Interoperability in a Standalone Environment

This section expands upon the preceding section, describing how to convert an EJB to use RMI/IIOP in a standalone environment.

1. Specify CSIv2 security policies for the bean in`orion_ejb_jar.xml` and in `internal_settings.xml`. See "CSIv2 Security Properties (orion-ejb-jar.xml)" and "EJB Server Security Properties (internal-settings.xml)" for details.

2. Restart OC4J with the `-DGenerateIIOP=true` flag.

3. Deploy your application using `admin.jar`. You must obtain the client's stub JAR file using the `-iiopClientJar` switch. Here is an example:

       java -jar $J2EE_HOME/admin.jar ormi://localhost admin welcome -deploy -file filename

        -deployment_name application_name -iiopClientJar stub_jar_filename

   Note: You must use the `-iiopClientJar` switch to enable interoperability (IIOP) for the application that you are deploying. In OC4J, interoperability is enabled on a per-application basis.

4. Change the client's `classpath` to include the stub JAR file that was obtained during deployment by running `admin.jar` with the `-iiopClientJar` switch.

   A copy of the stub JAR file that was generated by OC4J can also be found in the server's deployment directory at:

       application_deployment_directory/appname/ejb_module/module_iiopClient.jar

5. Edit the client's JNDI property `java.naming.provider.url` to use a `corbaname` URL instead of an `ormi` URL. For details on the `corbaname` URL, see "The corbaname URL".

   Note: IIOP stub and tie class code generation occurs at deployment time, unlike ORMI stub generation, which occurs at runtime. This is why you must add the JAR file to the `classpath` yourself. If you run in the server, a list of generated classes required by the server and IIOP stubs is made available automatically.

6. (Optional) To make the bean accessible to CORBA applications, run `rmic.jar` to generate IDL (the Interface Description Language), describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.

### Simple Interoperability in Oracle Application Server Environment

You can access an EJB using RMI/IIOP in an Oracle Application Server environment in two ways:

- Configuring for Interoperability Using Oracle Enterprise Manager

- Configuring for Interoperability Manually

#### Configuring for Interoperability Using Oracle Enterprise Manager

You can configure an EJB to be accessible by means of RMI/IIOP in an Oracle Application Server environment by using Oracle Enterprise Manager. Follow these steps:

1. Navigate to an OC4J instance in which you want to allow access to applications through RMI/IIOP. Figure 6-1 shows an OC4J instance called `home`.

   #### Figure 6-1 Oracle Enterprise Manager System Components

   Text description of the illustration emsyscp4.gif

2. Click on Server Properties in the Administration section for this OC4J instance. This is shown in Figure 6-2.

   #### Figure 6-2 Oracle Enterprise Manager Server Properties

   Text description of the illustration emsysdp3.gif

   By default, RMI/IIOP is disabled in an Oracle Application Server environment. To enable RMI/IIOP, ensure that a unique IIOP port (or port range) exists for each OC4J instance by entering the value in the IIOP ports field, as shown in Figure 6-3. Click Apply.

   #### Figure 6-3 Oracle Enterprise Manager Port Configuration

   Text description of the illustration emports.gif

   Deploy your application following the Oracle Enterprise Manager deployment wizard.

   Enable generation of client IIOP stubs for this application by selecting Generate IIOP stubs, as shown in Figure 6-4.

   #### Figure 6-4 Oracle Enterprise Manager Stub Generation

   Text description of the illustration emstbgn2.gif

   Finish deploying your application following the Oracle Enterprise Manager deployment wizard.

#### Configuring for Interoperability Manually

Follow these steps to manually configure an EJB for remote access by RMI/IIOP in an Oracle Application Server environment:

1. By default, RMI/IIOP is disabled in an Oracle Application Server environment. To enable RMI/IIOP, confirm in OPMN's configuration file, `J2EE_HOME``/opmn/conf/opmn.xml`, that a unique IIOP port (or port range) exists for each OC4J instance to be managed by OPMN.

   Note: You must specify an IIOP port (or port range) for each OC4J instance in which interoperability is to be enabled. Failure to do so causes OC4J to not configure an IIOP listener, thus automatically disabling interoperability, regardless of the configuration in the `internal-settings.xm` file of OC4J.

Here is an example:

    <ias-component id="OC4J">
              <process-type id="home" module-id="OC4J">
                   <port id="ajp" range="3000-3100"/>
                   <port id="rmi" range="23791-23799"/>
                   <port id="jms" range="3201-3300"/>
                   <port id="iiop" range="3401-3500"/>
                   <process-set id="default_island" numprocs="1"/>
              </process-type>
     </ias-component>

- If you modify any configuration file manually, you must update the configuration with `dcmctl`. Use the following command:

      dcmctl updateConfig

- Using `opmnctl` or Oracle Enterprise Manager, restart all OC4J instances that are managed by OPMN.

  For information on `opmnctl`, use the following command:

      opmnctl help

  To stop and restart OPMN and all OPMN-managed processes, first use the following command:

      opmnctl stopall

  and then:

      opmnctl startall

  For information on Oracle Enterprise Manager, see the Oracle Application Server Containers for J2EE User's Guide.

- Deploy your application using `dcmctl`, specifying the `-enableIIOP` option. Here is an example:

      dcmctl deployApplication -f filename -a application_name -enableIIOP

- Change the client's `classpath` to include the stub JAR file that was generated by OC4J. This file is normally found in the server's deployment directory:

      application_deployment_directory/appname/ejb_module/module_iiopClient.jar

- Edit the client's JNDI property `java.naming.provider.url` to use an `OPMN` or `corbaname` URL instead of an `ormi` URL. For details on the `corbaname` URL, see "The corbaname URL". For details on the OPMN URL, see "The OPMN URL".

  Note: IIOP stub and tie class code generation occurs at deployment time, unlike ORMI stub generation, which occurs at runtime. This is why you must add the JAR file to the `classpath` yourself. If you run in the server, a list of generated classes required by the server and IIOP stubs is made available automatically.

- (Optional) To make the bean accessible to CORBA applications, run `rmic.jar` to generate IDL (the Interface Description Language), describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.

  ### Advanced Interoperability in Oracle Application Server Environment

  You can access an EJB using RMI/IIOP in an Oracle Application Server environment in two ways:

  - Configuring for Interoperability Using Oracle Enterprise Manager

  - Configuring for Interoperability Manually

  #### Configuring for Interoperability Using Oracle Enterprise Manager

  The advanced configuring for interoperability using Oracle Enterprise Manager differs from the simple configuring described under "Configuring for Interoperability Using Oracle Enterprise Manager" only in the specification of ports. That is, you must specify an `iiop`, `iiops1`, and `iiops2` port (or port range) for each OC4J instance in which interoperability with CSIv2 is to be enabled. Failure to do so causes OC4J to not configure an IIOP listener, thus automatically disabling interoperability, regardless of the configuration in the `internal-settings.xm` file of OC4J. This is shown in Figure 6-5.

  #### Figure 6-5 Oracle Enterprise Manager Port Specifications

  Text description of the illustration emprtad2.gif

  #### Configuring for Interoperability Manually

  This section expands upon the preceding section, describing how to convert an EJB to use RMI/IIOP in an Oracle Application Server environment.

  1. Specify CSIv2 security policies for the bean in `orion_ejb_jar.xml` and in `internal_settings.xml`. See "CSIv2 Security Properties (orion-ejb-jar.xml)" and "EJB Server Security Properties (internal-settings.xml)" for details.

  2. By default, RMI/IIOP is disabled in an Oracle Application Server environment. To enable RMI/IIOP, confirm in the OPMN configuration file, `J2EE_HOME``/opmn/conf/opmn.xml`, that a unique `iiop`, `iiops1`, and `iiops2` port (or port range) exists for each OC4J instance to be managed by OPMN. These are the port meanings:

     `iiop`--standard IIOP port

     `iiops1`--IIOP/SSL port used for server-side authentication only

     `iiops2`--IIOP/SSL port used for both client and server authentication

     Note: You must specify an `iiop`, `iiops1`, and `iiops2` port (or port range) for each OC4J instance in which interoperability with CSIv2 is to be enabled. Failure to do so causes OC4J to not configure an IIOP listener, thus automatically disabling interoperability, regardless of the configuration in the `internal-settings.xml` file of OC4J.

  Here is an example:

      <ias-component id="OC4J">
          <process-type id="home" module-id="OC4J">
              <port id="ajp" range="3000-3100"/>
              <port id="rmi" range="23791-23799"/>
              <port id="jms" range="3201-3300"/>
              <port id="iiop" range="3401-3500"/>
              <port id="iiops1" range="3501-3600"/>
              <port id="iiops2" range="3601-3700"/>
              <process-set id="default_island" numprocs="1"/>
          </process-type>
      </ias-component>

      Note:

      If you choose to configure your client's JNDI property java.naming.provider.url to use an OPMN URL, your client cannot connect to iiops1 or iiops2 ports because OPMN-allocated ports are not reported to OC4J.

- Using `opmnctl` or Oracle Enterprise Manager, restart all OC4J instances that are managed by OPMN.

  For information on `opmnctl`, use the following command:

      opmnctl help

  To stop and restart OPMN and all OPMN-managed processes, first use the following command:

      opmnctl stopall

  and then:

      opmnctl startall

  For information on Oracle Enterprise Manager, see the Oracle Application Server Containers for J2EE User's Guide.

- Deploy your application using `dcmctl`, specifying the `-enableIIOP` option. Here is an example:

      dcmctl  deployApplication -f filename -a application_name -enableIIOP

- Change the client's `classpath` to include the stub JAR file that was generated by OC4J. This is normally found in the server's deployment directory:

      application_deployment_directory/appname/ejb_module/module_iiopClient.jar

- Edit the client's JNDI property `java.naming.provider.url` to use an `OPMN` or `corbaname` URL instead of an `ormi` URL. For details on the `corbaname` URL, see "The corbaname URL". For details on the OPMN URL, see "The OPMN URL".

  Note: IIOP stub and tie class code generation occurs at deployment time, unlike ORMI stub generation, which occurs at runtime. This is why you must add the JAR file to the `classpath` yourself. If you run in the server, a list of generated classes required by the server and IIOP stubs is made available automatically.

- (Optional) To make the bean accessible to CORBA applications, run `rmic.jar` to generate IDL (the Interface Description Language), describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.

  ### The corbaname URL

  To interoperate, an EJB must look up other beans using CosNaming. This means that the URL for looking up the root `NamingContext` must use the `corbaname` URL scheme instead of the `ormi` URL scheme. This section discusses the `corbaname` subset that is most used by EJB developers. For a full discussion of the `corbaname` scheme, see section 2.5.3 of the CORBA Naming Service Specification. The `corbaname` scheme is based on the `corbaloc` scheme, which section 13.6.10.1 of the CORBA specification discusses.

  The most common form of the `corbaname` URL scheme is:

      corbaname::host[:port]

  This `corbaname` URL specifies a conventional DNS host name or IP address and a port number. For example,

      corbaname::example.com:8000

  A `corbaname` URL can also specify a naming context by following the host and port by `#` and `NamingContext` in string representation. The CosNaming service on the specified host is responsible for interpreting the naming context.

      corbaname::host[:port]#namingcontext

  For example:

      corbaname::example.com:8000#Myapp

  ### The OPMN URL

  This section describes OPMN URL details specific to RMI/IIOP. For general information about the OPMN URL, see "JNDI Properties for RMI".

  In an Oracle Application Server environment, IIOP ports for all OC4J processes within each Oracle Application Server instance are dynamically managed by OPMN. Because the ports are dynamically allocated by OPMN, it might not be possible for clients to know the ports on which OC4J processes are actively listening for IIOP requests. To enable clients to successfully make RMI/IIOP requests in an Oracle Application Server environment without having to know the IIOP ports for all active OC4J processes, modify the `jndi.naming.provider.url` property (in the client's `jndi.properties` file) with a URL of the following format:

      opmn:corbaname::opmn_host[:opmn_port]:]:OC4J_instance_name#naming_context

  For example:

      opmn:corbaname::dlsun74:6003:home#stateless

  Note: NOTE: For the OC4J 10g (9.0.4) implementation, load balancing and failover are supported only for ORMI, not IIOP.

  Note: If you choose to use an OPMN URL, your client cannot connect to `iiops1` or `iiops2` (`ssl-port` or `ssl-client-server-auth-port`) ports.

  ### Exception Mapping

  When EJBs are invoked over IIOP, OC4J must map system exceptions to CORBA exceptions. Table 6-1 lists the exception mappings.

  ##### Table 6-1 Java-CORBA Exception Mappings

  OC4J System Exception | CORBA System Exception
  --- | ---
  `javax.transaction. TransactionRolledbackException` | `TRANSACTION_ROLLEDBACK`
  `javax.transaction.` `TransactionRequiredException` | `TRANSACTION_REQUIRED`
  `javax.transaction.` `InvalidTransactionException` | `INVALID_TRANSACTION`
  `java.rmi.NoSuchObjectException` | `OBJECT_NOT_EXIST`
  `java.rmi.AccessException` | `NO_PERMISSION`
  `java.rmi.MarshalException` | `MARSHAL`
  `java.rmi.RemoteException` | `UNKNOWN`

  ### Invoking OC4J-Hosted Beans from a Non-OC4J Container

  EJBs that are not hosted in OC4J must add the file `oc4j_interop.jar` to the `classpath` to invoke OC4J-hosted EJBs. OC4J expects the other container to make the `HandleDelegate` object available in the JNDI name space at `java:comp/HandleDelegate.`The `oc4j_interop.jar` file contains the standard portable implementations of home and remote handles, and metadata objects.

  ## Configuring OC4J for Interoperability

  To add interoperability support to your EJB, you must specify interoperability properties. Some of these properties are specified when starting OC4J and others in bean properties that are specified in deployment files.

  ### Interoperability OC4J Flags

  The following OC4J startup flags support RMI interoperability:

  - `-DGenerateIIOP=true`: generates new stubs and skeletons whenever you redeploy an application.

  - `-Diiop.debug=true`: generates deployment-time debugging messages, most of which have to do with code generation.

  - `-Diiop.runtime.debug=true`: generates runtime debugging messages.

  ### Interoperability Configuration Files

  Before EJBs can communicate, you must configure the parameters in the configuration files listed in Table 6-2.

  ##### Table 6-2 Interoperability Configuration Files

  Context | File | Description
  --- | --- | ---
  Server | `server.xml` | The `<sep-config>` element in this file specifies the path name, normally `internal-settings.xml`, for the server extension provider properties. For example: <sep-config path="./internal-settings.xml">
  | `internal-settings.xml` | This file specifies server extension provider properties that are specific to RMI/IIOP. See "EJB Server Security Properties (internal-settings.xml)" for details.
  Application | `orion-ejb-jar.xml` | The `<ior-security-config>` subentity of the `<session-deployment>` and `<entity-deployment>` entities specifies Common Secure Interoperability Version 2 (CSIv2) security properties for the server. See "CSIv2 Security Properties" for details.
  | `ejb_sec.properties` | This file specifies client-side security properties for an EJB. See "EJB Client Security Properties (ejb_sec.properties)" for details.
  | `jndi.properties` | This file specifies the URL of the initial naming context used by the client. See "JNDI Properties for Interoperability (jndi.properties)" for details.

  ### EJB Server Security Properties (internal-settings.xml)

  You specify server security properties in the `internal-settings.xml` file.

  Note: You cannot edit `internal-settings.xml` with the Oracle Enterprise Manager.

  Note: If you choose to configure your client's JNDI property `java.naming.provider.url` to use an `OPMN` URL, your client cannot connect to `ssl-port` and ssl-client-server-auth-port ports because OPMN-allocated ports are not reported to OC4J.

  This file specifies certain properties as values within `<sep-property>` entities. Table 6-3 contains a list of properties.

  The table refers to keystore and truststore files, which use the Java Key Store (JKS), a JDK-specified format, to store keys and certificates. A keystore stores a map of private keys and certificates. A truststore stores trusted certificates for the certificate authorities (CAs, such as VeriSign and Thawte).

  ##### Table 6-3 EJB Server Security Properties

  Property | Meaning
  --- | ---
  `port` | IIOP port number (defaults to 5555).
  `ssl` | true if IIOP/SSL is supported, false otherwise.
  `ssl-port` | IIOP/SSL port number (defaults to 5556). This port is used for server-side authentication only. If your application uses client and server authentication, you also must set ssl-client-server-auth-port.
  `ssl-client-server-auth-port` | Port used for client and server authentication (defaults to 5557). This is the port on which OC4J listens for SSL connections that require both client and server authentication. If not set, OC4J will listen on ssl-port + 1 for client-side authentication.
  `keystore` | Name of keystore (used only if ssl is true).
  `keystore-password` | The keystore password (used only if ssl is true).
  `trusted-clients` | Comma-separated list of hosts whose identity assertions can be trusted. Each entry in the list can be an IP address, a host name, a host name pattern (for instance, *.example.com), or *. An * alone means that all clients are trusted. The default is to trust no clients.
  `truststore` | Name of truststore. If you do not specify a truststore for a server, OC4J uses the keystore as the truststore (used only if ssl is true).
  `truststore-password` | Truststore password (can be set only if ssl is true).

  Note: In Table 6-3, the properties `keystore-password` `andtruststore-password` support password indirection. For more information, refer to the Oracle Application Server Containers for J2EE Security Guide.

  If OC4J is started by the Oracle Process Management Notification service (OPMN) in an Oracle Application Server (as opposed to standalone) environment, then ports specified in `internal-settings.xml` are ignored. If OPMN is configured to disable IIOP for a particular OC4J instance, then, even though IIOP may be enabled through `internal-settings.xml` (as pointed to by `server.xml`), IIOP is not enabled.

  The following example shows a typical `internal-settings.xml` file:

      <server-extension-provider name="IIOP"
              class="com.oracle.iiop.server.IIOPServerExtensionProvider">
          <sep-property name="port" value="5555" />
          <sep-property name="host" value="localhost" />
          <sep-property name="ssl" value="false" />
          <sep-property name="ssl-port" value="5556" />
          <sep-property name="ssl-client-server-auth-port" value="5557" />
          <sep-property name="keystore" value="keystore.jks" />
          <sep-property name="keystore-password" value="123456" />
          <sep-property name="truststore" value="truststore.jks" />
          <sep-property name="truststore-password" value="123456" />
          <sep-property name="trusted-clients" value="*" />
      </server-extension-provider>

  Note: Although the default value of `port` is one less than the default value for `ssl-port`, this relationship is not required.

  Here is the DTD for `internal-settings.xml:`

      <!-- A server extension provider that is to be plugged in to the server.
      -->
      <!ELEMENT server-extension-provider (sep-property*) (#PCDATA)>
      <!ATTLIST server-extension-provider name class CDATA #IMPLIED>
      <!ELEMENT sep-property (#PCDATA)>
      <!ATTLIST sep-property name value CDATA #IMPLIED>
      <!-- This file contains internal server configuration settings. -->
      <!ELEMENT internal-settings (server-extension-provider*)>

  ### CSIv2 Security Properties

  CSIv2 is an Object Management Group (OMG) standard for a secure interoperable wire protocol that supports authorization and identity delegation. You configure CSIv2 properties in three different locations:

  - `internal_settings.xml`

  - `orion-ejb-jar.xml`

  - `ejb_sec.properties`

  "CSIv2 Security Properties (internal-settings.xml)", "CSIv2 Security Properties (orion-ejb-jar.xml)", and "EJB Client Security Properties (ejb_sec.properties)" discusses these configuration files.

  ### CSIv2 Security Properties (internal-settings.xml)

  This section discusses the semantics of the values you set within the `<sep-property>` element in `internal_settings.xml`. For details of syntax, see "EJB Server Security Properties (internal-settings.xml)" .

  To use the CSIv2 protocol with OC4J, you must both set `ssl` to `true` and specify an IIOP/SSL port (`ssl-port`).

  - If you do not set `ssl` to `true`, then CSIv2 is not enabled. Setting `ssl` to `true` permits clients and servers to use CSIv2, but does not require them to communicate using SSL.

  - If you do not specify an `ssl-port`, then no CSIv2 component tag is inserted by the server into the IOR, even if you configure an <`ior-security-config>` entity in `orion-ejb-jar.xml`.

  When IIOP/SSL is enabled on the server, OC4J listens on two different sockets--one for server authentication alone, and one for server and client authentication. You specify the server authentication port within the `<sep-property>` element. The server and client authentication listener uses the port number immediately following.

  For SSL clients using server authentication alone, you can specify:

  - Truststore only

  - Both keystore and truststore.

  - Neither

  If you specify neither keystore nor truststore, then the handshake may fail if there are no default truststores established by the security provider.

  SSL clients using client-side authentication must specify both a keystore and a truststore. The certificate from the keystore is used for client authentication.

  ### CSIv2 Security Properties (ejb_sec.properties)

  If the client does not use client-side SSL authentication, you must set `client.sendpassword` in the `ejb_sec.properties` file for the client runtime to insert a security context and send the user name and password. You must also set`server.trustedhosts` to include your server.

  Note: Server-side authentication takes precedence over a user name and password.

  If the client does use client-side SSL authentication, the server extracts the `DistinguishedName` from the client's certificate and then looks it up in the corresponding user manager. It does not perform password authentication.

  #### Trust Relationships

  Two types of trust relationships exist:

  - Clients trusting servers to transmit user names and passwords using non-SSL connections

  - Servers trusting clients to send identity assertions, which delegate an originating client's identity

  Clients list trusted servers in the EJB property `oc4j.iiop.trustedServers`. See Table 6-4, "EJB Client Security Properties" for details. Servers list trusted clients in the `trusted-client` property of the `<sep-property>` element in `internal-settings.xml`. See "EJB Server Security Properties (internal-settings.xml)" for details.

  Conformance level 0 of the EJB standard defines two ways of handling trust relationships:

  - presumed trust, in which the server presumes that the logical client is trustworthy, even if the logical client has not authenticated itself to the server, and even if the connection is not secure

  - authenticated trust, in which the target trusts the intermediate server, based on authentication either at the transport level, or in the `trusted-client` list, or both

    Note: You can also configure the server to both require SSL client-side authentication and also specify a list of trusted client (or intermediate) hosts that are allowed to insert identity assertions.

  OC4J offers both kinds of trust. You configure trust using the bean's <`ior-security-config>` element in `orion-ejb-jar.xml`. See "CSIv2 Security Properties (orion-ejb-jar.xml)" for details.

  ### CSIv2 Security Properties (orion-ejb-jar.xml)

  This section discusses the CSIv2 security properties for an EJB. You configure each individual bean's CSIv2 security policies in its `orion-ejb-jar.xml`. The CSIv2 security properties are specified within `<ior-security-config>` elements. Each element contains a `<transport-config>` element, an `<as-context>` element, and an `<sas-context>` element.

  #### The <transport-config> Element

  This element specifies the transport security level. Each element within `<transport-config>` must be set to `supported`, `required`, or `none`. `None` means that the bean neither supports nor uses that feature; `supports` means that the bean permits the client to use the feature; `required` means that the bean insists that the client use the feature. The elements are:

  - `<integrity>`: Is there a guarantee that all transmissions are received exactly as they were transmitted?

  - `<confidentiality>`: Is there a guarantee that no third party was able to read transmissions?

  - `<establish-trust-in-target>`: Does the server authenticate itself to the client?

  - `<establish-trust-in-client>`: Does the client authenticate itself to the server?

    Notes: If you set <`establish-trust-in-client>` to `required`, this overrides specifying `username_password` in `<as-context>`. If you do this, you must also set the `<required>` node value in the `<as-context>` section to `false`; otherwise, access permission issues will arise. Setting any of the `<transport-config>` properties to `required` means that the bean will use RMI/IIOP/SSL to communicate.

  #### The <as-context> element

  This element specifies the message-level authentication properties.

  - `<auth-method>`: must be set to either `username_password` or `none`. If set to `username_password`, beans use user names and passwords to authenticate the caller.

  - `<realm>`: must be set to `default` at the current release.

  - `<required>`: if set to `true`, the bean requires the caller to specify a user name and password.

  #### The <sas-context> element

  This element specifies the identity delegation properties. It has one element, `<caller-propagation>`, which can be set to `supported`, `required`, or `none`. If the `<caller-propagation>` element is set to `supported`, then this bean accepts delegated identities from intermediate servers. If it is set to `required`, then this bean requires all other beans to transmit delegated identities. If set to `none`, this bean does not support identity delegation.

  An example:

      <ior-security-config>
        <transport-config>
          <integrity>supported</integrity>
          <confidentiality>supported</confidentiality>
          <establish-trust-in-target>supported</establish-trust-in-target>
          <establish-trust-in-client>supported</establish-trust-in-client>
        </transport-config>
        <as-context>
          <auth-method>username_password</auth-method>
          <realm>default</realm>
          <required>true</required>
        </as-context>
        <sas-context>
          <caller-propagation>supported</caller-propagation>
        </sas-context>
      </ior-security-config>

  ##### DTD

  The DTD for the `<ior-security-config>` element is:

      <!ELEMENT ior-security-config (transport-config?, as-context?
      sas-context?) >
      <!ELEMENT transport-config (integrity, confidentiality,
      establish-trust-in-target, establish-trust-in-client) >
      <!ELEMENT as-context (auth-method, realm, required) >
      <!ELEMENT sas-context (caller-propagation) >
      <!ELEMENT integrity (#PCDATA) >
      <!ELEMENT confidentiality (#PCDATA)>
      <!ELEMENT establish-trust-in-target (#PCDATA) >
      <!ELEMENT establish-trust-in-client (#PCDATA) >
      <!ELEMENT auth-method (#PCDATA) >
      <!ELEMENT realm (#PCDATA) >
      <!ELEMENT required (#PCDATA)> <!-- Must be true or false -->
      <!ELEMENT caller-propagation (#PCDATA) >

  ### EJB Client Security Properties (ejb_sec.properties)

  Any client, whether running inside a server or not, has EJB security properties. Table 6-4 lists the EJB client security properties controlled by the `ejb_sec.properties` file. By default, OC4J searches for this file in the current directory when running as a client or in `J2EE_HOME/config` when running in the server. You can specify this file's location explicitly with `-Dejb_sec_properties_location=``pathname`.

  ##### Table 6-4 EJB Client Security Properties

  Property | Meaning
  --- | ---
  `# oc4j.iiop.keyStoreLoc` | The path name for the keystore.
  `# oc4j.iiop.keyStorePass` | The password for the keystore.
  `# oc4j.iiop.trustStoreLoc` | The path name for the truststore.
  `# oc4j.iiop.trustStorePass` | The password for the truststore.
  `# oc4j.iiop.enable.clientauth` | Whether the client supports client-side authentication. If this property is set to `true`, you must specify a keystore location and password.
  `oc4j.iiop.ciphersuites` | Which cipher suites are to be enabled. Here are the valid cipher suites: `TLS_RSA_WITH_RC4_128_MD5 SSL_RSA_WITH_RC4_128_MD5 TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA TLS_RSA_EXPORT_WITH_RC4_40_MD5 SSL_RSA_EXPORT_WITH_RC4_40_MD5 TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA`
  `nameservice.useSSL` | Whether to use SSL when making the initial connection to the server.
  `client.sendpassword` | Whether to send user name and password in clear form (unencrypted) in the service context when not using SSL. If this property is set to `true`, the user name and password are sent only to servers listed in the `trustedServer` list.
  `oc4j.iiop.trustedServers` | A list of servers that can be trusted to receive passwords sent in clear form. Has no effect if `client.sendpassword` is set to `false`. The list is comma-separated. Each entry in the list can be an IP address, a host name, a host name pattern (for instance,`*.example.com`), or `*`. An `*` alone means that all servers are trusted.

  Note: The properties marked with a # can be set either in `ejb_sec.properties` or as system properties. The settings in `ejb_sec.properties` always override settings that are specified as system properties.

  ### JNDI Properties for Interoperability (jndi.properties)

  The following RMI/IIOP properties are controlled by the client's `jndi.properties` file:

  - `java.naming.provider.url` may be an `OPMN` or a `corbaname` URL for the bean to be interoperable. For details on `corbaname` URLs, see "The corbaname URL". For details on the OPMN URL, see "The OPMN URL".

  - `contextFactory` can be either `ApplicationClientInitialContextFactory` or the class `IIOPInitialContextFactory`.

    If your application has an `application-client.xml`, then leave `contextFactory` set to `ApplicationClientInitialContextFactory`. `` If your application does not have an `application-client.xml`, then change `contextFactory` to `IIOPInitialContextFactory`.

  #### Context Factory Usage

  `com.evermind.server.ApplicationClientInitialContextFactory` is used when looking up remote objects from stand-alone application clients. It uses the `refs` and `ref-mappings` found in `application-client.xml` and `orion-application-client.xml`. It is the default initial context factory when the initial context is instantiated in a Java application.

  `com.oracle.iiop.server.IIOPInitialContextFactory` is used when looking up remote objects between different containers using the IIOP protocol.

| Copyright © 1996, 2003 Oracle Corporation. All Rights Reserved. |
| Home | Index