10
Interoperability and RMI Tunneling

This chapter describes OC4J support for cross-platform distributed EJB interoperation and for using RMI over HTTP (RMI tunneling).

This chapter covers the following topics:

• Introduction to EJB Interoperability

• Switching to Interoperable Transport

• Configuring OC4J for Interoperability

• Configuring RMI Tunneling

Introduction to EJB Interoperability

Version 2.0 of the Enterprise Java Beans 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. Redeployment details are discussed in "Simple Interoperability" .

EJB interoperability consists of the following:

• Transport interoperability through CORBA IIOP

• Naming interoperability through the CORBA CosNaming Service

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

• Transaction interoperability through the CORBA Transaction Service (OTS)

OC4J provides all these features.

Naming

OC4J supports the CORBA CosNaming service. OC4J can publish EJBHome object references in a CosNaming service. OC4J 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 CSIv2. CSIv2 specifies different conformance levels; OC4J complies with the EJB specification, which requires conformance level 0.

Transactions

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

• Transactionally interoperable--transactions are supported between beans hosted in different J2EE containers

• Transactionally non-interoperable--transactions are supported only among beans in the same container

This release of OC4J is transactionally non-interoperable. This means that when a transaction spans EJB containers, OC4J raises a specified exception.

Switching to Interoperable Transport

In OC4J, EJBs use RMI/ORMI, a proprietary protocol, to communicate. It is easy to convert an EJB to using RMI/IIOP; this makes it possible for EJBs to invoke one another across EJB containers.

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

Simple Interoperability

Follow these steps:

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

2. 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".

3. (Client only) Change the client's classpath to include the stub JAR file generated by OC4J. This will normally be

   application_deployment_directory/appname/ejb-module/module_iiopClient.jar 
   
   

   If you do not have access to the deployment directory, you can obtain the generated stub JAR file during deployment by running admin.jar with the -iiopClientJar switch

   Note: IIOP stub and tie class code generation happens at deployment time, unlike ORMI stub generation which happens 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.

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

5. Redeploy your application.

Advanced Interoperability

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

2. 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.

3. 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".

4. (Client only) Change the client's classpath to include the stub JAR file generated by OC4J. This will normally be

   application_deployment_directory/appname/module/module_iiopClient.jar 
   

   Note: IIOP stub and tie class code generation happens at deployment time, unlike ORMI stub generation which happens 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 describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.

6. Redeploy your application.

The corbaname URL

In order 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 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 is discussed in section 13.6.10.1 of the CORBA specification.

The most common form of the corbaname URL scheme is:

corbaname::host[:port]

This specifies a conventional DNS hostname 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 a stringified NamingContext. 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 rmic.jar Compiler

In order to invoke or be invoked by CORBA objects, RMI objects must have corresponding stubs, skeletons, and IDL. The rmic.jar compiler can used to generate stubs and skeletons from Java classes or to generate IDL. The generated IDL can be used to generate non-Java stubs and skeletons using any CORBA IDL compiler.

java -jar rmic.jar options classname ...

The rmic.jar compiler takes the following options:

• -always (same as -alwaysgenerate)--Forces the compiler to generate new outputs even when the existing stubs, ties, or IDL are newer than the input class. Requires the -iiop or -idl flags.

• -classpath classpath--Specifies the directories to search for the classes.

• -d pathname-- Specifies output directory for generated class files.

• -g--Generates debugging information.

• -idl--Generates IDL for all classes in the input, as well as any classes they reference. IDL, the Interface Description Language, is Corba's mechanism for describing methods and data in a language-independent way.

  Note: The rmic.jar compiler generates IDL that uses the CORBA 2.3 extensions to IDL; compilers that do not support these extensions cannot compile rmic-generated IDL.

• -idlModule <fromJavaPackage<.class>> <toIDLModule>--Specifies IDLEntity package mapping. An example:

  -idlModule foo.bar my::real::idlmod 
  

• -idlFile <fromJavaPackage<.class>> <toIDLFile>--Specifies IDLEntity file mapping. An example:

  -idlFile test.pkg.X TEST16.idl
  

