Download FAQ History |  | API Search Feedback

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

> - A server certificate keystore (see Setting Up Digital Certificates).
> - An HTTPS connector (see Configuring the SSL Connector).

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

> `<``JAVA_HOME``>\bin\keytool -genkey -alias server-alias -keyalg RSA -keypass changeit -storepass changeit
> -keystore keystore.jks`

> 2. Export the generated server certificate `keystore.jks` into the file `server.cer`.

> `<``JAVA_HOME``>\bin\keytool -export -alias server-alias
> -storepass changeit -file server.cer -keystore keystore.jks`

> 3. If you want to have the certificate signed by a CA, read Signing Digital Certificates for more information.
> 4. 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:

> `<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]:`

> 5. Enter `yes`, then strike the `Enter` or `Return` key. The following information displays:

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

> `keytool -certreq -alias server-alias -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.

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

> `<``JAVA_HOME``>\bin\keytool -genkey -alias client-alias -keyalg RSA -keypass changeit -storepass changeit
> -keystore keystore.jks`

> 2. Export the generated client certificate into the file `client.cer`.

> `<``JAVA_HOME``>\bin\keytool -export -alias client-alias
> -storepass changeit -file client.cer -keystore keystore.jks`

> 3. 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:

> `<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

> - To check the contents of a keystore that contains a certificate with an alias `server`:

> `keytool -list -keystore keystore.jks -alias server -v`

> - To check the contents of the `cacerts` file:

> `keytool -list -keystore cacerts.jks`

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

> - Configure the SSL Socket Factory in the `<``JWSDP_HOME``>/conf/server.xml` file by adding and setting the `keystoreFile` and `keystorePass` properties, as shown. As with all changes to the Web server configuration file, you must stop and restart the Web server for this change to become effective.

> `<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"
> debug="0" />
> </Connector>`

> In addition to setting these properties, if you enable client authentication by setting the `clientAuth` property to`"true"`, client authentication will be required for all the requests going through the specified SSL port.

> - Set the method of authentication in the `web.xml` file to `CLIENT-CERT`, as shown below. By enabling client authentication in this way, client authentication is enabled for a specific application.

> `<login-config>
> <auth-method>CLIENT-CERT</auth-method>
> </login-config>`

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

Download FAQ History |  | API Search Feedback

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.