The Community OpenORB - SSL

Chris Wood

Jerome Daniel

Michael Rumpf

Table of Contents

How to get involved
Technical Writer
1. Overview
2. Compilation
3. Installing
4. Configuration
5. Deployment
6. Frequently Asked Questions
A. Appendix

List of Tables

1. Release History



The Community OpenORB has its roots in the Distributed Object Group's JavaORB, a pure-Java, open-source CORBA ORB.

The JavaORB project was initiated by Jerome Daniel in October 1998. Only six months later, in April 1999, version 1.0 was released. In the same month he founded the Distributed Object Group (DOG) together with Xavier Blanc, Nicolas Charpentier, and Vincent Vallee. In May 1999 negotiations with ExOffice Technologies, Inc., about a strategic partnership started for cooperatively developing new versions of the JavaORB project. In July 1999 version 2.0 of the JavaORB was released. During the following months several CORBA services and various enhancements to the JavaORB's core were added. In February 2000 Olivier Modica joined the DOG team and until May 2000 the whole DOG became part of ExOffice Technologies, Inc., Around the same time Chris Wood, an employee aith ExOffice Technologies, Inc., joined the team. In June 2000 the company ExOffice Technologies, Inc., was renamed to Intalio, Inc., In July 2000 the DOG at Intalio, Inc., was extended by another member, Marina Daniel. [1]. The whole team was working on a new version of the JavaORB which was later renamed to OpenORB. After several months of in-house development OpenORB was released at

Table 1. Release History [2]

VersionRelease Date
1.0.0February 5th 2001
1.0.1March 9th 2001
1.1.0May 8th 2001
1.2.0August 15th 2001
After nine months the OpenORB project had proven to be successful. Public visibility was increasing steadily and the community had grown to a respectable size.

Then the bubble bursted and many companies, incl. Intalio, Inc., had to focus on their core business, in order to survive. It became obvious to the community that the project is going to drown with the bubble as the traffic on the mailing list was fading steadily. That was the time when a few OpenORB community members decided to get more involved into the project. The movement was led by Steve McConnell and Michael Rumpf. The problem was trying to get Intalio to turn the OpenORB project into a real, i.e. community driven, open-source project after the example of many Apache projects. Unfortunately the strategy of getting Intalio into the boat was not successful. The consequence was a fork of the OpenORB project at SourceForge the Community OpenORB. The new project was founded by Steve McConnell, Michael Rumpf, Shawn Boyce, Jesper Pedersen, J. Scott Evans, and Viacheslav Tararin on January 8th 2002.

Soon after the formation of the Community OpenORB project version 1.2.1 of the OpenORB suite was released on January 11th 2002. This version included many bug-fixes over the Intalio source base that had been released on August 15th 2001 for the last time.

On June 8th 2002, Ashish Agrawal, VP. of Engineering at Intalio, Inc., send a mail to the open-source communities of the various projects that had been sponsored by Intalio over the past [3]. The part about OpenORB was: "We support the project on Sourceforge and recommend any contributors to contribute to this project. OpenORB will no longer be hosted on Exolab."

Since the beginning of the Community OpenORB project substantial changes have been made to the source base. Since early 2002 the circle of active developers grew to over 10, not including the people contributing patches eventually. The number of users, subscribed to the openorb-user mailing-list, grew to over 100, the downloads have passed 15.000. On September 30th version 1.3.0 was released to the community.


We are working to make OpenORB a part of the Apache project. We have already adopted the Apache community rules [4] and we are just waiting for the current copyright holder, Intalio, Inc., to donate the source base to the Apache Foundation. Once the politics are completed we will move the project over to the Apache facilities making OpenORB a full member of the Apache Software community.

Independently of these efforts we are trying to make OpenORB the best open-source CORBA ORB around. In order to achieve this goal we need your help. Either if you are a user, a technical writer, or a developer we will appreciate any help.

As a user you could help by answering other users's questions, by proposing new features, or by submitting bug reports.

