The JavaTM Web Services Tutorial
Home
TOC
Index 		PREV TOP NEXT
Divider

Installing and Configuring SSL Support on Tomcat

Secure Socket Layer (SSL) is a technology that allows Web browsers and Web servers to communicate over a secured connection. In this secure connection, the data that is being sent is encrypted before being sent, then decrypted upon receipt and prior to processing. Both the browser and the server encrypt all traffic before sending any data.

Another important aspect of the SSL protocol is authentication. During your initial attempt to communicate with a Web server over a secure connection, that server will present your Web browser with a set of credentials in the form of a server certificate. The purpose of the certificate is to verify that the site is who and what it claims to be. In some cases, the server may request a certificate that the client is who and what it claims to be (which is known as client authentication).

You only need to configure Tomcat to take advantage of SSL support when you are planning on running it as a stand-alone Web server. When you are planning to run Tomcat primarily as a JSP and Java Servlet container behind another Web server, such as Apache or Microsoft IIS, it is usually necessary to configure the primary Web server to handle the SSL connections from users. The communications between the primary Web server and Tomcat do not need to be encrypted.

To install and configure SSL support on Tomcat, you need

To verify that SSL support is enabled, see Verifying SSL Support.

Using JSSE

You need to have Java Secure Socket Extension (JSSE) installed in order for Tomcat to use SSL. JSSE is integrated into the Java WSDP 1.0. JSSE is a set of Java packages that enable secure Internet communications. These packages implement a Java version of SSL (Secure Sockets Layer) and TLS (Transport Layer Security) protocols and include functionality for data encryption, server authentication, message integrity, and optional client authentication. Using JSSE, developers can provide for the secure passage of data between a client and a server running any application protocol (such as HTTP, Telnet, NNTP, and FTP) over TCP/IP.

By default, the location of the jsse.jar file is <JWSDP_HOME>/common/lib/jsse.jar. For more information on JSSE, see its Web site at http://java.sun.com/products/jsse/index-102.html.

Setting Up a Server Certificate

In order to implement SSL, a Web server must have an associated certificate for each external interface, or IP address, that accepts secure connections. The theory behind this design is that a server should provide some kind of reasonable assurance that its owner is who you think it is, particularly before receiving any sensitive information. It may be useful to think of a certificate as a "digital driver's license" for an Internet address. It states with which company the site is associated, along with some basic contact information about the site owner or administrator.

The certificate is cryptographically signed by its owner and is difficult for anyone else to forge. For sites involved in e-commerce, or any other business transaction in which authentication of identity is important, a certificate can be purchased from a well-known Certificate Authority (CA) such as Verisign or Thawte.

If authentication is not really a concern, such as if an administrator simply wants to ensure that data being transmitted and received by the server is private and cannot be snooped by anyone eavesdropping on the connection, you can simply save the time and expense involved in obtaining a CA certificate and simply use a self-signed certificate.

Certificates are used with the HTTPS protocol to authenticate Web clients. The HTTPS service of the Tomcat server will not run unless a server certificate has been installed. Use the procedure outlined below to set up a server certificate that can be used by Tomcat to enable SSL.

One tool that can be used to set up a Tomcat server certificate is keytool, a key and certificate management utility. It enables users to administer their own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates himself/herself to other users/services) or data integrity and authentication services, using digital signatures. It also allows users to cache the public keys (in the form of certificates) of their communicating peers.

A certificate is a digitally-signed statement from one entity (person, company, etc.), saying that the public key (and some other information) of some other entity has a particular value. When data is digitally signed, the signature can be verified to check the data integrity and authenticity. Integrity means that the data has not been modified or tampered with, and authenticity means the data indeed comes from whoever claims to have created and signed it.

