Download
FAQ
History
HomeHomeNext API
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.

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.

Setting Up Digital Certificates

In order to use 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 J2SE. 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 keytool and public key cryptography, read the keytool documentation at the following URL:

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

Creating a Server Certificate

You use keytool to generate certificates. The keytool stores the keys and certificates in a file termed a keystore. A keystore is a repository of certificates used for identifying a client or a server. Typically, a keystore contains one client or one server's identity. The default keystore implementation implements the keystore as a file. It protects private keys with a password.

The keystores are created in the directory from which you run keytool. This can be the directory where the application resides or it can be a directory common to many applications.

To create a server certificate,

  1. Create the keystore. If you create a server certificate, you will reference it from the Tomcat deployment descriptor so that you can use SSL.
  2. Export the certificate from the keystore.
  3. Sign the certificate.
  4. Import the certificate into a trust-store. A trust-store is a repository of certificates used for verifying the certificates. A trust-store typically contains more than one certificate. An example using a trust-store for SSL-based mutual authentication is discussed in Client-Certificate Authentication over HTTP/SSL with JAX-RPC.

Run keytool to generate the server keystore, which we will name server-keystore.jks. This step uses the alias server-alias to generate a new public/private key pair and wrap the public key into a self-signed certificate inside server-keystore.jks. The key pair is generated using an algorithm of type RSA, with a default password of changeit. For more information on keytool options, see its online help at http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html.

From the directory where you want to create the keystore, run keytool with the following parameters. When you press Enter, keytool prompts you to enter the server name, organizational unit, organization, locality, state, and country code. Note that you must enter the server name in response to keytool's first prompt in which it asks for first and last names. For testing purposes, this may be localhost. The host specified in the keystore must match the host identified in the host variable specified in the <INSTALL>/jwstutorial12/examples/common/build.properties file, as specified in Edit the Build Properties.

  1. Generate the server certificate.
  2. <JAVA_HOME>\bin\keytool -genkey -alias server-alias -keyalg RSA -keypass changeit -storepass changeit
    -keystore keystore.jks

  3. Export the generated server certificate keystore.jks into the file server.cer.
  4. <JAVA_HOME>\bin\keytool -export -alias server-alias
    -storepass changeit -file server.cer -keystore keystore.jks

  5. If you want to have the certificate signed by a CA, read Signing Digital Certificates for more information.
  6. To create the trust-store file cacerts.jks and add the server certificate to the trust-store, run keytool from the directory where you created the keystore and server certificate with the following parameters:
  7. <JAVA_HOME>\bin\keytool -import -v -trustcacerts
    -alias server-alias -file server.cer
    -keystore cacerts.jks -keypass changeit
    -storepass changeit

    Information on the certificate, such as that shown below will display.

    <INSTALL>/jwstutorial12/examples/gs 60% keytool -import
    -v -trustcacerts -alias server-alias -file server.cer -keystore cacerts.jks -keypass changeit -storepass changeit
    Owner: CN=localhost, OU=Sun Micro, O=Docs, L=Santa Clara, ST=CA, C=US
    Issuer: CN=localhost, OU=Sun Micro, O=Docs, L=Santa Clara, ST=CA, C=US
    Serial number: 3e932169
    Valid from: Tue Apr 08
    Certificate fingerprints:
    MD5: 52:9F:49:68:ED:78:6F:39:87:F3:98:B3:6A:6B:0F:90
    SHA1: EE:2E:2A:A6:9E:03:9A:3A:1C:17:4A:28:5E:97:20:78:3F:
    Trust this certificate? [no]:

  8. Enter yes, then strike the Enter or Return key. The following information displays:
  9. Certificate was added to keystore
    [Saving cacerts.jks]

Signing Digital Certificates

Once you've created a digital certificate, you will want to have it signed by its owner. Once the digital certificate is cryptographically signed by its owner, it 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.

Obtaining a Digitally-Signed Certificate

This example assumes that the keystore is named keystore.jks, the certificate file is server.cer, and the CA file is cacerts.jks. To get your certificate digitally signed by a CA:

  1. Generate a Certificate Signing Request (CSR).
  2. keytool -certreq -alias server-alias -keyalg RSA
    -file <
    csr_filename> -keystore cacerts.jks

  3. Send the contents of the csr_filename for signing.
  4. 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.

Creating a Client Certificate for Mutual Authentication