Open-source projects often lack high quality documentation. New users depend on good documentation and it definitely helps to reduce the traffic on the user mailing-list. So if you are good at writing documentation you are extremely welcome to join the team.

As a developer you can help by doing the usual things: fix bugs, add new features, write test-cases, improve the build-system, or any other task of which you think should be improved.

This leads to the question: "How do I get involved?"

How to get involved


Although we are permanently trying to improve the documentation you may have problems using OpenORB. In these cases you should follow the steps below:

  • Read this documentation and any related documentation carefully.

  • Search this module's FAQ and any related FAQs for answers to your questions.

  • Search the openorb-user mailing list archive

  • If your question is more of a general CORBA question, then you should also search the following newsgroup archives for answers: comp.object.corba, .

  • If your problem can't be solved by any of the steps above, then send a question to the openorb-users mailing-list. For spam protection the mailing-list has been restricted to subscribed members only. Therefore you need to subscribe to the mailing-list before you can send your question. In order to receive qualified responses it is important that your submission also passes a certain level of quality, i.e. include information like OS version, JDK version, OpenORB module version, exception stack traces, or any other information that might be useful to analyze the problem.

As an OpenORB user you are invited to share your knowledge with other community members when they are having problems. When you know the answer to another user's question feel free to respond to it. Doing so will help the developers, working on new features or fixing bugs, to concentrate on these tasks. A vital community is a fundametal requirement for OpenORB becoming an Apache project.

Technical Writer

As a technical writer you should be subscribed to the most important mailing lists: openorb-users and openorb-devel. The questions sent to the openorb-users mailing-list are a good indicator of which part of the documentation needs to be improved. The openorb-devel list is for internal development of the OpenORB modules and thus any discussion about writing documentation for OpenORB should go here.

Documentation for the OpenORB modules is divided into two major parts, the docbook documentation and the Javadoc documentation. The docbook documentation is created from XML files adhering to the docbook-xml standard [5]. The second part is the Javadoc documentation that is used for internal and external API documentation. Writing documentation includes fixing or writing Javadoc comments, extending the docbook manual, and adding FAQ items.


As a developer you should be subscribed to both mailing lists: openorb-users and openorb-devel. Any proposal for a new feature should be sent to the openorb-devel mailing list and will be discussed by the members of these lists . As a developer you should know what the user thinks of a certain feature and therefore subscription to the openorb-user mailing list is substantial. Another mailing-list that might be of interest to a developer is the openorb-commits mailing-list. The CVS server is sending the diffs of each cvs commit to this mailing-list. These notification mails keep you informed about what is going on and it supports improving code quality because other members of the list can instantly review any patch that is committed to the CVS tree.

[5] Currently only HTML documentation is created from the XML source files. The PDF generation has recently been disabled because the current Apache FOP implementations, both stable and dev, are having problems with the latest version of the docbook-xml and docbook-xsl combination.

Chapter 1. Overview

This document provides installation and use instructions for the SSLIOP module for OpenORB.

The SSLIOP extension for OpenORB provides transport layer security for transmitted requests. It is a fully compliant implementation of the SSLIOP OMG specification.

The extension provides encryption of CORBA requests and responses, protection from the contents of messages being modified from a third party, and authentication of clients and servers.

Enabling security is completely transparent to a preexisting application, it is also possible to phase in secure communications by allowing incoming requests which are unsecured.

Understanding the security offered by SSLIOP SSLIOP relies on SSL to provide three facets of security

  • integrity protection, to provide protection against the contents of a message being modified.
  • encryption, providing protection against the content of a message being viewed.
  • authentication, ensuring that one or both of the parties involved are who they claim to be.

All three facets need not be provided at the same time. For example, authentication may be limited to one party (normally the server) or authentication may be provided, but without encryption.

It is always necessary to authenticate at least one end of the connection to avoid a man in the middle attack. If this is not the case, any malicious attacker can masquerade as a legitimate user: The malicious attacker intercepts connection requests and sets up two secured, unauthenticated connections between itself and the two intended endpoints. With these connections in place the malicious attacker can intercept and corrupt any of the data that he relays between the two legitimate users.

