FAQ
History 		PreviousHomeNext Search
Feedback
Divider

Installing and Configuring SSL Support

What is Secure Socket Layer Technology?

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. SSL addresses the following important security considerations.

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

Confidentiality

When data is being passed between the client and server on a network, third parties can view and intercept this data. SSL responses are encrypted so that the data cannot be deciphered by the third-party and the data remains confidential.

Integrity

When data is being passed between the client and server on a network, third parties can view and intercept this data. SSL helps guarantee that the data will not be modified in transit by that third party.

To install and configure SSL support on your stand-alone Web server, you need the following components. The following sections discuss enabling SSL support for Tomcat specifically. If you are using a different Web server, consult the documentation for your product.

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

Using JSSE

If you are using J2SE SDK v1.3.1, you need to have Java Secure Socket Extension (JSSE) installed in order to use SSL. JSSE is a part of the J2SE 1.4 SDK. 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 <JAVA_HOME>/jre/lib/jsse.jar. For more information on JSSE, see its Web site at http://java.sun.com/products/jsse/.

Setting Up Digital Certificates

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

SSL uses public key cryptography, which is based on key pairs. Key pairs contain one public key and one private key. If data is encrypted with one key, it can only be decrypted with the other key of the pair. This property of is fundamental to establishing trust and privacy in transactions. For example, using SSL, the server computes a value and encrypts the value using its private key. The encrypted value is called a digital signature. The client decrypts the encrypted value using the server's public key and compares the value to its own computed value. If the two values match, the client can trust that the signature is authentic since only the private key could have been used to produce such a signature.

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

One tool that can be used to set up a digital certificate is keytool, a key and certificate management utility that ships with the J2SE 1.4 SDK. 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. For a better understanding of public key cryptography, read the keytool documentation at

http://java.sun.com/j2se/1.4.1/docs/tooldocs/solaris/keytool.html

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 file termed a 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.1/docs/tooldocs/solaris/keytool.html

This section describes creating a server keystore called server.keystore and a client keystore called the client.keystore. The two files make a key pair. These files are usually created in either your <HOME> directory or in the application directory.

In addition to the server and client keystores, you must have a signed certificate, which must be present on the server. This file must contain the public key certificates of the Certificate Authority or the client's public key certificate at the time the server is authenticating the client. We will create the server.cer file in the <HOME> directory.

Typically, a keystore file is protected by a password. The default value for this password is changeit for server.keystore, client.keystore, and server.cer files.

To create a keystore file, we use the keytool utility. The keytool utility can be found in the <JAVA_HOME>/bin directory.

To set up a digital certificate,

  1. Generate a key pair.

    2. The keytool utility enables you to generate the key pair. The keytool utility that ships with the J2SE SDK 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 keystore file, run the keytool utility as follows, replacing <keystore_filename> with the name of your keystore file, for example, server.keystore. If you are using the Tomcat server, the file must either be named .keystore and located in the home directory of the machine on which Tomcat is running, or you will need to tell Tomcat where the kestore file is by adding a keystoreFile attribute to the <Factory> element in the Tomcat configuration file or by specifying the location of the file on the Connector (8443) node of admintool. 

       keytool -genkey -keyalg RSA -alias tomcat-server
    -keystore <keystore_filename>
  2. The keytool utility prompts you for the following information:
    1. Keystore password--Enter the default password, which is changeit. Refer to the keytool documentation for information on changing the password.
    2. First and last name--Enter the appropriate value, for example, JWSDP.
    3. Organizational unit--Enter the appropriate value, for example, Java Web Services.
    4. Organization--Enter the appropriate value, for example, Sun Microsystems.
    5. City or locality--Enter the appropriate value, for example, Santa Clara.
    6. State or province--Enter the unabbreviated name, for example, CA.
    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 the Web server--Do not enter a password. Press Return.

The next step is generate a signed certificate for this keystore. A self-signed certificate is acceptable for most SSL communication. If you are using a self-signed certificate, continue with Creating a Self-Signed Certificate. If you'd like to have your certificate digitally signed by a CA, continue with Obtaining a Digitally-Signed Certificate.

Creating a Self-Signed Certificate