• -iiop--Generates IIOP stubs and ties. Stub classes are called by clients to transmit RMI messages over IIOP; tie classes are called by the server to process incoming calls and dispatch them to the implementation class. Each remote interface has a stub; each server implementation class has a tie. Stub classes are also generated for abstract interfaces. An abstract interface does not extend java.rmi.Remote; in addition, it either has no methods or all of its methods throw java.rmi.RemoteException or one of its superclasses.

• -keep (same as -keepgenerated)--Preserves intermediate generated source files; by default, these are deleted.

• -nolocalstubs --Does not create stubs optimized to run in the same process as the server. Requires -iiop.

• -nowarn--Turns off all compiler warnings.

• -noValueMethods--Stops generation of IDL for methods and constructors within IDL valuetypes. Requires -idl.

• -v1.1--Creates stubs and skeletons for 1.1 stub protocol version only. By default. rmic generates stubs and skeletons compatible with both 1.1 and 1.2.

• -v1.2--Creates stubs and skeletons for 1.2 stub protocol version only. By default. rmic generates stubs and skeletons compatible with both 1.1 and 1.2.

• -vcompat (default)--Creates stubs/skeletons compatible with both 1.1 and 1.2 stub protocol versions.

• -verbose--Sends messages about compiler status to stdout.

Exception Mapping

When EJBs are invoked over IIOP, OC4J must map system exceptions to CORBA exceptions. Table 10-1, "Java-CORBA Exception Mappings" lists the exception mappings.

Table 10-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 in order to invoke OC4J-hosted EJBs. OC4J expects the other container to make HandleDelegate object available in the JNDI namespace 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 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

The following files contain entries that specify interoperability information.

Server-wide Files

• server.xml

  The <sep-config> element in this file specifies the pathname, normally internal-settings.xml, for the server extension provider properties.

  <sep-config path="internal-settings.xml">
  
  

• internal-settings.xml

  Specifies server extension provider properties specific to RMI/IIOP. See "EJB Server Security Properties (internal-settings.xml)" for details.

Application-specific Files

• orion-ejb-jar.xml

  (Server) The <ior-security-config> sub-entity of the <session-deployment> and <entity-deployment> entities specifies Common Secure Interoperability Version 2 (CSIv2) security properties. See "CSIv2 Security Properties" for details.

• ejb_sec.properties

  (Client) Specifies client-side security properties for an EJB. See "EJB Client Security Properties (ejb_sec.properties)" for details.

• jndi.properties

  (Client) Specifies the URL of the initial naming context. See "JNDI Properties for Interoperability (jndi.properties)" for details.

EJB Server Security Properties (internal-settings.xml)

You specify server security properties in internal-settings.xml.

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

This file specifies the following properties as values within <sep-property> entities. Table 10-2, "EJB Server Security Properties" contains a list of properties.

Table 10-2 EJB Server Security Properties

Property	Meaning
port	IIOP port number (defaults to 4444)
ssl	true if IIOP/SSL is supported, false otherwise
ssl-port	IIOP/SSL port number (defaults to 4445) This port is used for server-side authentication only. If your application uses client and server authentication, 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 hostname, a hostname pattern (for instance, *.example.com), or *; * 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 only be set if ssl is true)

The keystore and truststore files use JDK-specified formats 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).

A typical internal-settings.xml looks like:

<server-extension-provider name="IIOP" 
   class="com.oracle.iiop.server.IIOPServerExtensionProvider"> 
  <sep-property name="port" value="4444" /> 
  <sep-property name="host" value="localhost" /> 
  <sep-property name="trusted-clients" value="*.example.com" />
  <sep-property name="ssl" value="true" /> 
  <sep-property name="ssl-port" value="4445" /> 
  <sep-property name="keystore" value="keystore1" /> 
  <sep-property name="keystore-password" value="changeit" /> 
</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

Common Secure Interoperability version 2 (CSIv2) is an 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

These configuration files are discussed in "CSIv2 Security Properties (internal-settings.xml)", "CSIv2 Security Properties (orion-ejb-jar.xml)", and "EJB Client Security Properties (ejb_sec.properties)".

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)" .

In order 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 may specify:

• Truststore only

• Both keystore and truststore.

