                Java(tm) Secure Socket Extension 1.0.1

                                README

-----------------------------------------------------------------------
CONTENTS

     - Introduction
     - Understanding The Export Issues
     - Where To Find Documentation
     - Send Us Feedback!


-----------------------------------------------------------------------
Introduction
-----------------------------------------------------------------------
Thank you for downloading the Java(tm) Secure Socket Extension (JSSE)
1.0.1.  JSSE 1.0.1 supplements the Java 2 platform, and requires that
you have it installed.

JSSE 1.0.1 is written entirely in the Java(tm) programming language.


-----------------------------------------------------------------------
Installation
-----------------------------------------------------------------------
JSSE 1.0.1 is supplied as an extension to the Java 2 platform.  JSSE is
implemented via a Java Cryptography Architecture (JCA) security
provider class.

Note:
	(Windows and Solaris use different pathname separators, so
	please use the appropriate one ("\", "/") for your
	environment.)

	<java-home> refers to the directory where the Java 2 Runtime
	Environment (JRE) was installed.  The Java 2 SDK (aka JDK)
	contains the JRE, but at a different level in the file
	hierarchy.  For example, if the Java 2 SDK or JRE was installed
	in /home/user1, <java-home> would be:

		/home/user1/jdk1.2.x		[JRE]
		/home/user1/jre1.2.x/jre	[SDK]


1)  Install the JSSE jar files.
	The JSSE lib subdirectory contains the extension files jsse.jar,
	jcert.jar, and jnet.jar.  You can either install these files in
	the JDK/JRE ("installed extension") or bundle them with your
	applet or application ("bundled extension").  If you
	wish to install them as an installed extension, place
	them in the following directory:

		<java-home>/lib/ext

2)  Register the SunJSSE provider.
	JSSE 1.0.1 comes standard with a Cryptographic Service Provider,
	or "provider" for short, named "SunJSSE".  Although the "SunJSSE"
	provider is supplied with every JSSE 1.0.1 installation, it still
	needs to be configured explicitly, either statically or
	dynamically, before its services can be accessed.

2a)  Static registration of SunJSSE provider.
	Add the "SunJSSE" provider to your list of approved providers.
	This is done statically by editing the security properties file:

		<java-home>\lib\security\java.security [Win32]
		<java-home>/lib/security/java.security [Solaris]

	One of the types of properties contained in the java.security
	file is of the following form:

		security.provider.n=providerClassName

	This declares a provider, and specifies its preference order "n".
	The preference order is the order in which providers are
	searched for requested algorithms (when no specific provider is
	requested).  The order is 1-based; 1 is the most preferred,
	followed by 2, and so on.

	Add the above line to java.security, replacing
	providerClassName with com.sun.net.ssl.internal.ssl.Provider,
	and substituting n with the priority that you would like to
	assign to the "SunJSSE" provider.  For example, to add the Sun
	internal SSL provider to the standard provider shipped with the
	JRE, your entries would look like:

		security.provider.1=sun.security.provider.Sun
		security.provider.2=com.sun.net.ssl.internal.ssl.Provider

	"SunJSSE" would now be the second preferred provider.

2b)  Dynamic registration of SunJSSE provider.
	Instead of registering the provider statically, you can add the
	provider dynamically at runtime by adding the following lines
	of code at the beginning of your program:

		Security.addProvider(
		    new com.sun.net.ssl.internal.ssl.Provider());

3)  Install a JSSE-specific cacerts file, if desired.
	JSSE will first check for an alternate cacert file before
	falling back on the standard cacert file, so that you can
	provide a JSSE-specific set of trusted root certificates
	separate from ones that might be present in cacerts for code
	signing purposes.

	The search order for the locating the trust store is:

	1)  the file specified by the system property javax.net.ssl.trustStore,
	2)  <java-home>/lib/security/jssecacerts, then
	3)  <java-home>/lib/security/cacerts.