This example assumes that the keystore is named server.keystore, the certificate file is server.cer, and the CA file is cacerts.jks. Run these commands in your <HOME> directory so that they are created there.

  1. Export the server certificate to a certificate file:

    2. keytool -keystore server.keystore -export -alias tomcat-server -file server.cer

  2. Enter the password (changeit).

    3. Keytool returns the following message:

    Certificate stored in file <server.cer>

  3. Import the new server certificate into the Certificate Authority file cacerts.jks:

    4. keytool -import -alias serverCA -keystore <HOME>/cacerts.jks
    -file server.cer

  4. Enter the password (changeit).

    5. Keytool returns a message similar to the following:

    Owner: CN=JWSDP, OU=Java Web Services, O=Sun, L=Santa Clara,
    ST=CA, C=US
    Issuer: CN=JWSDP, OU=Java Web Services, O=Sun, L=Santa Clara,
    ST=CA, C=US
    Serial number: 3e39e3e0
    Valid from: Thu Jan 30 18:48:00 PST 2003 until: Wed Apr 30 19:48:00 PDT 2003
    Certificate fingerprints:
    MD5: 44:89:AF:54:FE:79:66:DB:0D:BE:DC:15:A9:B6:09:84
    SHA1:21:09:8A:F6:78:E5:C2:19:D5:FF:CB:DB:AB:78:9B:98:8D:06:8C:71
    Trust this certificate? [no]: yes
    Certificate was added to keystore

Obtaining a Digitally-Signed Certificate

This example assumes that the keystore is named server.keystore, the certificate file is server.cer, and the CA file is cacerts.jks.

  1. Get your certificate digitally signed by a CA. To do this,
    1. Generate a Certificate Signing Request (CSR).

      2. keytool -certreq -alias tomcat-server -keyalg RSA
      -file <csr_filename> -keystore cacerts.jks

    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 e-mail. Store this certificate in a file.
    4. Import the signed certificate that you received in email into the server:

      5. keytool -import -alias tomcat-server -trustcacerts -file
      <signed_cert_file> -keystore <keystore_filename>

  2. Import the certificate (if using a CA-signed certificate).

    3. 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 install the CA certificate in the Java 2 Platform, Standard Edition, run the keytool utility as follows.

    keytool -import -trustcacerts -alias root
      -file <ca-cert-filename> -keystore <keystore-filename>

Creating a Client Certificate for Mutual Authentication

Creating a client certificate is similar to the procedure for server certificates.

  1. Use keytool to create a client certificate in a keystore file of your choice:

    2. keytool -genkey -keyalg RSA -alias jwsdp-client -keystore client.keystore

    You will be prompted for a password. Enter changeit, the default password. When requested enter the name, organization, and other prompts for the client. Do not enter anything at "Key password for <client>", just press Return.

  2. Export the new client certificate from the keystore to a certificate file:

    3. keytool -keystore client.keystore -export -alias jwsdp-client -file client.cer

  3. Enter the keystore password (changeit). Keytool returns this message:
    4. Certificate stored in file <client.cer>
  4. Import the new client certificate into the server's Certificate Authority file cacerts.jks. This allows the server to trust the client during SSL mutual authentication.

    5. keytool -import -alias root -keystore <HOME>/cacerts.jks
    -file client.cer

  5. Enter the keystore password (changeit). Keytool returns this message:

    6. Owner: CN=JWSDP Client, OU=Java Web Services, O=Sun, L=Santa Clara, ST=CA, C=US
    Issuer: CN=JWSDP Client, OU=Java Web Services, O=Sun, L=Santa Clara, ST=CA, C=US
    Serial number: 3e39e66a
    Valid from: Thu Jan 30 18:58:50 PST 2003 until: Wed Apr 30
    19:58:50 PDT 2003
    Certificate fingerprints:
    MD5: 5A:B0:4C:88:4E:F8:EF:E9:E5:8B:53:BD:D0:AA:8E:5A
    SHA1:90:00:36:5B:E0:A7:A2:BD:67:DB:EA:37:B9:61:3E:26:B3:89:46:
    32
    Trust this certificate? [no]: yes
    Certificate was added to keystore

Checking That Mutual Authentication is Running