• Neither

If you specify neither keystore nor truststore, 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 in order for the client runtime to insert a security context and send the username and password. You must also set server.trustedhosts to include your server.

Note: Server-side authentication takes precedence over a username 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

There are two types of trust relationships:

• Clients trusting servers to transmit usernames 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 10-3, "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 to also specify a list of trusted client (or intermediate) hosts who are allowed to insert identity assertions.

OC4J provides 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; requires 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>. 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 will use user names and passwords to authenticate the caller.

• <realm>--Must be set to default at this release.

• <required>--If set to true, the bean requires the caller to specify a username 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. The following are 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 10-3 lists the properties controlled by the ejb_sec.properties file.

Table 10-3 EJB Client Security Properties

Property	Meaning
# oc4j.iiop.keyStoreLoc	The pathname for the keystore.
# oc4j.iiop.keyStorePass	The password for the keystore.
# oc4j.iiop.trustStoreLoc	The pathname 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. The valid cipher suites are: 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 username and password in clear (unencrypted) in the service context when not using SSL. If this property is set to true, the username 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. 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 hostname, a hostname pattern (for instance, *.example.com), or *; * 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 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 must be a corbaname URL in order for the bean to be interoperable. For details on corbaname URLs, see "The corbaname URL".

• contextFactory can now be either ApplicationClientInitialContextFactory or the new class IIOPInitialContextFactory.

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

Configuring RMI Tunneling

When EJBs must communicate across firewalls they can use tunneling to transmit RMI across HTTP. This tunneling is supported only with RMI/ORMI; you cannot do HTTP tunneling with RMI/IIOP.

To configure OC4J to support RMI tunneling, do the following:

1. Modify the JNDI provider URL. The JNDI provider URL for accessing the OC4J EJB server takes the form:

   ormi://hostname:ormi_port/the_app
   

   You should change the URL to:

   http:ormi://hostname:HTTP_PORT/the_app
   

   Note: If omitted, HTTP_PORT defaults to 80. The argument port number is your HTTP port, not your ORMI port.

2. If your HTTP traffic goes through a proxy server, you must specify the proxyHost and (optionally) proxyPort in the command line when starting the EJB client. If you do not supply a value for proxyPort, it defaults to 80.

   -Dhttp.proxyHost=proxy_host -Dhttp.proxyPort=proxy_port
   

Configuring RMI in server.xml and rmi.xml

In order to use RMI from OC4J, you must edit the server.xml and rmi.xml files.

Editing server.xml

Your server.xml file must specify the pathname of the RMI configuration file in the <rmi-config> element. The syntax is:

<rmi-config path="RMI_PATH" /> 

The usual RMI_PATH is ./rmi.xml; you can name the file whatever you like.

Editing rmi.xml

The file rmi.xml must specify which host, port, and username/password will be used to connect to (and accept connections from) remote RMI servers. Your file must contain an <rmi-server> element describing possible connections. An <rmi-server> element looks like:

<rmi-server host="hostname" port="port"> 
<server host="hostname" username="username" port="port" 
  password="password" http-path="pathname"/> 
<log> 
  <file path="logfilepathname" /> Okay
</log> 
</rmi-server> 

<rmi-server> has the following attributes:

hostname

is the host or IP name from which your server will accept RMI requests. hostname can be a particular hostname or "[ALL]". If you specify a hostname, the OC4J server will only accept RMI requests from that particular host. If hostname is "[ALL]" or you omit the host attribute, the OC4J server will accept RMI requests from any host.

port

is the port number on which your server listens for RMI requests. If you omit this attribute, it defaults to 23791.

An <rmi-server> element can contain zero or multiple <server> elements and zero or one <log> elements.

Each <server> element specifies a server that your application can contact over RMI. A <server> element takes the form:

<server host="hostname" username="username" port="port" 
  password="password"/> 

The host attribute is required; the remaining attributes are optional.

hostname

the name or IP address of the server you will contact over RMI.

username

the username of a valid principal on the remote server

port

the port number on which the remote server listens for RMI requests

password

the password used by the principal username

The <log> element contains the pathname of a log file to which the server will write all RMI requests.