This section discusses setting up client-side authentication. When both server and client-side authentication are enabled, this is called mutual, or two-way, authentication. In client authentication, clients are required to submit certificates that are issued by a certificate authority that you choose to accept. From the directory where you want to create the keystore, run keytool as outlined below. When you press Enter, keytool prompts you to enter the server name, organizational unit, organization, locality, state, and country code. Note that you must enter the server name in response to keytool's first prompt in which it asks for first and last names. For testing purposes, this may be localhost. The host specified in the keystore must match the host identified in the host variable specified in the <INSTALL>/jwstutorial12/examples/common/build.properties file, as specified in Edit the Build Properties.

To create a keystore named client-keystore.jks that contains a client certificate named client.cer, follow these steps:

  1. Generate the client certificate.
  2. <JAVA_HOME>\bin\keytool -genkey -alias client-alias -keyalg RSA -keypass changeit -storepass changeit
    -keystore keystore.jks

  3. Export the generated client certificate into the file client.cer.
  4. <JAVA_HOME>\bin\keytool -export -alias client-alias
    -storepass changeit -file client.cer -keystore keystore.jks

  5. Add the certificate to the trust-store file cacerts.jks. Run keytool from the directory where you created the keystore and client certificate with the following parameters:
  6. <JAVA_HOME>\bin\keytool -import -v -trustcacerts
    -alias client-alias -file client.cer
    -keystore cacerts.jks -keypass changeit
    -storepass changeit

    Keytool returns this message:

    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

For an example application that uses mutual authentication, see Client-Certificate Authentication over HTTP/SSL with JAX-RPC. For information on verifying that mutual authentication is running, see Verifying Mutual Authentication is Running.

Miscellaneous Commands for Certificates

Configuring the SSL Connector


Note: An SSL Connector needs to be configured for Tomcat.


Depending on your Web Server, an SSL HTTPS Connector may or may not be enabled. If you are using Tomcat, an SSL connector needs to be configured, and this section describes how to do so. 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. Also, in order to use SSL you must also add information about where to locate the keystore file and what it's password is to the deployment descriptor. To enable the SSL connector for Tomcat and add the information about the keystore, follow these steps:

  1. Shut down the server. If you don't know how to do this, refer to the section Shutting Down Tomcat.
  2. Enable or add an SSL HTTPS Connector to your Web server using either of these two methods:
    • Add the Connector using admintool. See the documentation for admintool for more information on how to do this.
    • Add a Connector element for an SSL connector to the server's deployment descriptor.
    • To enable the Connector element for Tomcat, find the following section in the file <JWSDP_HOME>/conf/server.xml, remove the comment tags surrounding it, and add the code in bold to specify the keystore information.

      <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
      <!-- REMOVE the comment tag on the next line-->
      <!--
      <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
      <Connector           className="org.apache.coyote.tomcat5.CoyoteConnector"
          port="8443" minProcessors="5" maxProcessors="75"
          enableLookups="true" disableUploadTimeout="true"
          acceptCount="100" debug="0" scheme="https"
          secure="true">
      <Factory className=
          "org.apache.coyote.tomcat5.CoyoteServerSocketFactory"
        keystoreFile="<path_to_keystore>/keystore.jks"
        keystorePass="changeit"
          clientAuth="false" protocol="TLS" />
      </Connector>
      <!-- REMOVE the comment tag on the line below-->
      -->

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 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. The certificates will only display the first time. When you accept the certificates, subsequent hits to this site assume that you still trust the content.

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.

Enabling Mutual Authentication Over SSL

This section discusses setting up client-side authentication. When both server and client-side authentication are enabled, this is called mutual, or two-way, authentication. In client authentication, clients are required to submit certificates that are issued by a certificate authority that you choose to accept. There are at least two ways to enable client authentication.

When client authentication is enabled in both ways mentioned above, client authentication will be performed twice.

Verifying Mutual Authentication is Running

You can verify that mutual authentication is working by obtaining debug messages. This should be done at the client end, and this example shows how to pass a system property in targets.xml so that targets.xml forks a client with javax.net.debug in its system properties, which could be added in a file such as <INSTALL>/jwstutorial12/examples/common/targets.xml.

To enable debug messages for SSL mutual authentication, pass the system property javax.net.debug=ssl,handshake, which will provide information on whether mutual authentication is working or not. This can be done by adding the sysproperty to targets.xml file as shown in bold:

<java 
  fork="on" 
  classpath="${dist}/${client-jar}:${jwsdp-path}" 
  classname="${client-class}" >
  <arg value="${trustStore}" />
  <arg value="${trustStorePassword}" />
  <arg value="${key-store}" />
  <arg value="${key-store-password}" />
  <sysproperty key="javax.net.debug"
    value="ssl,handshake" />
  <sysproperty key="javax.net.ssl.keyStore" 
    value="${key-store}" />
  <sysproperty key="javax.net.ssl.keyStorePassword"
    value="${key-store-password}" /
</java> 
Divider
Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

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