Over the next months, a JCSI User Guide will appear on our website.

In the meantime.....



This release of JCSI from DSTC's Java Cryptography and Security Project
features 

 (1) a JCE implementation 
 (2) a Security Provider 
 (3) a Public Key Infrastructure (PKI) library and tools
 (4) a Cryptographic Message Syntax (CMS) library
 (5) an S/MIME library and tools
 (6) an SSL library
 (7) a Kerberos/GSSAPI library and tools
 (8) sample code for the various JCSI components


The JCE and Security Provider are meant to be used in the standard
manner (Refer to JavaSoft's JDK 1.2 security documentation for an
introduction to the Java Cryptography Architecture). 

The other libraries are built on top of the standard JCA/JCE APIs.  
This includes 
 
 (a) the SSL library which implements the javax.net.ssl APIs,
     through which application programming should be done
 (b) the PKI, CMS, and S/MIME libraries written to proprietary APIs,
     which are preliminary and are subject to changes at the interface level. 
 (c) the Kerberos V library which has a proprietary API, together with
     a GSSAPI for application programming which is based on a draft
     standard.


The PKI library requires the use of the Java Naming & Directory 
Interface (JNDI) for LDAP access, and the Java Servlet Development Kit 
(JSDK) 2.1 for on-line Certification Authority (CA) functionality. These can 
be downloaded from the JavaSoft site http://www.javasoft.com.

The S/MIME library is integrated with the JavaMail framework, which in
turn uses the Java Activation Framework (JAF). These can also be
downloaded from http://www.javasoft.com.



Contents
========

1. javax/   : source for the JCSI JCE & javax.net.ssl implementations
2. com/     : source for JCSI provider & secure protocol implementations
3. jars/    : jar files 
4. classes/ : class files after compilation
5. apidocs/ : API docs after generation
6. bin/     : shell scripts JCSI tools
7. samples/ : sample code for JCA/JCE, online CA, SSL, RMI over SSL, & S/MIME.


Re-compilation
==============

Recompilation is _NOT_ necessary unless you change the source.

(The included Makefile is for UNIX only; on Windows, adapt it for nmake, or
run the javac commands manually)

1. Set up the path to your javac.
2. Put jndi.jar, ldap.jar, providerutil.jar from JNDI, 
   mail.jar from JavaMail, and activation.jar from JAF in your classpath

   e.g. CLASSPATH=.:./classes:./classes/jndi.jar:./classes/ldap.jar
        EXPORT CLASSPATH=$CLASSPATH:./classes/jsdk.jar

   or, preferably (if you have permission) into the extensions sub-directory.

3. 'make all' from the top directory will compile the whole thing and 
    put the .class files under the classes/ sub-directory
4. Optionally remake the jar files with 'make jar' in the current directory.


To use the JCE & provider
=========================

1. See JavaSoft security documentation 
   (http://www.javasoft.com/products/jdk1.2/docs/guide/security/index.html,
    http://java.sun.com/products/jdk/1.2/jce/). 
   For instance, to statically register the provider, you will need to
   add an entry in the system-wide java.security properties file.

2. Add the jar file jcsi.jar to the extensions subdirectory or to your 
   classpath.
3. See the samples/misc directory for sample code which uses the JCA/JCE
   APIs.


To use the SSL library and examples
===================================

The javax.net.ssl APIs do not specify a mechanism for comfiguration.
JCSI uses a proprietary mechanism based on a Properties file 
pointed to by the System Property jcsi.ssl.conf, or by default, the
file <user.home>/.jcsi/ssl.properties.

For a server, the following is configurable:

  i)   enabled cipher suites
  ii)  server private key, password-protected using PKCS#8
  iii) password to unlock private key (if not supplied, this will be
       prompted for)
  iv)  server certs 
  v)   whether client authentication is required
  vi)  trusted certs (for client authentication)

Certificates can either be a single DER encoding, or multiple base64
encoded DER encodings, delimited as per PEM in a single file (with
no spurious whitespace, whatsoever).

For a client, the following is configurable:

  i)   enabled cipher suites
  ii)  client private key, password-protected using PKCS#8 (if not
       supplied, client authentication is not possible)
  iii) password to unlock private key (if not supplied, this will be
       prompted for)
  iv)  client certs (if not supplied, client authentication is not
       possible)
  vi)  trusted certs


Test client and server code is available in the samples/ssl/ directory
which can be run as is against existing SSL-enabled Web servers and
your favourite Web browser.

