Download and Install JSSE
Download the Java Secure Socket Extensions (JSSE) package, version 1.0.2 or later, fromhttp://java.sun.com/products/jsse/. If you built Tomcat from source, you have probably already downloaded this package. If you are running JDK 1.4 (currently in beta), these classes have been integrated directly into the JDK, so you can skip this entire step.
After expanding the package, there are two ways to make it available to Tomcat (choose one or the other):
- Make JSSE an installed extension by copying all three JAR files (
jcert.jar, jnet.jar, and jsse.jar) into your $JAVA_HOME/jre/lib/ext directory. - Create a new environment variable
JSSE_HOME that contains the absolute path to the directory into which you unpacked the JSSE binary distribution.
Prepare the Certificate Keystore
Tomcat currently operates only on JKS format keystores. This is Java's standard "Java KeyStore" format, and is the format created by the keytool command-line utility. This tool is included in the JDK.
To import an existing certificate into a JKS keystore, please read the documentation (in your JDK documentation package) about keytool.
To create a new keystore from scratch, containing a single self-signed Certificate, execute the following from a terminal command line:
Windows:
Unix:
(The RSA algorithm should be preferred as a secure algorithm, and this also ensures general compatibility with other servers and components.)
This command will create a new file, in the home directory of the user under which you run it, named ".keystore". To specify a different location or filename, add the -keystore parameter, followed by the complete pathname to your keystore file, to the keytool command shown above. You will also need to reflect this new location in the server.xml configuration file, as described later. For example:
Windows:
Unix:
After executing this command, you will first be prompted for the keystore password. The default password used by Tomcat is "changeit" (all lower case), although you can specify a custom password if you like. You will also need to specify the custom password in the server.xml configuration file, as described later.
Next, you will be prompted for general information about this Certificate, such as company, contact name, and so on. This information will be displayed to users who attempt to access a secure page in your application, so make sure that the information provided here matches what they will expect.
Finally, you will be prompted for the key password, which is the password specifically for this Certificate (as opposed to any other Certificates stored in the same keystore file). You MUST use the same password here as was used for the keystore password itself. (Currently, the keytool prompt will tell you that pressing the ENTER key does this for you automatically.)
If everything was successful, you now have a keystore file with a Certificate that can be used by your server.
Edit the Tomcat Configuration File
The final step is to configure your secure socket in the $CATALINA_HOME/conf/server.xml file, where$CATALINA_HOME represents the directory into which you installed Tomcat 4. An example <Connector> element for an SSL connector is included in the default server.xml file installed with Tomcat. It will look something like this:
You will note that the Connector element itself is commented out by default, so you will need to remove the comment tags around it. Then, you can customize the specified attributes as necessary. For detailed information about the various options, consult the Server Configuration Reference. The following discussion covers only those attributes of most interest when setting up SSL communication.
The port attribute (default value is 8443) is the TCP/IP port number on which Tomcat will listen for secure connections. You can change this to any port number you wish (such as to the default port forhttps communications, which is 443). However, special setup (outside the scope of this document) is necessary to run Tomcat on port numbers lower than 1024 on many operating systems.
If you change the port number here, you should also change the value specified for theredirectPort attribute on the non-SSL connector. This allows Tomcat to automatically redirect users who attempt to access a page with a security constraint specifying that SSL is required, as required by the Servlet 2.3 Specification.
You will notice a Factory element nested inside the Connector element. This is where the "socket factory" used by Tomcat, whenever it needs a socket on the corresponding port number, is configured. You may need to add or change the following attribute values, depending on how you configured your keystore earlier:
AttributeDescriptionclassNameThe fully qualified class name of the Java class that implements this socket factory. Do not change the default value.clientAuthSet this value to true if you want Tomcat to require all SSL clients to present a client Certificate in order to use this socket.keystoreFileAdd this attribute if the keystore file you created is not in the default place that Tomcat expects (a file named .keystore in the user home directory under which Tomcat is running). You can specify an absolute pathname, or a relative pathname that is resolved against the $CATALINA_BASE environment variable.keystorePassAdd this element if you used a different keystore (and Certificate) password than the one Tomcat expects (changeit).protocolThe encryption/decryption protocol to be used on this socket. Do not change the default value.
After completing these configuration changes, you must restart Tomcat as you normally do, and you should be in business. You should be able to access any web application supported by Tomcat via SSL. For example, try:
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
and you should see the usual Tomcat splash page (unless you have modified the ROOT web application). If this does not work, the following section contains some troubleshooting tips.
