$Id: README,v 1.21 2002/10/25 03:23:32 ekr Exp $
PureTLS 0.9b4

Copyright (C) 1999-2003 Claymore Systems, Inc.

DESCRIPTION
PureTLS is a free Java-only implementation of the SSLv3 and TLSv1
(RFC2246) protocols. PureTLS was developed by Eric Rescorla for
Claymore Systems, Inc, but is being distributed for free because we
believe that basic network security is a public good and should be a
commodity. PureTLS is licensed under a Berkeley-style license, which
basically means that you can do anything you want with it, provided
that you give us credit.

This is a beta release of PureTLS. It fixes known security problems in
PureTLS 0.9b3. Although it has undergone a fair amount of testing and
is believed to operate correctly, it no doubt contains significant
bugs, which this release is intended to shake out. Please send any bug
reports to the author at <ekr@rtfm.com>.

We believe that this is the best version of PureTLS available.  Users
are advised to upgrade as soon as possible. Server users using RSA
should upgrade to get the improved Bleichenbacher protection (see
CHANGES).


FUNCTIONALITY
PureTLS implements the SSLv3 and TLSv1 protocols, with the following
cipher suites:
	TLS_DHE_DSS_WITH_DES_CBC_SHA   
	TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
	TLS_RSA_WITH_DES_CBC_SHA
	TLS_RSA_WITH_3DES_EDE_CBC_SHA
	TLS_RSA_WITH_RC4_128_MD5
	TLS_RSA_WITH_RC4_128_SHA
	TLS_RSA_EXPORT_WITH_RC4_40_MD5
	TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5
	TLS_RSA_EXPORT_WITH_DES40_CBC_SHA

DEPENDENCIES
JDK:
PureTLS has been developed under JDK 1.2 on FreeBSD. It 
has been tested under JDK 1.2 and JDK 1.3 on Solaris and Windows.

Cryptix:
Although PureTLS includes some crypto functionality (DH and DSS
implementations) it depends on Cryptix for a number of algorithms
(RSA, MD5, SHA-1, DES, 3DES, RC4, RC2). It would be nice if any
JCE-compliant provider would work and we'll work on that for future
releases, but for the moment, Cryptix is required. The issue is that
key formats are not standardized and we depend on Cryptix-specific
formats. 

The latest version of Cryptix (3.2) can be obtained at:
http://www.cryptix.org/

Cryptix ASN.1 kit:
PureTLS uses the Cryptix ASN.1 kit for it's certificate and key parsing.
Due to version skew you need to get a modified version from
http://www.rtfm.com/puretls
This version is known to work.

PACKAGE OVERVIEW
This distribution contains the following files:
README        -- this file
COPYRIGHT     -- licensing terms for this distribution
INSTALL	      -- installation instructions
build.sh      -- a shell script which builds the distribution
root.pem      -- the root certificate for the RSA test hierarchy
client.pem    -- a RSA test certificate for a client
server.pem    -- a RSA test certificate for a server
dsa-root.pem      -- the root certificate for the DSA test hierarchy
dsa-client.pem    -- a DSA test certificate for a client
dsa-server.pem    -- a DSA test certificate for a server
dh1024.pem    -- a set of DH parameters
test.pl	      -- a test script. This will need modification
		 if you want to run it in your environment

PureTLS itself consists of a number of Java packages, all of which live
under the src/ directory:
COM.claymoresystems.ptls      -- the main PureTLS code
COM.claymoresystems.sslg      -- a number of interfaces which PureTLS
				 implements
COM.claymoresystems.crypto    -- supplementary crypto code
COM.claymoresystems.cert      -- the certificate handling engine
COM.claymoresystems.provider  -- the Claymore Systems JCE provider,
				 implementing DSS
COM.claymoresystems.util      -- random utility classes

The demo code lives in:
COM.claymoresystems.ptls.demo

A more complete test harness lives in:
COM.claymoresystems.ptls.test
There are no guarantees this will work in your system.

CHANGES FROM B4
* SECURITY: Added protection against Vaudenay and Boneh-Brumley
  timing attacks.


CERTIFICATE CHECKING DETAILS
By default, PureTLS will check Basic Constraints and Key Usage and
throw an error if they are wrong but continue if they are not present.
This is a change from the older version where no checks at all
were performed. 

You can use the COM.claymoresystems.sslg.CertVerifyPolicyInt class to
set a stricter policy of requiring the presence and correctness of
these extensions. For PKIX compliance, set the policy to require Basic
Constraints but not Key Usage. Note that setting this policy may
cause failures with older intermediate certificates which did not
include Basic Constraints.

If you do not require Basic Constraints checking, you must check
the certificate chain yourself, as before, either by checking
extensions and enforcing maximum length. Even if you do require
Basic Constraints to be present we still recommend enforcing maximum
chain length since CAs have been known to make mistakes, and extension
support in PureTLS has seen only internal testing.

The policy setting for whether to check certificate expiry dates
has also been moved to CertVerifyPolicyInt.


INSTALLATION
See the file INSTALL in this directory for how to install.

INTEROPERABILITY ISSUES
PureTLS has been tested against OpenSSL, Terisa's SecureWeb toolkit,
Netscape and IE.

SHAMELESS PLUG
I developed PureTLS because Claymore Systems needed it to
develop an enterprise Java security solution. Although we're
giving away PureTLS, we're selling these enterprise Java security
components. If you're interested, please contact Claymore
marketing at kevin@dick.org

I also do security consulting, mainly systems design and analysis.
If you're interested in this, contact me at ekr@rtfm.com 
(http://www.rtfm.com/).

