The Tomcat Servlet/JSP Container

Apache Tomcat 4

Apache Logo


Getting Started



Application Developers

Catalina Developers

Jasper Developers

SSL Configuration HOW-TO

Printer Friendly Version
Quick-Start Version

The description below uses the variable name $CATALINA_HOME to refer to the directory into which you have installed Tomcat 4, and is the base directory against which most relative paths are resolved. However, if you have configured Tomcat 4 for multiple instances by setting a CATALINA_BASE directory, you should use $CATALINA_BASE instead of $CATALINA_HOME for each of these references.

To install and configure SSL support on Tomcat 4, you need to follow these simple steps. For more information, read the rest of this HOW-TO.

  1. Download JSSE 1.0.2 (or later) from http://java.sun.com/products/jsse/ and either make it an installed extension on the system, or else set an environment variable JSSE_HOME that points at the directory into which you installed JSSE.

  2. Create a certificate keystore by executing the following command:





    and specify a password value of "changeit".

  3. Uncomment the "SSL HTTP/1.1 Connector" entry in $CATALINA_HOME/conf/server.xml and tweak as necessary.

Introduction to SSL



SSL and Tomcat






General Tips on Running SSL




Download and Install JSSE

Download the Java Secure Socket Extensions (JSSE) package, version 1.0.2 or later, from http://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.










  -keystore \path\to\my\keystore


  -keystore /path/to/my/keystore



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.)


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:

<-- Define an SSL HTTP/1.1 Connector on port 8443 -->
<Connector className="org.apache.catalina.connector.http.HttpConnector"
           port="8443" minProcessors="5" maxProcessors="75"
           clientAuth="false" protocol="TLS"

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.



You may need to add or change the following attribute values, depending on how you configured your keystore earlier:

Attribute Description
algorithm The certificate encoding algorithm to be used. If not specified, the default value is SunX509.
ciphers The comma separated list of encryption ciphers that this socket is allowed to use. By default, the default ciphers for the JVM will be used. Note that this usually means that the weak export grade ciphers will be included in the list of available ciphers. The ciphers are specified using the JSSE cipher naming convention.
clientAuth Set this value to true if you want Tomcat to require all SSL clients to present a client Certificate in order to use this socket. Set this value to want if you want Tomcat to request a client Certificate, but not fail if the user doesn't send a certificate (requires a 1.4.x JVM or higher).
keystoreFile Add 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.
keystorePass Add this element if you used a different keystore (and Certificate) password than the one Tomcat expects (changeit).
keystoreFile The type of keystore file to be used for the server certificate. If not specified, the default value is "JKS".
sslProtocol The version of the SSL protocol to use. If not specified, the default is "TLS".




Installing a Certificate from a Certificate Authority

To obstain and install a Certificate from a Certificate Authority (like verisign.com, thawte.com or trustcenter.de) you should have read the previous section and then follow these instructions:

Create a local Certificate Signing Request (CSR)


    keytool -genkey -alias tomcat -keyalg RSA \
    	-keystore <your_keystore_filename>
  • The CSR is then created with:
    	-keystore <your_keystore_filename>

Now you have a file called certreq.csr. The file is encoded in PEM format. You can submit it to the Certificate Authority (look at the documentation of the Certificate Authority website on how to do this). In return you get a Certificate.

Importing the Certificate


    For Verisign.com trial certificates go to: http://www.verisign.com/support/verisign-intermediate-ca/Trial_Secure_Server_Root/index.html For Trustcenter.de go to: http://www.trustcenter.de/certservices/cacerts/en/en.htm#server
  • Import the Chain Certificate into you keystore
    keytool -import -alias root -keystore <your_keystore_filename> \
    	-trustcacerts -file <filename_of_the_chain_certificate>
  • And finally import your new Certificate (It must be in X509 format):
    keytool -import -alias tomcat -keystore <your_keystore_filename> \
    	-trustcacerts -file <your_certificate_filename>


  • I get "java.security.NoSuchAlgorithmException" errors in my log files.

    The JVM cannot find the JSSE JAR files. Follow all of the directions to download and install JSSE.






Copyright © 1999-2009, Apache Software Foundation