Sample JCSI SSL code
====================

This directory houses sample SSL client & server programs built with
JCSI SSL.

Contents
--------

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

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
------------

Two sample programs jcsi.SSLClient and jcsi.SSLServer are included.
jcsi.SSLClient. The client can be run against any SSL v3-enabled web
server. The server can be run against any SSL v3-enabled web browser.
The client and server can also be run against each other. The (Unix)
commands to run these programs are:

     sslclient <host> <port>
     sslserver <port>


Setup
-----

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

The following steps are required to use these default key files:

  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 ssl.properties in <your_home_directory>/.jcsi/, change
     the 'jcsi.ssl.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)


Running the client
------------------

To run the SSL client try, for instance,

  sslclient www.openssl.org 443

to establish an SSL connection with the HTTPS server at www.openssl.org.
The client makes an HTTP "GET /" request over the established
SSL connection and displays the raw HTML returned to stdout.

Try changing the 'jcsi.ssl.debugLevel' entry in ssl.properties 
valid values are 0-3) to see the details of the protocol exchanges. 

(On Windows, either run the java command in the script manually, or
convert sslclient to a .bat file) 

The trustedCerts file included in this distribution contains Verisign &
Thawte root certificates sufficient to run against the following servers:

  www.openssl.org
  www.microsoft.com
  www.apache-ssl.org
  www.thawte.com

Running the client
------------------

To test the SSL server try, for instance,

  sslserver 9999

to put the server to listen on port 9999 on the localhost. 

Either run sslclient against it

  sslclient localhost 9999,

or, more interestingly, run Netscape or Microsoft Internet Explorer against
it. Simply point the browser at the URL

  https://localhost:9999/

If you have set up client certificates for your browser (see the onlineCA
example), you can try setting ssl.properties to require client
authentication. 

If you generated the browser certificates with your own CA keys (as opposed
to the ones in this distribution) you will need to add the CA certificate 
to the trustedCerts for sslserver to accept your browser certificates.
Either do this manually, eg. using the Unix tool mimencode to convert from 
DER format to base64 and adding the PEM header & footer, or use the JCSI
SecMail (S)etup option to import the CA cert into trustedCerts.
