
			 SSL integration for JacORB 1.1
			_______________________________

Abstract:

	To have SSL support requires NO changes in your source
	code, but you need to rebuild JacORB as explained hereafter,
	create and deploy key stores holding the cryptographic data.

Required: 

	- JDK 1.2 or later

	- IAIK-JCE 2.6 beta 1, the security provider classes
	  downloadable from http://jcewww.iaik.tu-graz.ac.at/index.htm

	- iSaSiLk 3.0 or later, the SSL implementation
	  downloadable from http://jcewww.iaik.tu-graz.ac.at/index.htm

	[ Remark: We will allow using SUN provider and SSL implementation
	  in the next release ]

Introduction:
=============

  When the  ORB instance is  initialized by the  application, properties
are read from files and the  command line. For the default SSL support
we define two properties:

	jacorb.security.support_ssl=on
	jacorb.security.enforce_ssl=on    

If support_ssl=off  then enforce_ssl=off also.  enforce_ssl means that
any  outgoing  or  incoming  request  will  have to  be  over  an  SSL
connection; CORBA::NO_PERMISSION is thrown if the policy is violated.

If jacorb.security.support_ssl=on  the user will  have to authenticate
himself.  The authentication  succeeds if a key entry  can be found in
the key store file.  (Roles will be supported in a later version).

Cryptographic  data  (key  pairs  and  certificates) is  stored  in  a
.keystore file.  The .keystore has  to be in the home directory (where
property files also are).  IMPORTANT: define in your property file

	jacorb.security.keystore=.keystore

otherwise a .keystore file will be searched in the current directory.

The  key  store  holds  the  key entries  for  principals,  which  can
authenticate  themselves  to  the   object  system,  and  the  trusted
certificate entries for the  Certification Authorities accepted by the
object system.

There is  one instance of JacORB  per JVM. This ORB  instance will use
the  user's   keys  and  certificate  chain,   when  establishing  SSL
connections.

The  class  jacorb/security/util/KeyStoreManager  should  be  used  to
create the  key stores.   Its features are:  generate key  pairs, sign
public keys,  import or export certificates chains  and define trusted
certificate  authorities.  The first  certificate  in the  certificate
chain may have a role extension.

Building JacORB with SSL support:
================================

1. Make   sure  that   the   cryptographic  libraries   are  in   your
   CLASSPATH.  (If  they  are  not,  JacORB will  be  built  without  SSL
   support.)

2. Build JacORB anew: go to the installation directory and call "ant"
   
3. Edit the properties file to set the security-relevant properties as
   outlined above
   

Creating key stores:
===================

   You can proceed as follow:
   
1. Start  jacorb.security.util.KeyStoreManager  and  create  a  (new)
   master key  store, which should hold  key pairs for the  users and CAs
   (menu File/New).

   Remember that key pairs are stored in key entries. For each user and CA
   create a key entry (menu Keys/Create). Remark: a user can be assigned
   more then one key entry (use different aliases), if for example he will
   act in different roles. For more details, please consult the JKD tool
   documentation for "keytool", which explains the key store concept.

2. Public keys of users have to be  signed by at least one CA (you can
   have intermediate  signer in a  certificate chain). As you  create the
   certificate chain (menu Certificates/Create)  you can assign a role to
   the alias.
   
3. Export the certificates of the CAs (menu Certificates/Export).
   Save your master key store to a file.

4. For each machine and/or user you will derive a key store as follows:
	- Make a copy of the master key store and open it in KeyStoreManager
	  (menu File/Open).
	- Remove all key entries for CAs (menu Keys/Delete).
	- Remove all key entries for users not that machine (menu Keys/Delete).
	- Create a trusted certificate entry for each CA (menu Trustees/Add).
	  You will need the exported certificates for this.
	- Save the key store to a file.

5. Deploy the key store files. 