The keytool stores the keys and certificates in a so-called keystore. The default keystore implementation implements the keystore as a file. It protects private keys with a password. For more information on keytool, read its documentation at http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/keytool.html.

  1. Generate a key pair and a self-signed certificate.
    The keytool utility enables you to create the certificate. The keytool utility that ships with the J2SE SDK version programmatically adds a Java Cryptographic Extension provider that has implementations of RSA algorithms. This provider enables you to import RSA-signed certificates.
    To generate the certificate, run the keytool utility as follows, <keystore_filename> with the name of your keystore file: 
       keytool -genkey -keyalg RSA -alias tomcat
    -keystore <keystore_filename>
Note: Tomcat is looking for the keystore to have the name .keystore in the home directory of the machine on which Tomcat is running.
  1. The keytool utility prompts you for the following information:
    1. Keystore password--Enter a password. (You may want to use changeit to be consistent with the default password of the J2SE SDK keystore.)
    2. First and last name--Enter the fully-qualified name of your server. This fully-qualified name includes the host name and the domain name. For testing purposes on a single machine, this will be localhost.
    3. Organizational unit--Enter the appropriate value.
    4. Organization--Enter the appropriate value.
    5. City or locality--Enter the appropriate value.
    6. State or province--Enter the unabbreviated name.
    7. Two-letter country code--For the USA, the two-letter country code is US.
    8. Review the information you've entered so far, enter Yes if it is correct.
    9. Key password for Tomcat--Do not enter a password. Press Return.

A self-signed certificate is acceptable for most SSL communication. If you are using a self-signed certificate, skip to Configuring the SSL Connector. If you'd like to have your certificate digitally signed by a CA, continue with Obtaining a Digitally-Signed Certificate.

Obtaining a Digitally-Signed Certificate

  1. Get your certificate digitally signed by a CA. To do this,
    1. Generate a Certificate Signing Request (CSR). 
           keytool -certreq -alias tomcat -keyalg RSA
      -file <csr_filename> -keystore <keystore_filename>
    2. Send the contents of the <csr_filename> for signing.
    3. If you are using Verisign CA, go to http://digitalid.verisign.com/. Verisign will send the signed certificate in email. Store this certificate in a file.
    4. Import the signed certificate that you received in email into the server: 
           keytool -import -alias root -trustcacerts -file 
      <signed_cert_file> -keystore <keystore_filename>
  2. Import the certificate (if using a CA-signed certificate).
    If your certificate will be signed by a Certification Authority (CA), you must import the CA certificate. You may skip this step if you are using only the self-signed certificate. If you are using a self-signed certificate or a certificate signed by a CA that your browser does not recognize, a dialog will be triggered the first time a user tries to access the server. The user can then choose to trust the certificate for this session only or permanently.
    To import the certificate, perform these tasks:
    1. Request the CA certificate from your CA. Store the certificate in a file.
    2. To install the CA certificate in the Java 2 Platform, Standard Edition, run the keytool utility as follows. (You must have the required permissions to modify the $JAVA_HOME/jre/lib/security/cacerts file.) 
           keytool -import -trustcacerts -alias tomcat 
      -file <ca-cert-filename> -keystore <keystore-filename>

Configuring the SSL Connector

By default, an SSL HTTPS Connector is not enabled. You can enable and configure an SSL HTTPS Connector on port 8443 using either of the following methods:

Adding an SSL Connector in admintool

To configure an SSL Connector using admintool, you must first have created a keystore as described in Setting Up a Server Certificate. Tomcat will be looking for a keystore file named .keystore in the home directory of the machine on which Tomcat is running. When you have verified that you have created the keystore file, follow these steps.

  1. Start Tomcat, if you haven't already done so.
  2. Start admintool by entering http://localhost:8080/admin in a Web browser.
  3. Enter a user name and password combination that is assigned the role of admin.
  4. Select Service (Java Web Services Developer Pack) in the left pane.
  5. Select Create New Connector from the drop-down list in the right pane.
  6. In the Type field, select HTTPS.
  7. In the Port field, enter 8443 (or whatever port you require). This defines the TCP/IP port number on which Tomcat will listen for secure connections.
  8. Enter the Keystore Name and Keystore Password if you have created a keystore named something other than .keystore, if .keystore is located in a directory other than the home directory of the machine on which Tomcat is running, or if the password is something other than the default value of changeit. If you have used the expected values, you can leave these fields blank.
    The home directory is generally /home/user_name on Unix and Linux systems, and C:\Documents and Settings\user_name on Microsoft Windows systems.
  9. Select Save to save the new Connector for this session.
  10. Select Commit Changes to write the new Connector information to the server.xml file so that it is available the next time Tomcat is started.

