$Id: INSTALL,v 1.9 2002/08/28 02:48:00 ekr Exp $
PureTLS 0.9b2-SNAP Nov 19, 2001

PureTLS INSTALLATION GUIDE

Firstly, you'll need a JavaVM. Anything over JDK 1.1.7 ought to work,
including JDK 1.2.

PureTLS also depends on Cryptix and the Cryptix ASN.1 kit.
You must use Cryptix 3.2. We're still using a modified downrev
version of the Cryptix ASN.1 kit which you can get prebuilt off of
the PureTLS website at http://www.rtfm.com/puretls

INSTALLING CRYPTIX
You can get Cryptix-3.2 at http://www.cryptix.org/. 

When you unzip the Cryptix zip file you'll get a directory
containing all the directories with no top-level directory.
I strongly recommend you make a new directory first, e.g.

  mkdir Cryptix-3.2
  cd Cryptix-3.2
  unzip <zipfile>

You'll end up with the jarfile cryptix32.jar in your top level
directory. Put this file somewhere in your classpath.


INSTALLING THE CRYPTIX ASN.1 KIT
Untar the Cryptix-asn1 distribution. So, if you're using
the 20011119 distribution you'd do:

       	gunzip < Cryptix-asn1-20011119.tar.gz | tar xf -
	
This will build a directory called Cryptix-asn1-20011119.
The file you want is cryptix-asn1.jar which lives in this
directory. Put that file in your classpath.


INSTALLING GNU GETOPT:
Although PureTLS does not require it, the demo programs
in ptls/demo do require GNU Getopt for Java in order
to process the command line options that control them.

You can get a copy at:
	http://www.urbanophile.com/~arenn/hacking/download.html

It's fairly easy to install, and contains directions. 
If you don't install it, the demo programs won't compile,
but the rest of PureTLS will compile and work fine.

INSTALLING PureTLS:
Wherever you unpacked PureTLS, it created a directory called
puretls-0.9b1-SNAP-<whatever> which contains, among other things, the
README file. It also contains a subdirectory called src which contains
the source. 

There are two build options. The new build system uses make.
The old build system uses shell or batch scripts. The script
system is deprecated and will likely be removed in 0.9b2-fcs. 
Only use it if you can't get make to work for you.


NEW INSTALL (using make)
First, cd to src. Then examine the Makefile to see if you need to
make any changes to your local environment, such as changing the
compile flags or the Java compiler. 

Make sure that your JDK_VERSION is set correctly in the Makefile.
Valid settings are 1.2, 1.3, and 1.4. If you have 1.2.x or 1.1.8,
use 1.2. Note that if you change this setting you must do a 
'make clean' before you can rebuild.

To build the main PureTLS code and jar file, do:
	make 
This will build the jar file <ROOT>/build/puretls.jar and the
Javadoc in <ROOT>/build/api.

To build the demo programs, do:
	make demo
This will build the jar file for the demo programs in
<ROOT>/build/puretlsdemo.jar

Note: You may find that your version of make doesn't like the
Makefile. Unfortunately, Makefile syntax varies dramatically
between operating systems. If you find this to be the case,
use GNUMake, which is known to work.

NEW INSTALL (using Ant)
Copy the file build.properties.sample to build.properties.
Edit build.properties if appropriate to point to the
locations of cryptix32.jar and cryptix-asn1.jar. 

Type 
	ant
to build the PureTLS distribution. This will automatically build
both <ROOT>build/puretls.jar and <ROOT>build/puretlsdemo.jar.
NOTE: The demo jar file will be empty if the GNU Getopt is not
installed somewhere in the CLASSPATH. This is something of a bug.

Type
	ant javadoc
To build the javadoc in build/doc/api.

OLD INSTALL (using scripts)
In src, execute the build script using
	sh build.sh 
or 	
	build.bat

on Windows

This will compile the distribution, assuming that 'javac' is 
in your path. The distribution will build the class files in
the local directories and will also construct a jar file called
puretls.jar in <ROOT>. This jar file contains the demo programs if
they built successfully.


RUNNING DEMO PROGRAMS
At this point, you're ready to run the demo programs that come with
PureTLS. In the toplevel directory (the one containing this file),
execute:
	java COM.claymoresystems.ptls.demo.SSLServer -f -D dh1024.pem
the -f tells it to seed the PRNG with zeros for faster startup
(but zero security)
the -D tells it to use dh1024.pem for it's DH params instead of
generating them on the fly.

and in a different shell, execute:
	java COM.claymoresystems.ptls.demo.SSLClient


If all goes well, you should see (in the window in which
you ran SSLClient):
	Cipher suite: TLS_DHE_DSS_WITH_DES_CBC_SHA
	Cert chain
	Issuer C=US,ST=California,O=Claymore Systems, Inc.,CN=Test CA
	Subject C=US,ST=California,O=Claymore Systems, Inc.,CN=Test CA
	Serial 0
	Validity Tue Jun 22 18:07:17 GMT 1999-Thu Jul 22 18:07:17 GMT 1999
	Issuer C=US,ST=California,O=Claymore Systems, Inc.,CN=Test CA
	Subject C=US,ST=California,O=Claymore Systems, Inc.,CN=Test Server
	Serial 6
	Validity Tue Jun 22 18:08:24 GMT 1999-Wed Jun 21 18:08:24 GMT 2000
	HTTP/1.0 200 OK
	Server: PureTLS Demo Server

	Success!

And in the window in which you ran SSLServer:
	Accepted connection

If this doesn't work, you probably got some sort of Exception backtrace.
Send us a copy and we'll try to figure out what's going on.

WHERE TO GO NOW
The next thing you want to do is read the Javadoc, which the build
script drops in the main directory. This should give you enough
information to start coding applications using PureTLS. You should
also look at the demo programs for running examples.

Good luck!




