readme.txt

java安全

                Java(tm) Secure Socket Extension 1.0.3
                           Sample Code

                             README

----------------------------------------------------------------------
CONTENTS
----------------------------------------------------------------------
	- Introduction
	- Sample KeyStores
	- Code Examples
	- Troubleshooting

----------------------------------------------------------------------
Introduction
----------------------------------------------------------------------
This JSSE sample code bundle provides some rudimentary examples of how
the JSSE can be used to secure communications in the Java(tm) network
environment.

The samples do require some familiarity with Java and the JSSE API, so
please consult the appropriate documentation for more information.

JDK:	http://java.sun.com/doc/

	Also consult the JDK implementation's documentation.

JSSE:	documentation for the JSSE API can be found in Sun's
	JSSE implementation or documentation bundles, or at
	http://java.sun.com/products/jsse/

	Also consult the JSSE implementation's documentation.  Follow any
	instructions given by the vendor as to how to configure the
	security provider, set the classpaths (if necessary), enable the
	https protocol handler, define HTTPS proxy servers, and so on.

----------------------------------------------------------------------
Sample KeyStores
----------------------------------------------------------------------
This bundle includes two sample keystore files that can be used with
the sample code.  They are both stored in the "JKS" KeyStore format,
which is the default format used by Sun's JDK implementation.  (If
another KeyStore format is desired, the JDK will need to be configured
to recognize the new default format.)  The remainder of this document
assumes the Sun implementations of JDK and JSSE are being used.

JSSE uses the certificate KeyStore files to authenticate the clients
and servers.

samplecacerts	This file is very similar to the stock JDK cacerts
		file, in that it contains trust certificates from
		several vendors.  It also contains a trust certificate
		from Duke, the Java mascot (see */testkeys below).

		This file can be installed as:
			<java-home>/lib/security/jssecacerts
		or:
			<java-home>/lib/security/cacerts

		(Be sure to replace this file with a production cacerts
		file before deploying the application.)

		The password for this keystore is the same as the
		JDK cacert's initial password:  changeit

*/testkeys	This file is used by the code samples as the source
		of public/private key and certificate material.  It
		contains the keystore certificate entry for Duke (as
		above in samplecacerts).

		These files are duplicated in each sample directory, as
		the sample code expects the testkeys file to be in the
		current working directory.

		The password for this keystore is:  passphrase

The Sun JDK utility "keytool" can be used to generate certificates and
keystore files.

If you are using the Sun implementations of the JDK and JSSE, you will
configure the system to use the proper trustStore.  Please see the JDK
and JSSE documentation for more information about how to specify
trustStores.

NOTE:  If you use a browser such as Microsoft's Internet Explorer or
Netscape's Navigator to access the example ssl server (e.g.
socket/server/ClassFileServer), you will see a dialog popup with the
message that the application doesn't recognize the "duke" certificate.
This is normal because the self-signed certificate being presented to
the browser is not initially trusted.

----------------------------------------------------------------------
Code Examples
----------------------------------------------------------------------
The sample code bundle is broken into several directories, based on
the style of SSL connections.

urls

    URLReader.java

	This example illustrates using a URL to access resources on a
	secure site.  By default, this example connects to
	www.verisign.com, but it can be adapted to connect to the
	ClassFileServer above.  The URL request must be slightly
	modified, and you must create a host certificate for the https
	host being used, otherwise there will be a "HTTPS hostname
	wrong" error.  (Note:  This behaviour can be overriden by using
	the HostNameVerifier in the HttpsURLConnection class.)

	If you are using Sun's reference implementation, you will need
	to set the System property "java.protocol.handler.pkgs" to
	point to the JSSE https implementation.  Also, if you are
	behind a firewall, you will need to set "https.proxyHost" and
	"https.proxyPort".

	USAGE:
	    java URLReader


    URLReaderWithOptions.java

	This example is very similar to URLReader above, but
	allows you to set the system properties via arguments to the
	main method, rather than as -D options to the java runtime
	environment.

	USAGE:
	    java URLReaderWithOptions [-h proxyhost] [-p proxyport] \
		    [-k protocolhandlerpkgs] [-c ciphersarray]

		proxyHost = secure proxy server hostname (https.proxyHost)
		proxyPort = secure proxy server port (https.proxyPort)
		protocolhandlerpkgs = a "|" separated list of protocol handlers
			(java.protocol.handler.pkgs)
		ciphersarray = enabled cipher suites as a comma separated list
			(https.cipherSuites)

