Sample code for JCSI GSSAPI
============================

This directory houses sample GSSAPI programs. 

This example requires an RFC 1510 compliant Kerberos V Key Distribution
Centre or KDC (eg. the one from MIT) to be installed and configured.

It has been reported to work against MIT Kerberos V, Dascom DCE for Unix
and IBM DCE for Windows NT.

** Instructions for doing this are not included here. **

Contents
--------

  README          this document
  jcsi/           source code
  classes/        compiled .class files
  Makefile        a Unix Makefile in case re-compilation is necessary
  jgss-server     a Unix shell script to run the GSSAPI server
  jgss-client     a Unix shell script to run the GSSAPI client

Re-compilation
--------------

Compiled classes for the sample programs are included in the classes/
directory for convenience. If re-compilation is necessary (for instance,
if you change the source code), the included Makefile should suffice.

The programs
------------

These sample programs are modelled on (and designed to be interoperable with) 
the gss-sample programs in the MIT Kerberos V distribution. The client
establishes a GSSAPI context with a server, sends it an encrypted message
and gets back the message "signed" (ie. integrity-protected) by the server.

The client program jcs.GSSClient requires a Ticket Granting Ticket (TGT)
from a KDC, whereas the server program jcsi.GSSServer requires a keytab
from the KDC with which it is registered. Currently, the client's KDC and
the server's KDC are required to be the same (in order words, inter-REALM
support is not yet available).

The following (KDC-specific) Kerberos steps are required for this
example (see your Kerberos administrator):

  1. Register a user with the KDC.

  2. Register a service with the KDC.

     Typically, the service is of the form

       <service name>/<host fqdn>@REALM

     For this example, "gss-server" is recommended as the service name.

  3. Add the registered service principal's key to a keytab.
     Make sure you have read permission on this keytab.
     
The following (JCSI-specific) steps are then required (in addition to
the Setup instructions below).

  4. Configure your kerberos.properties for your Kerberos REALM.

  5. Copy your keytab to the location pointed to by the jcsi.kerberos.keytab
     property in kerberos.properties (by default, krb5.keytab)

  6. Obtain a TGT for the registered user. This can be done with 
     JCSI's jKinit script, or with eg, MIT Kerberos kinit. Make sure the 
     credential cache in which this TGT is kept corresponds to that which
     is configured in kerberos.properties.

Next, run the server 

  jgss-server [-port <port>] <service name>

on your port of choice, and for the service previously registered.
<service name> must be a fully-qualified GSSAPI service name of the
form 

  service@<host fqdn>

(note the difference between the Kerberos & GSSAPI fully-qualified names).
Because Java's InetAddress.getLocalHost().getName() does not consistently
return the fully-qualified domain name over all JDK 1.2 ports, this must
be specifically added.

Finally, run the client

  jgss-client [-port <port>] <host> <service name> <message>

where <service name> must be the same fully qualified GSSAPI name as
above.


Note: The user on behalf of which the client is run needs not be the same as 
that for the server. If necessary, the location of the kerberos.properties 
file can be configured by passing -Djcsi.kerberos.conf=<location> on the 
command-line to the java interpreter.

Setup
-----

This distribution contains jar files, compiled classes & key files,
(almost!) sufficient to run both the sample programs in this directory. 

To test the SSL client, follow these instructions:

  0. Make sure you have JDK 1.2 properly set up, and the DSTC provider
     configured (See the top-level README if necessary)

  1. Make a copy of the <jcsi_install_dir>/.jcsi/ sub-directory under
     your home directory.

  2. In the file kerberos.properties in <your_home_directory>/.jcsi/, change
     the 'jcsi.kerberos.key.dir' entry to point to the full pathname of the
     <your_home_directory>/.jcsi/keys/ directory.

     (for Windows use "\\" as the path separator,
      eg. C:\\WINNT\\Profiles\\Administrator\\.jcsi\\keys)

