$Id: INSTALL,v 1.1 1999/06/22 18:19:46 ekr Exp $
PureTLS 0.9a1 21-June-1999

PureTLS INSTALLATION GUIDE

The PureTLS installation is a little tricky, because PureTLS requires
a number of other packages but unfortunately those packages have bugs
that must be patched before PureTLS will work correctly. We hope that
by the time PureTLS beta has been fixed, these packages will have
been patched in the released versions.

Firstly, you'll need to have a JDK 1.1.X compatible VM installed. It's
possible that PureTLS will work under JDK 1.2, but it's never been
tried. If it works, send me email at <ekr@rtfm.com> and let me know.

PureTLS also depends on Cryptix and the Cryptix ASN.1 kit.
We provide a tar file with a built Cryptix/Cryptix ASN.1 tree
at http://www.rtfm.com/puretls/Cryptix.tar.gz
   
so you don't have to build it yourself. If you're feeling brave,
skip down to "INSTALLING CRYPTIX" and follow the directions there.
Then come back and follow the directions under "INSTALLING PureTLS"


INSTALLING PRECOMPILED CRYPTIX:
First you need to pick a root directory for the distribution.
We'll call that <ROOT>. 

Unpack Cryptix.tar.gz in <ROOT>, using 
       	gunzip < Cryptix.tar.gz | tar xf -
	
It will produce a directory called Cryptix in <ROOT>

If you've never installed Cryptix before, you need to install
it as a JCE Security Provider. Do:

	cd <ROOT>/Cryptix/src
	javac -d . cryptix/provider/Install.java

You will probably need to be root to do this.

You'll also need to <ROOT>/Cryptix/src/ to 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.9a1, which contains, among other things, the
README file. It also contains a shell script called 'build.sh'.

First, add <ROOT>/puretls-0.9a1 to your CLASSPATH.

Then execute the build script using
	sh build.sh

This will compile the distribution, assuming that 'javac' is 
in your path. 

Now you need to add the Claymore Service provider to your
list of JCE providers. In the future, we'll have a script to
do this, but for the moment you need to do it by hand.

The relevant file lives in the Java library directory in the
file security/java.security. E.g. 
'/usr/local/jdk1.1.7/lib/security/java.security'.

You'll see a series of lines that look like
	#    security.provider.<n>=<className> 

Find the last one and add a line like:
	security.provider.<n+1>=COM.claymoresystems.provider.ClaymoreProvider

Most likely, Cryptix will be provider number 2, so you'll add the line:
	security.provider.3=COM.claymoresystems.provider.ClaymoreProvider

If you get errors about 'algorithm BlahBlah not available' this probably
means that you've done something wrong here.

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

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


You'll have to wait for 10-30 seconds while the random number
generator seeds (This is an annoyance with Sun's PRNG which we're
still looking to work around. It only happens once per application
so it shouldn't be a problem in production apps.

If all goes well, you should see (in the window in which
you ran SSLClient):
	Cert chain
	Issuer C=US,ST=California,O=RTFM, Inc.,CN=EKR,EM=ekr@rtfm.com
	Subject C=US,ST=California,O=RTFM, Inc.,CN=EKR,EM=ekr@rtfm.com
	Serial 0
	Validity Thu Apr 01 00:25:33 GMT 1999-Sat May 01 00:25:33 GMT 1999
	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!


-----ABANDON ALL HOPE YE WHO ENTER HERE-----
INSTALLING CRYPTIX:
You can get the latest version of Cryptix from http://www.cryptix.org/
You'll want Cryptix version 3.0.3 at the latest. You'll need the source
version, because you need to apply some patches because a number of the
algorithms are broken.

Download the cryptix patch kit from:
	http://www.rtfm.com/puretls/cryptix.patch

Put this in the top of the Cryptix directory and run:
	patch -p < cryptix.patch

Once you've done this, you can safely follow the Cryptix installation
instructions. If you don't make this fix, the SSL handshake will fail
catastrophically, because HMAC will be computed incorrectly.

Here's a brief overview of how to install Cryptix:
1. unpack the distribution into some appropriate directory. It will
create a directory called Cryptix.
2. Make the change described above to
Cryptix/src/cryptix/provider/md/BlockMessageDigest.java
3. in Cryptix/src/, run either build.sh or build.bat depending on
whether you're on Unix or Windows. This should build the class files.
4. Add the Cryptix/src/ directory to your CLASSPATH.
5. If this is the first time you've installed Cryptix, you'll
need to install it as a Security Provider. This is done using the
following commands:
	cd Cryptix/src
	javac -d . cryptix/provider/Install.java

You may see some messages about not being able to build
provider/rpk/*. Ignore them.

For more detail see the install directions that come with Cryptix.

INSTALLING THE CRYPTIX ASN.1 KIT:
First, get a copy of the ASN.1 kit from http://www.cryptix.org/.

You'll need the Alpha 3 kit, which was just released.
It gets unzipped in the Cryptix/src/cryptix directory. 

Before you need to build it, you want to turn off debugging.
If nothing else, it will throw a lot of really annoying output on
the screen, and on some systems it causes the ASN.1 kit to
crash.

To do this, you need to edit 4 files:
asn1/lang/PackageProperties.java:
	change the initialization of GLOBAL_DEBUG to false:
    static final boolean GLOBAL_DEBUG = false;

asn1/lang/lang.properties:
    turn off all tracing:
Trace.Parser =           false
Trace.ASNObject =        false
Trace.SimpleNode =       false
Trace.Tag =              false


asn1/encoding/PackageProperties.java:
    static final boolean GLOBAL_DEBUG = false;

asn1/encoding/encoding.properties:
    turn off all tracing:
Trace.DER =             false
Trace.EncodingFactory = false

Once you've made these changes you're ready to compile. You'll also
need to have a copy of JavaCC. (I told you this was complicated).

Anway, cd to asn1/lang and do:
jjtree ASN1-002.jjt
javacc ASN1-002.jj

Then go to asn1/ and do:
javac */*.java

If all goes well, thing will build. Now go back to the instructions
under "INSTALLING PureTLS" and follow them.


