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.