sockets

    server

	ClassServer.java
	ClassFileServer.java

	    This sample demonstrates the implementation of a
	    mini-webserver, which can service simple HTTP or HTTPS
	    requests (only the GET method is supported).

	    By default, the server does not use SSL/TLS.  However,
	    a command line option enables SSL/TLS.

	    Requests must be of the form:

		GET /<filename>

	    USAGE:
		java ClassFileServer port docroot [TLS [true]]

		    port = the port on which the server resides
		    docroot = the root of the local directory hierarchy
		    TLS = an optional flag which enables SSL/TLS
			services
		    true = an optional flag which requires that clients
			authenticate themselves.  This option requires
			that SSL/TLS support be enabled.

	    NOTE:  If you are connecting via a web brower to a
	    TLS socket, specify that the https protocol be used:

		e.g.  https://localhost:2001/dir1/file1

	    Otherwise, you may see unrecognized SSL handshake errors.

    client

	SSLSocketClient.java

	    This example demonstrates how to use a SSLSocket as a client to
	    send a HTTP request and get a response from an HTTPS server.
	    By default, this example connects to www.verisign.com, but
	    it can easily be adapted to connect to the ClassFileServer
	    above.  (Note:  The GET request must be slightly modified.
	    See above for more information.)

	    This application assumes the client is not behind a firewall.

	    USAGE:
		java SSLSocketClient

	SSLSocketClientWithClientAuth.java

	    This example is similar to SSLSocketClient above, but
	    this shows how to set up a key manager to do client
	    authentication if required by server.

	    This application also assumes the client is not behind a
	    firewall.

	    USAGE:
		java SSLSocketClientWithClientAuth host port requestedfilepath

	SSLSocketClientWithTunneling.java

	    This example illustrates how to do proxy Tunneling to access a
	    secure web server from behind a firewall.

	    The System properties "https.proxyHost" and "https.proxyPort"
	    are used to make a socket connection to the proxy host, and
	    then the SSLSocket is layered on top of that Socket.

	    USAGE:
		java SSLSocketClientWithTunneling

rmi

     Hello.java
     HelloImpl.java
     RMISSLClientSocketFactory.java
     RMISSLServerSocketFactory.java
     HelloClient.java

	This example illustrates how to use RMI over an SSL transport
	layer, using the JSSE.  The server will run HelloImpl, and the
	client will run HelloClient.

	The compilation is a little tricky, here are the necessary
	steps:

	    % javac *.java
	    % rmic HelloImpl
	    % rmiregistry
	    % java \
		-Djava.rmi.server.codebase="file:/current_working_dir/" \
		HelloImpl   (run in another window)
	    % java HelloClient (run in another window)

	Note the final trailing slash on the "java.rmi.server.codebase"
	parameter.  If the codebase is not specified properly, you may
	get an java.lang.ClassNotFoundException exception.

	Also note that the RMI security manager may be installed,
	and therefore, you will need to give it the appropriate
	network privilege:

	    permission java.net.SocketPermission "localhost:1099", "connect";
	

----------------------------------------------------------------------
Troubleshooting
----------------------------------------------------------------------
One of the most common problems people have in using JSSE is when the
JSSE receives a certificate that is unknown to the mechanism that makes
trust decisions.  If an unknown certificate is received, the trust
mechanism will throw an exception saying that the certificate is
untrusted.  Make sure that the correct trust KeyStore is being used,
and that the JSSE is installed and configured correctly.

In the Sun Reference Implementation, the exception error returned will
be:

	javax.net.ssl.SSLException: untrusted server cert chain

The SSL debug mechanism can be used to investigate such trust
problems.  See the implementation documentation for more information
about this subject.

In the SSLSocketClientWithClientAuth, if the server doesn't trust
the client's certificate(s), it may break the pipe, and therefore the
client may get a broken pipe error.