There is the option of disabling authentication at both ends, however it is strongly recommended not to do this. Options are available to authenticate only the server, or both the server and the client. Currently it is not possible to authenticate only the client, although if requested we could provide this possibility.

To provide authentication it is necessary to construct a public and private key pair, which is also authenticated against a well known public key of some organization, known as a certifying authority (ca). For information about construction and authentication of keys see the documentation for the keytool application, provided by your JDK.

Encryption is required where the data being transmitted is sensitive to eavesdropping, for example credit card data. In some cases all that is required is integrity protection, preventing an attacker from modifying the data while it is in transmission. The computational overhead required is thus greatly reduced.

Chapter 2. Compilation

To compile and use OpenORB SSL you have to previously install and configure a SSL implementation in Java such as JSSE. For example, consult the Java Sun Web Site ( ) to get more information about JSSE.

It is assumed that OpenORB is previously installed on your system. The OpenORB ( openorb-{version}.jar ) and Tool ( openorb_tools-{version}.jar ) jar files must be added into your classpath.

Then, to build OpenORB SSLIOP :

  • set the JAVA_HOME env variable

  • start 'build.bat' ( for Windows ) or '' ( for Unix )

OpenORB SSL is then built. The openorb_ssl-{version}.jar file is created in the 'dist' directory ( itself created by the build process ).

The SSLIOP distribution contains an Ant script that can be used to build it. If you use the build.bat ( for windows ) or ( for Unix ) all dependences and required classpath are directly included.

Thus, to compile SSLIOP for OpenORB, we advise you to enter the following command from the command line : build or

Chapter 3. Installing

This chapter explains how to install SSLIOP for OpenORB.

How to get SSLIOP for OpenORB ?

To get this OpenORB extension, please visit the Community OpenORB web site ( ). Then, go to the download section. Follow the instructions to download the SSLIOP extension.

SSLIOP dependencies.

The SSLIOP module must have a correctly installed OpenORB distribution to allow it to be used. It also requires an implementation of JSSE, a standard implementation of SSL for java as standardized by sun. Currently only the Sun reference implementation is available, it can be retrieved from the Sun website

Please refer to your JSSE documentation for information on installation and configuration of keystore locations and passwords. The sun reference implementation of JSSE uses system properties to specify keystore locations and passwords. In general this is not secure from interception by malicious code. If untrusted code is to be run, see the section on advanced configuration.

Chapter 4. Configuration

How to configure SSLIOP for OpenORB

The first step in using SSLIOP is to add the openorb_ssl-x.y.z.jar file to your classpath.

If JSSE was configured so that the keystore location and password have been specified, or for a simple client-only application, where the server does not require client authentication, configuration of the SSLIOP module can be performed simply by adding the following line to the active profile of the user's master configuration file:

<import xlink:href="${openorb.home}config/SSLIOP.xml" />

This will rely on the JSSE implementation for all configuration, using its defaults. If the JSSE implementation is configured with a keystore location and password all requirements for secure operation will be satisfied, both at the server and client end. This configuration provides encrypted and integrity protected messaging, and authentication of servers.

If the JSSE implementation is configured using unprotected system properties any thread running in the same VM will be able to access the keystore location and password. For this reason this configuration does not provide any protection from untrusted code, which may use these properties to gain access to sensitive key information. Without providing a keystore and password to the JSSE implementation only client to server requests can be performed, and clients will not be authenticated. This may be reasonable a behavior in many cases.

A persistent server requires a constant port number to be used when it executes. To set a constant port number for ssl incoming connections use the following config fragment:

<import xlink:href="${openorb.home}config/SSLIOP.xml#SSLIOP">
		<property name="port" value="684" />

Allowing unsecured requests and corbaloc: references.

By default whenever SSLIOP, or any other security mechanism, is activated any requests which do not use a secure mechanism will be rejected with NO_PERMISSION exceptions on both the server and client side. This default behaviour is designed to prevent any accedental transmission of sensitive data for clients, and to ensure protection for servers.

