ORBAsec SL3 and its (future) Components --------------------------------------- This directory contains a number of directories that compose the ORBAsec SL3 product line. (Currently, there is only one component, the base system, "sl3"). Each directory contains the IDL, Source Code, Demonstration, and Test programs for a component of the ORBAsec SL3 distribution. The "sl3" directory is Adiron's implementation of the OMG CORBA Common Secure Interoperability (CSI) protocol, which is referred to as CSIv2 (i.e. Version 2). This document can be found at http://www.omg.org/technology/documents/formal/omg_security.htm#CSIv2 ORBAsec SL3 also implements the Authorization Token Layer Acquisition Service (ATLAS) part of the CSIv2 protocol. This document is available at http://www.omg.org/technology/documents/formal/atlas.htm. ORBAsec SL3 is implemented as a "plug-in" for Adiron's AdironORB and IONA's ORBacus for Java. ORBAsec SL3 replaces the insecure TCP/IP transport protocol and IIOP message protocol in these ORBs. You must acquire the software and license of either AdironORB from Adiron's website at http://www.adiron.com, or ORBacus for Java from IONA's website at http://www.orbacus.com before you can build and use ORBAsec SL3. For using TLS/SSL, you also need IAIK-JCE 3.0 and IAIK-iSaSiLk 3.0 products, which you must get from IAIK's website, http://jce.iaik.tugraz.at. On the other hand, for using Kerberos, you need Wedgetail's JCSI Kerberos, which you must get from Wedgetail's website, http://www.wedgetail.com/jcsi. Also, to build ORBAsec SL3, we have made the transition from the MAKE and NMAKE utilities and have moved to Ant, from the Apache Software Foundaion. This provides us better portability between the various UNIX platforms and Microsoft Windows. You must go to the Apache Ant website, http://ant.apache.org, and obtain their code and license. Files of Interest ----------------- INTRO.txt This file. RELEASE.txt Release Notes pertaining to anomalies with using ORBAsec SL3. BUILD.txt Software requirements and build instructions. INSTALL.txt Instructions for installing and configuring J2SE. CHANGES.txt A concise log of changes/bug fixes from previous versions. LICENSE.txt The license agreement for using ORBAsec SL3. You agree to all provisions of this LICENSE. Understanding ORBAsec SL3 ------------------------- To understand ORBAsec SL3, one must understand security at the transport layer, such as the use of SSL (or TLS as it is now called), and the way it is enabled, such as the use of X.509 Certificates and Encrypted Private Keys, a.k.a. understanding a Public Key Infrastructure (PKI). Knowledge of the Java JCE is helpful. CSIv2 is based on Service Contexts ---------------------------------- Also, one must understand the use of "Service Contexts" in CORBA. CORBA is implemented with a message protocol called GIOP. CSIv2 Security information travels along with GIOP Request/Reply message pairs in the GIOP "service context". The use of GIOP "Service Contexts" is the way in which CSIv2 specified and implemented. The CSIv2 protocol is specified by the OMG Common Security Interoperability Version 2 (CSIv2) specification, which has become a chapter in the CORBA/IIOP Specification since version 2.6. CSIv1 and CSIv2 --------------- CORBA Interoperable Security (do not confuse it with the CORBA Security Level 1 and 2 API) is divided into two parts, the older Version 1 (CSIv1) and the newer Version 2 (CSIv2). CSIv1 handled authentication and message protection down at the transport layer. It had specifications of SECIOP (Kerberos, Sesame, SPKM) and SSL. Only, Adiron, implemented SECIOP (Kerberos) along with SSL. Other vendors made attempts at delivering an SSL based solution. CSIv2 specifies the use of SSL (which is now called TLS) as the primary transport security layer. CSIv2 is also works over plain unprotected TCP/IP for those "trusted" environments, where the overhead and protection of a transport security mechanism, such as TLS, is not warranted. ORBAsec SL3 APIs for CSIv1 and CSIv2 ------------------------------------ ORBAsec SL3 implements the transport security mechanisms of CSIv1 and the security context mechanisms of CSIv2. CSIv2 uses the transport security mechanisms of CSIv1 and adds some security context information at the GIOP Request/Reply level (i.e. over the transport). This distinction is important. For ORBAsec SL3, it divides CORBA security into two distinct APIs, one for Transport Security, and another for CSIv2 Security. ORBAsec SL3 calls these APIs: module TransportSecurity For use of security mechanisms available at the transport layer. module SecurityLevel3 For the use of CSIv2 Security Contexts. Both these APIs are modeled after the "Principal Calculus" from a paper by Martin Abadi, Butler Lampson, et al, called "A calculus for access control in distributed systems", ACM Transactions on Programming Languages and Systems, Sept 1993. This calculus gives ORBAsec SL3 security a mathematical foundation, which is highly important when reasoning about security, e.g. making access control decisions. These Principals are found in the module SecurityLevel3 and have a base valuetype of "Principal". Currently, ORBAsec SL3 implements the following from the OMG CSIv2 RFP response and the current CSIv2-Finalization Task Force (CSIv2-FTF): CSIv1 - Level 0, message protection without impersonation/delegation. Security Mechanism: TLS/SSL CSIv2 - Level 0 Transport Security Mechanism: TLS/SSL Client Authentication using a user defined Username/Password scheme. Identity Assertion This capability allows a client "quote" somebody else during an invocation. ORBAsec SL3 is currently implemented with a Adiron proprietary API (CORBA repository prefix of "adiron.com"). The previous version of CORBA's standard Security Level 2 is deemed, by Adiron, to be insufficient to support CSIv2, and in most cases was found insufficient to handle even CSIv1. Therefore, Adiron has embarked on a new API based on a mathematical foundation of security, in which it hopes its customers will embrace. Building and Installing ORBAsec SL3 ----------------------------------- Please see the "BUILD.txt" and "INSTALL.txt" files for building and installing instructions. Demonstrations and Tests ------------------------ In the "demo" directory there are numerous demonstrations of Clients, Servers, and "relay" Servers to illustrate the various points about ORBAsec SL3. Such points are: o The API to create CSIv1 credentials (i.e. TransportSecurity). o The API to create CSIv2 credentials (i.e. SecurityLevel3). - Create Quoting Credentials. - Create Credentials that use a Username/Password Scheme. - In a web server, extract the certificates from an HTTPS connection, and make Quoting Credentials from them. Please see the "demo/README" file for further information. In the "test" directory there are several regression tests. You may use either "ant run-test" or "./run-test" in each subdirectory to run these tests automatically. You will need "/bin/tcsh" if you use the "./run-test" command. The test directories also show some features that might be interesting to the programmer. However, most of the tests exercise points made by the demonstration programs. Please see the "test/README" file for further information. Programming with ORBAsec SL3 and AdironORB ------------------------------------------ The first thing you need to do to get started with ORBAsec SL3 with AdironORB is to initialize the ORB with ORBAsec SL3's initializers. There are two different ways to initialize the ORB with ORBAsec SL3, one if your application is going to be pure client, and the other if your application is going to be a server. This means without bringing up the Root POA (Portable Object Adapter) and one if you are going to be a server, i.e. reference the Root POA. Client initialization is performed as follows: java.util.Properties props = System.getProperties(); props.put("org.omg.CORBA.ORBClass", "com.adiron.orb.core.ORB"); props.put("org.omg.CORBA.ORBSingletonClass", "com.adiron.orb.core.ORBSingleton"); props.put("org.adiron.orb.server.enable","false"); props.put("org.adiron.orb.ORBInitializerClass", "com.adiron.orbasec.sl3.AdironORBInitializer"); props.put("org.omg.PortableInterceptor.ORBInitializerClass." + "com.adiron.orbasec.sl3.SL3Initializer_AdironORB", ""); org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init(args, props); The first two properties select the ORB you will be working with, which is AdironORB. The next property, "org.adiron.orb.server.enable", determines whether the ORB will be used for server applications. For a client application, this property is set to false. The next property, "org.adiron.orb.ORBInitializerClass", specifying the AdironORB internal initializer, is set to "com.adiron.orbasec.sl3.AdironORBInitializer" for using ORBAsec SL3's secure network communications. The last property, starting with "org.omg.PortableInterceptor.ORBInitializerClass", installs ORBAsec SL3 into the Adiron ORB by way of Portable Interceptors. Server initialization is basically the same except that we change the value of the "org.adiron.orb.server.enable" property to true. Server initialization is performed as follows: java.util.Properties props = System.getProperties(); props.put("org.omg.CORBA.ORBClass", "com.adiron.orb.core.ORB"); props.put("org.omg.CORBA.ORBSingletonClass", "com.adiron.orb.core.ORBSingleton"); props.put("org.adiron.orb.server.enable","true"); props.put("org.adiron.orb.ORBInitializerClass", "com.adiron.orbasec.sl3.AdironORBInitializer"); props.put("org.omg.PortableInterceptor.ORBInitializerClass." + "com.adiron.orbasec.sl3.SL3Initializer_AdironORB", ""); org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init(args, props); You need the server initialization if you are going to access the Root POA using the orb.resolve_initial_references("RootPOA") call and perform object._this(orb) calls, which "registers" an object implementation with the ORB's POAs. Programming with ORBAsec SL3 and ORBacus ---------------------------------------- The first thing you need to do to get started with ORBAsec SL3 is to initialize the ORB with ORBAsec SL3. There are two different ways to initialize ORBAsec SL3, one if your application is going to be pure client, and the other if your application is going to be a server. This means without bringing up the RootPOA and one if you are going to be a server, i.e. reference the RootPOA, which is the Portable Object Adapter. Client initialization is performed as follows: java.util.Properties props = System.getProperties(); props.put("org.omg.CORBA.ORBClass", "com.ooc.CORBA.ORB"); props.put("org.omg.CORBA.ORBSingletonClass", "com.ooc.CORBA.ORBSingleton"); props.put("ooc.oci.plugin.iiop","com.adiron.orbasec.sl3.IIOP"); props.put("org.omg.PortableInterceptor.ORBInitializerClass." + "com.adiron.orbasec.sl3.ClientInitializer", ""); org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init(args, props); The first two properties select the ORB you will be working with, which is ORBacus. The next property, "ooc.oci.plugin.iiop", specifying the IIOP plug-in class, is set to "com.adiron.orbasec.sl3.IIOP" for using ORBAsec SL3's secure network communications instead of ORBacus' "insecure" IIOP communications. The next property installs ORBAsec SL3 into the ORBacus ORB by way of Portable Interceptors, which is an ORB initialization interceptor. We use the class "com.adiron.orbasec.sl3.ClientInitializer" to initialize a client. Server initialization is basically the same except that we use a different interceptor, "com.adiron.orbasec.sl3.ServerInitializer". Server initialization is performed as follows: java.util.Properties props = System.getProperties(); props.put("org.omg.CORBA.ORBClass", "com.ooc.CORBA.ORB"); props.put("org.omg.CORBA.ORBSingletonClass", "com.ooc.CORBA.ORBSingleton"); props.put("ooc.oci.plugin.iiop","com.adiron.orbasec.sl3.IIOP"); props.put("org.omg.PortableInterceptor.ORBInitializerClass." + "com.adiron.orbasec.sl3.ServerInitializer", ""); org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init(args, props); Special Notes for Previous Users (ORBAsec SL3 3.4.0 and before) ----------------------------------------------------------- In the previous versions of ORBAsec SL3, application programs may use the following code to set a system property: props.put("ooc.orb.init_iiop","none"); With the new OCI implementation in ORBacus 4.1.0, the above code must be changed to props.put("ooc.oci.plugin.iiop","com.adiron.orbasec.sl3.IIOP"); in ORBAsec SL3 3.4.1 and higher. Documentation for ORBAsec SL3 ----------------------------- We are currently working on a User Guide for ORBAsec SL3. However, it is not yet done. You can rely heavily on the demonstration programs for what you need to get you started. There are many good examples there. Also, for a better understanding of the interfaces you can look at the "javadoc" information (or comments in the IDL files) that gets generated by the IDL documentation program. The HTML for this documentation gets installed in the "docs" directory. ORBAsec SL3 Debugging Information --------------------------------- We have added configuration access to ORBAsec SL3 debugging information. Various debugging routines print out information during connections and various CSIv2 activities. The debugging routines are enabled by setting the following system properties. orbasec.debug=true turns debugging on. This property MUST be true regardless of the following properties values. orbasec.debug.ALL=true enables all debugging information orbasec.debug.SL3=true information relating to various initialization and general secure ORB activity. orbasec.debug.CSI=true information relating to generic CSIv2 credential handling. orbasec.debug.TRANSPORT=true information relating to generic transport handling. orbasec.debug.TCPIP=true information relating to the TCPIP transport orbasec.debug.SSL=true information relating to SSL transports orbasec.debug.SSL_VERIFY=true information about the SSL Default Certificate Chain Identity Verifier we use. If the user replaces the ChainVerifier, this property does nothing. orbasec.debug.SECIOP=true information relating to SECIOP transports. orbasec.debug.SECP=true information relating to the SECP protocol. orbasec.debug.SECP_LOG=true enables logging GSS tokens to files. orbasec.debug.KRB5=true information relating to Kerberos transports orbasec.debug.GC=true information relating to the creation and destroy of credentials and contexts. For ORBacus, you may put these properties in a Java Properties file and use the ORB command line argument -ORBconfig, i.e., java -ORBconfig . NOTE: Debugging information is cryptic and terribly verbose, but it is helpful when you report a problem to us. Good Luck! ---------- May ORBAsec SL3 secure all your applications! We are interested in hearing your comments and especially any problems you encounter. Please subscribe to our mailing list "sl3-users@adiron.com" by going to the following "Mailman" mailing list management page: http://greene.case.syr.edu/mailman/listinfo/sl3-users This link may also be found under the ORBAsec SL3 page at http://www.adiron.com. Cheers, The Adiron ORBAsec SL3 Team. ------------------------------------------------------------------------ Copyright (C) 2004 Adiron, LLC. All rights reserved.