-----------------------------------------------------------------------
HTTPS Support
-----------------------------------------------------------------------
The JSSE reference implementation contains a URL handler for the
"https" URL protocol type.  In order to use this handler, you must add
the handler's implementation package name to the list of packages which
are searched by the Java URL class.  This is configured via the
"java.protocol.handler.pkgs" system property.  See the java.net.URL
class documentation for details.  System properties can be set via the
command line or at runtime through the java.lang.System class.

For example, you can set this property on the command line via:

	java -Djava.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol

When accessing HTTPS servers through a web proxy, you must set the
"https.proxyHost" and "https.proxyPort" system properties to the
correct host name and port number of the web proxy.

For example, to set this property on the command line to access HTTPS
servers through the proxy host "webproxy" running at port 8080 you
would use:

	java -Dhttps.proxyHost=webproxy -Dhttps.proxyPort=8080


-----------------------------------------------------------------------
Understanding The Export Issues
-----------------------------------------------------------------------
This release of JSSE 1.0.1 contains a global version and a domestic
version of JSSE.  The global version may be exported outside of the
United States and Canada.

However, the domestic version of JSSE 1.0.1 is available within the
U.S. and Canada only.  It may not be exported outside the U.S. or
Canada.  When you downloaded the software and agreed to the terms of
the license, you agreed to comply with all U.S. laws and regulations
concerning export of this software.  Be aware that if you export this
software outside the U.S. or Canada, you are liable of violating
U.S. laws.

This does not automatically disqualify products that incorporate JSSE
1.0.1 for export.  Whether a product that incorporates JSSE 1.0.1 is
exportable or not is a case-by-case decision by the U.S. Commerce
Department.  It will depend on how tightly JSSE is bundled with that
product, and how easy it is for users to access the cryptographic
functionality directly and use it for other than the product's
purposes or replace it with stronger cryptographic algorithms or
keys.  Regardless of whether you incorporate the domestic or global
version, you are advised to consult your export control counsel or
attorney to determine the exact requirements.

For more information on U.S. encryption policies, refer to these web
sites:

	U.S. Dept of Commerce		www.doc.gov
	Export Policy Resource Page	www.crypto.com
	Computer Systems Public Policy  www.cspp.org

Reference sites for more information:

	Bruce Schneier's site		www.counterpane.com
	Gene Spafford's site		www.cs.purdue.edu/coast/coast.html


-----------------------------------------------------------------------
Where To Find Documentation
-----------------------------------------------------------------------
Once you have installed JSSE 1.0.1, you will be able to read more
detailed information about the software and how to use it.

The following documents will be of interest to you:

+ An "API Specification & Reference" document:

    <java-home>/doc/guide/API_users_guide.html

+ JSSE 1.0.1 javadocs:

    <java-home>/doc/apidoc/index.html

(<java-home> is the name of the directory that is automatically
created when you extract JSSE 1.0.1.)

+ The Java Security Web site has more information about the JSSE, plus
additional information about the Java 2 Security Model.  Please see:

	http://java.sun.com/products/jsse/
	http://java.sun.com/security/


-----------------------------------------------------------------------
Bug Reports and Feedback
-----------------------------------------------------------------------
Please submit bugs with sample code using the normal Java Developer 
Connection (JDC) process at:

	http://java.sun.com/cgi-bin/bugreport.cgi

Bug reports with sample code are highly appreciated!

(Please be aware that we may be barred from offering technical support
specifically regarding encryption implementations of the JSSE APIs to
people outside the U.S. or Canada, according to U.S. regulations.)

You can send feedback to:

	java-security@sun.com

The above mailing list is not a subscription list.  It is simply a
one-way channel that you can use to send feedback to the Java 2
Standard Edition security group.

An archive of previous discussions is available online at:

	http://archives.java.sun.com/archives/java-security.html


-----------------------------------------------------------------------
Miscellaneous Credits
-----------------------------------------------------------------------
Portions of this release of JSSE 1.0.1 include binary bytecode which is
subject to the following notice:

// Copyright (C) 1996 by Jef Poskanzer <jef@acme.com>.  All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//
// THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
// OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
// OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
// SUCH DAMAGE.
//
// Visit the ACME Labs Java page for up-to-date versions of this and other
// fine Java utilities: http://www.acme.com/java/