This protection can be disabled by using the following config file fragment:

<import xlink:href="${openorb.home}config/SSLIOP.xml#security">
		<property name="server.allowUnsecure" value="true" />
	<property name="client.allowUnsecure" value="true" />

This same mechanism is shared across all security mechanisms. At the moment finer grain access over what is rejected and what is accepted is not possible.

One case where it is necessary to disable security is when using the initial references service and corbaloc: style string references. This is because IIOP is the only defined protocol for resolving initial references; IIOP is unsecured it will not be allowed. By default OpenORB uses a corbaloc: address to resolve the name service, if the name service is started with SSLIOP enabled and it's IOR is used in the following configuration fragment then this can be avoided:

<import xlink:href="${openorb.home}config/OpenORB.xml#InitRef">
			<property name="NameService" value="IOR:..." />

Encryption type settings

All the SSLIOP specific configuration properties have 'support' and 'require' variants for both for clients and servers. This allows flexible setting of security facets for both clients and servers, for example a server which supports, but does not require, data encryption can be contacted by clients both with and without encryption in effect. Note that if both endpoints support but do not require a particular facet then the facet will be used.

In some situations, the extra overhead involved in encrypting all transferred data is in excess of what is required. It may be reasonable to authenticate the participants in the connection and transmit integrity protected data, this prevents data from being modified in transit but does not protect it's contents being viewed by eavesdroppers. Using the following import statement achieves this goal:

<import xlink:href="${openorb.home}config/SSLIOP.xml#SSLIOP">
		<property name="server.encrypt.require" value="false" />
		<property name="" value="false" />

This disables support on the client side for encrypted communication, and allows connections on the server side to use protocol suites which are unencrypted. It is still possible to instantiate an encrypted channel to the server side, however the client side will always initiate unencrypted channels.

By default, only the server in a connection is required to authenticate itself. The client can remain unauthenticated. To require authentication of the client by the server the following configuration fragment can be used:

<import xlink:href="${openorb.home}config/SSLIOP.xml#SSLIOP">
		<property name="server.authClient" value="true" />

The client will then require a certificate trusted by the server in order to connect. With client authentication enabled, and with all other requirements for bidirectional IIOP satisfied then bidirectional SSLIOP will be enabled. To require client authentication, but disable bidirectional access use:

<import xlink:href="${openorb.home}config/SSLIOP.xml#SSLIOP">
	  <property name="server.authClient" value="true" />
	  <property name="server.allowBiDir" value="false" />

It is possible to disable authentication altogether for both clients and servers leaving only encryption, however this should not normally be done since unauthenticated communication is then subject to man in the middle attack:

<import xlink:href="${openorb.home}config/SSLIOP.xml#SSLIOP">
	  <property name="" value="false" />

Setting up the context.

When the code being run in the same virtual machine is potentially untrusted, extra measures must be taken to ensure access is not granted to sensitive private key information. Sun's JSSE reference implementation relies on setting system properties, which if unprotected can be intercepted by malicious code and used to steal sensitive private key information. To avoid this the IOPSSL package provides a password entry dialog box option, and a replaceable class providing the dialog boxes.

To activate the dialog box for keystore location and password entry use the following config fragment:

      <import xlink:href="${openorb.home}config/SSLIOP.xml#SSLIOP">
	  <property name="context.useDefault" value="false" />
      <property name="context.keyStore.URL" 
      value="${user.home}.keystore" >
	  <property name="context.keyStore.prompt" value="password" >

The first property, SSLIOP.context.useDefault=false, disables the use of the default ssl socket factories. Not using the default contexts may not be possible when using a non-sun JSSE implementation. The second property, SSLIOP.keyStore.URL, gives a URL for the keystore. The value given here will pick up the default keystore created by the keytool utility from your JDK.