For RMI over SSL, take a look at the samples/rmi_ssl/ directory.

NB: This release of the SSL library is for testing only. Robustness,
security and performance enhancements will be made before the Final
Release.

To use the PKI tools
====================

Three tools are provided (Unix shell scripts available in the bin/
directory):

  a) caTool
       -- Use this to generate self-signed X.509 v3 certificates,
       -- or user certificates. Takes PKCS#10 certificate signing requests
       -- generated by JDK 1.2's keytool or JCSI's keyTool.
       -- 
       -- Usage: caTool
      
  b) repositoryTool 
       -- Use this to publish or retrieve a user certificate from
       -- an LDAP directory.
       --
       -- Usage: repositoryTool

  c) keyTool  
       -- Use this to generate a key pair and make a PKCS#10 certificate
       -- signing request. The request can saved in a file to be
       -- handed to the CA to process using caTool. 
       --
       -- Usage: keyTool

A sample online CA is included in the samples/onlineCA directory. This
is set up to service certification requests from either Netscape Communicator
or Microsoft Internet Explorer.

The CA tools rely on the configuration file pointed to by the System
Property jcsi.ca.conf or, by default, <user.home>/.jcsi/ca.properties.
You will need to modify this file to suit your purpose. Some commentary is 
provided within.

When using the CA tools for the first time, you will need to do the following:

 i.   Set the CA's distinguished name in ca.properties
 ii.  Run caTool to generate a key pair and self-signed certificate for
      the CA. Save the private key and certificate and place in the 
      locations specified in ca.properties
 iii. Set the path to the key and cert in ca.properties
 iv.  Set the password used to protect the private key. This is for online CA
      (It's not secure :-(, I know)
 v.   If LDAP functionality is required, change ca.properties to suit
  
NB. It goes without saying that the .jcsi/ sub-directory contains
sensitive information and should be protected appropriately.


To use the S/MIME tool
======================

A text-based S/MIME mail client called SecMail is provided. 

      SecMail
        -- Use this to compose and send signed and/or encrypted text email,
        -- or to process received signed and/or encrypted mail files. 
        -- 
        -- Message composition is primitive (follows the Unix Mail interface)
        -- and does not yet support attachments. S/MIME messages to be 
        -- decoded are expected to be in a separate file for each message.
        --
        -- Usage: SecMail

When using SecMail for the first time, follow the Setup menu option to
add trusted CA certificates. These are cached and written to disk when
SecMail exits normally. Use this option also when encountered with a
signed S/MIME message from someone whose certificate is issued by a CA
not already trusted and which you want to trust.

SecMail caches certificates from received S/MIME messages which are capable
of supporting encryption, and which have the receiver's email address either
in a SubjectAltName extension or in the subject distinguished name. CATool
now generates certificates with email addresses in a SubjectAltName extension,
as per S/MIME v3 recommendations.

SecMail supports DSA and RSA-based signature algorithms for signing
and TripleDES and RC2/40 for content encryption, with RSA for key 
encryption.

SecMail has been tested successfully against a recent International Netscape,
using RSA and RC2/40. 

SecMail relies on the configuration file pointed to by the System Property
jcsi.smime.conf or, by default, <user.home>/.jcsi/smime.properties'. You will 
need to modify this file to suit your purpose. Some commentary is provided 
within.

NB: The jar files mail.jar, activation.jar & jcsi.jar need to be all in the
extensions directory to work, otherwise a Java Activation Framework
exception is thrown (JAF bug?).

To use the Kerberos/GSSAPI tools
==================================

A Java version of the "Kerberos login" kinit is provided. An installed
Key Distribution Centre (KDC) compliant with RFC 1510 is needed for this
to work.

      jKinit
        -- Use this to obtain Ticket Granting Tickets (TGTs) from the
        -- KDC. A registed user can use either its password, a keytab
        -- or a cryptographic smartcard (eg. JavaCard) for which a
        -- JCE provider is available
        --
        -- Usage: jKinit [-c | -k keytab | -j provider] [user]

Sample GSSAPI code is included in the samples/gss-sample directory. Please
consult the README there for the gory details.

Configuration is via the file pointed to by the System Property
jcsi.kerberos.conf or, by default, <user.home>/.jcsi/kerberos.properties', 
which will need to be modified to suit. Some commentary is provided within.


To generate API documentation
=============================

1. 'make javadocs' from the top directory will cause javadoc to be executed
    on all the packages with the .html files placed under the apidocs/
    sub-directory