To view and/or edit the newly-created Connector, expand the Service (Java Web Services Developer Pack) node, and select Connector (8443).

Configuring the SSL Connector in server.xml

An example Connector element for an SSL connector is included in the default server.xml. This Connector element is commented out by default. To enable the SSL Connector for Tomcat, remove the comment tags around the SSL Connector element. To do this, follow these steps.

  1. Shutdown Tomcat, if it is running. Changes to the file <JWSDP_HOME>/conf/server.xml are read by Tomcat when it is started.
  2. Open the file <JWSDP_HOME>/conf/server.xml in a text editor.
  3. Find the following section of code in the file (try searching for SSL Connector). Remove comment tags around the Connector entry. The comment tags that are to be removed are shown in bold below. 
      <!-- SSL Connector on Port 8443 -->
   
  <!--
    <Connector
      className="org.apache.coyote.tomcat4.CoyoteConnector"
      port="8443" minProcessors="5" 
      maxProcessors="75"
      enableLookups="false"
      acceptCount="10" 
      connectionTimeout="60000" debug="0"
      scheme="https" secure="true">
    <Factory
      className="org.apache.coyote.tomcat4.
             CoyoteServerSocketFactory"
             clientAuth="false" protocol="TLS" />
    </Connector>
  -->
  4. Save and close the file.
  5. Start Tomcat.

The attributes in this Connector element are outlined in more detail in Tomcat Administration Tool.

Verifying SSL Support

For testing purposes, and to verify that SSL support has been correctly installed on Tomcat, load the default Tomcat introduction page with the following URL: 

https://localhost:8443/

The https in this URL indicates that the browser should be using the SSL protocol. The port of 8443 is where the SSL Connector was created in the previous step.

The first time a user loads this application, the New Site Certificate dialog displays. Select Next to move through the series of New Site Certificate dialogs, select Finish when you reach the last dialog.

Troubleshooting SSL Connections

When Tomcat starts up, I get an exception like "java.io.FileNotFoundException: {some-directory}/{some-file} not found".

A likely explanation is that Tomcat cannot find the keystore file where it is looking. By default, Tomcat expects the keystore file to be named .keystore, and to be located in the home directory on the system under which Tomcat is running (which may or may not be the same as yours). If the keystore file is anywhere else, you will need to add a keystoreFile attribute to the <Factory> element in the Tomcat configuration file or specify the location of the file on the Connector (8443) node of admintool.

When Tomcat starts up, I get an exception like "java.io.FileNotFoundException: Keystore was tampered with, or password was incorrect".

Assuming that someone has not actually tampered with your keystore file, the most likely cause is that Tomcat is using a different password than the one you used when you created the keystore file. To fix this, you can either go back and recreate the keystore file, or you can add or update the keystorePass attribute on the <Factory> element in the Tomcat configuration file or on the Connector (8443) node of admintool. REMINDER - Passwords are case sensitive!

If you are still having problems,

If you are still having problems, a good source of information is the TOMCAT-USER mailing list. You can find pointers to archives of previous messages on this list, as well as subscription and unsubscription information, at http://jakarta.apache.org/site/mail.html.

General Tips on Running SSL

Further information on SSL

For more information, please read the Tomcat document SSL Configuration HOW-TO, located at <JWSDP_HOME>/docs/tomcat/ssl-howto.html.

Divider
Home
TOC
Index 		PREV TOP NEXT
Divider

This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.

All of the material in The Java Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.