The third property, SSLIOP.keyStore.prompt=password, results in a dialog box being activated to request a password. Prompting for a password is the only secure method for retrieving a password. Other options available for this field are "default" where the JSSE defaults are used, "prompt" where the location of both the keystore and its password are prompted for, and "noprompt" where the properties are used directly. When using the "noprompt" option the property SSLIOP.keyStore.password is available for setting the password, however this is not secure from malicious code which has access to the orb.

In some applications it may be required that an alternative trust store is used to the default. The default trust store, provided with all jdk installations, trusts users who have certificates registered with one of the global CAs. For some applications only specific groups of users should be granted access. In these situatations an application specific trust store can be created, and it's location specified: To activate the dialog box for keystore location and password entry use the following config fragment:

      <import xlink:href="${openorb.home}config/SSLIOP.xml#SSLIOP">
	  <property name="context.useDefault" value="false" />
	  <property name="context.trustStore.URL" value="a secure URL" />

It should be noted that the URL used to locate the trust store should be secure from attack, an https URL is useful for remote locations, while a local file URL can be used locally.

Parts or all of this mechanism can be replaced, several protected functions are available from the org.openorb.SSLIOP.SSLContextFinder class, to use them create a subclass and modify the SSLIOP.SSLContextFinderClass property to locate the replacement. For more details see the class's api documentation.

Chapter 5. Deployment

To test SSLIOP simply run any application you would normally run. Running the ORB with the -ORBDebug=2 flag will display information about what protocols were used and when connections go up and down.

How to freeze the configuration ?

When you developed an application that uses SSL, you'll probably customized some parameters to fullfil your needs. After this customization, it's possible to replace the default configuration embedded within the SSL Jar file by your own configuration file. This section explains how to do that.

To freeze the configuration, we are going to replace the embedded configuration by the new one. The way to do that depends on the distribution that you are currently using : source code or pre built distribution. The following paragraphs describes how to proceed for each distribution kind.

Source code distribution In that case, a Ant target is provided to replace the embedded configuration file. From the command line : build config


The new configuration file must be available in the src/config directory. Moreover, the Jar file where the configuration will be output must be available in the dist directory.

Pre built distribution: In that case, the config directory contains a script named setConfig ( setConfig.bat for Windows and for Unix ). We have just to start this script to replace the embedded configuration file.


The new configuration file must be available in the config directory. Moreover, the Jar file where the configuration will be output must be available in the lib directory.

Chapter 6. Frequently Asked Questions

6.1. I have several users in my organization who I want to allow access to my server, but noone from outside. How can i set this up?
6.2. The key store location is set so that each user has the keystore sourced from their local directory. The trust store URL should be a secure location, a file, resource or https url will work.

I have several users in my organization who I want to allow access to my server, but noone from outside. How can i set this up?

Use the following profile in your enterprise wide configuration file:

        <profile name="name">
        <import xlink:href="${openorb.home}config/SSLIOP.xml#SSLIOP">
        <property name="server.authClient" value="true" />
  		<property name="context.useDefault" value="false" />
	  	<property name="context.keyStore.URL" value="${user.home}.keystore" />
		<property name="context.keyStore.prompt" value="password" />
	  	<property name="context.trustStore.URL" value="location" />


The key store location is set so that each user has the keystore sourced from their local directory. The trust store URL should be a secure location, a file, resource or https url will work.

There are two choices for how to proceed once this has been done. The first choice is to simply store self-signed certificates in the trust store from each of the users. This has the advantage of simplicity, however does require centralization of the keystore to ensure it is always kept up to date.

The second choice is to create a organization wide certification authority (CA). This can be done using software available in the public domain, openssl for example can be used. Each of the users creates a private key and has the corresponding public key signed by the CA. The truststore must then only contain the certificate of the CA, all of the certificates signed by the CA, those of the users, will then be trusted. Since this trust store is static it can be copied to local storage without need to search for updates.

A variation of the second option is to have your CA's certificate signed by a root CA, each jdk ships with a number of certificates of root CAs, if your CA's certificate is signed by one of these then the default trust store can be used. The disadvantage of this is it allows users outside of your organization access to your protected data.

Appendix A. Appendix