To prove that the SSL handshaking is occurring, shutdown Tomcat, set the debug flag in the file <JWSDP_HOME>/bin/catalina.bat, then restart Tomcat. The server will display the handshake messages, or write them to the file <JWSDP_HOME>/logs/launcher.server.log. The following example shows the new code in bold. 

rem Execute the Tomcat launcher
"%JAVA_HOME%\bin\java.exe" -Djavax.net.debug=ssl,handshake
-classpath %PRG%\..;%PRG%\..\..\jwsdp-shared\bin;"%PRG%

Using a PKCS12 Certificate in the Tomcat Server

The Java WSDP supports PKCS12-format certificates. PKCS12 standard specifies a portable format for storing or transporting a user's private keys, certificates, miscellaneous secrets, etc. See the following Web site for additional information: 

http://www.rsasecurity.com/rsalabs/pkcs/pkcs-12

If you have a PKCS12-format certificate, you must convert it into JKS format. The command for the conversion is: 

keytool -pkcs12 -pkcsFile <fileName> -pkcsKeyStorePass
<password> -pkcsKeyPass <password> -jksFile <outputFileName>
-jksKeyStorePass <password>

The result is a JKS file that has the key - private key and the certificate chain - in the file.

To export the certificate into a file, such as abc.cer, use keytool with the
-export option: 

keytool -keystore <outputFileName> -export -alias <server> 
-file abc.cer

Miscellaneous Commands for Certificates

Configuring the SSL Connector

Depending on your Web Server, an SSL HTTPS Connector may or may not be enabled. If you are using the Tomcat server, an SSL connector is not configured. This section describes how to configure the SSL HTTPS Connector for Tomcat. If you are using another Web Server, consult the documentation for that server.

A Connector element for an SSL connector must be included in the server deployment descriptor. Before making changes to the server deployment descriptor, you must shut down the server. The following code is an example of code that will enable an SSL Connector for a Web server: 

<Connector
   className="org.apache.coyote.tomcat5.CoyoteConnector"
   port="8443" minProcessors="5" maxProcessors="75"
   enableLookups="true" acceptCount="10" debug="0"
   scheme="https" secure="true" useURIValidationHack="false">
<Factory className="com.sun.web.security.SSLSocketFactory"
   clientAuth="false" protocol="TLS" debug="0" /> 
</Connector>

The attributes in this Connector element are described in more detail in the documentation for the Tomcat Server Administration Tool in Appendix A. You can add an SSL HTTPS Connector to Tomcat using either of these two 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 Digital Certificates. 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.

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

    4.   <!-- 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 documentation.

Verifying SSL Support

For testing purposes, and to verify that SSL support has been correctly installed, load the default introduction page with a URL that connects to port defined in the server deployment descriptor: 

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.

General Tips on Running SSL

The SSL protocol is designed to be as efficient as securely possible. However, encryption/decryption is a computationally expensive process from a performance standpoint. It is not strictly necessary to run an entire Web application over SSL, and it is customary for a developer to decide which pages require a secure connection and which do not. Pages that might require a secure connection include login pages, personal information pages, shopping cart checkouts, or any pages where credit card information could possibly be transmitted. Any page within an application can be requested over a secure socket by simply prefixing the address with https: instead of http:. Any pages which absolutely require a secure connection should check the protocol type associated with the page request and take the appropriate action if https: is not specified.

Using name-based virtual hosts on a secured connection can be problematic. This is a design limitation of the SSL protocol itself. The SSL handshake, where the client browser accepts the server certificate, must occur before the HTTP request is accessed. As a result, the request information containing the virtual host name cannot be determined prior to authentication, and it is therefore not possible to assign multiple certificates to a single IP address. If all virtual hosts on a single IP address need to authenticate against the same certificate, the addition of multiple virtual hosts should not interfere with normal SSL operations on the server. Be aware, however, that most client browsers will compare the server's domain name against the domain name listed in the certificate, if any (applicable primarily to official, CA-signed certificates). If the domain names do not match, these browsers will display a warning to the client. In general, only address-based virtual hosts are commonly used with SSL in a production environment.

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.

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
FAQ
History 		PreviousHomeNext Search
Feedback
Divider

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.