Java(tm) Secure Socket Extension for the JavaTM 2 SDK, Standard Edition, v 1.4 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. J2SDK: http://java.sun.com/doc/ JSSE: Documentation for the JSSE API can be found in Sun's J2SDK implementation or documentation bundles, or at http://java.sun.com/j2se/1.4/docs/guide/security/jsse/JSSERefGuide.html If you use a JSSE implementation from a vendor other than Sun, also consult that 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 J2SDK implementation. (If another KeyStore format is desired, the J2SDK will need to be configured to recognize the new default format.) The remainder of this document assumes the Sun implementations of J2SDK 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 J2SDK 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: /lib/security/jssecacerts or: /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 J2SDK 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 J2SDK utility "keytool" can be used to generate certificates and keystore files. If you are using the Sun implementations of the J2SDK and JSSE, you will configure the system to use the proper trustStore. Please see the J2SDK and JSSE documentation for more information about how to specify trustStores. IMPORTANT NOTE: Verify Your cacerts File Since you trust the CAs in the cacerts file as entities for signing and issuing certificates to other entities, you must manage the cacerts file carefully. The cacerts file should contain only certificates of the CAs you trust. It is your responsibility to verify the trusted root CA certificates bundled in the cacerts file and make your own trust decisions. To remove an untrusted CA certificate from the cacerts file, use the delete option of the keytool command. You can find the cacerts file in the JRE installation directory. Contact your system administrator if you do not have permission to edit this file. 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.) 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 / 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: Couldn't find trusted certificate The SSL debug mechanism can be used to investigate such trust problems. See the implementation documentation for more information about this subject.