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 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 ofkeytool
and public key cryptography, read thekeytool
documentation at the following URL:
http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html
Creating a Server Certificate
You can use
keytool
to generate certificates. Thekeytool
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,
- Create the keystore. If you create a server certificate, you will reference it from the Tomcat deployment descriptor so that you can use SSL.
- Export the certificate from the keystore.
- Sign the certificate.
- 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 Example: Client-Certificate Authentication over HTTP/SSL with JAX-RPC.
Run
keytool
to generate the server keystore, which we will nameserver-keystore.jks
. This step uses the aliasserver-alias
to generate a new public/private key pair and wrap the public key into a self-signed certificate insideserver-keystore.jks
. The key pair is generated using an algorithm of type RSA, with a default password ofchangeit
. For more information onkeytool
options, see its online help athttp://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 tokeytool
's first prompt in which it asks for first and last names. For testing purposes, this may belocalhost
. The host specified in the keystore must match the host identified in thehost
variable specified in the<
INSTALL
>/jwstutorial13/examples/common/build.properties
.
- Generate the server certificate.
<
JAVA_HOME
>\bin\keytool -genkey -alias server-alias
-keyalg RSA -keypass changeit -storepass changeit
-keystore keystore.jks- Export the generated server certificate in
keystore.jks
into the fileserver.cer
.
<
JAVA_HOME
>\bin\keytool -export -alias server-alias
-storepass changeit -file server.cer -keystore keystore.jks- If you want to have the certificate signed by a CA, read Signing Digital Certificates for more information.
- To create the trust-store file
cacerts.jks
and add the server certificate to the trust-store, runkeytool
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 changeitInformation on the certificate, such as that shown below will display.
<
INSTALL
>/jwstutorial13/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]:- Enter
yes
, then strike theEnter
orReturn
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 the self-signed certificate.
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 client certificate, 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 tokeytool
's first prompt in which it asks for first and last names. For testing purposes, this may belocalhost
. The host specified in the keystore must match the host identified in thehost
variable specified in the<
INSTALL
>/jwstutorial13/examples/common/build.properties
file.To create a keystore named
client-keystore.jks
that contains a client certificate namedclient.cer
, follow these steps:
- Generate the client certificate.
<
JAVA_HOME
>\bin\keytool -genkey -alias client-alias -keyalg RSA -keypass changeit -storepass changeit
-keystore keystore.jks- 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- Add the certificate to the trust-store file
cacerts.jks
. Runkeytool
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 keystoreFor an example application that uses mutual authentication, see Example: 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, its 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 add information about where to locate the keystore file and what its password is to the deployment descriptor. To enable the SSL connector for Tomcat and add the information about the keystore, follow these steps:
- Shut down the server. If you don't know how to do this, refer to the section Shutting Down Tomcat.
- Enable or add an SSL HTTPS Connector to your Web server using either of these two methods:
- Add the
Connector
usingadmintool
. See the documentation foradmintool
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:
The
https
in this URL indicates that the browser should be using the SSL protocol. Thelocalhost
in this example assumes you are running the example on your local machine as part of the development process. The8443
in this example is the secure port that was specified where the SSL Connector was created in Configuring the SSL Connector. If you are using a different server or port, modify this value accordingly.The first time a user loads this application, the New Site Certificate or Security Alert dialog displays. Select Next to move through the series of 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 ofhttp:
. Any pages which absolutely require a secure connection should check the protocol type associated with the page request and take the appropriate action ifhttps:
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. No matter which way you choose, you must enter the keystore location and password in the Web server configuration file to enable SSL, as discussed in Configuring the SSL Connector. The two ways to enable mutual authentication over SSL are:
- Configure the SSL Socket Factory in the
<
JWSDP_HOME
>/conf/server.xml
file 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="true"
protocol="TLS"
debug="0" />
</Connector>When 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 toCLIENT-CERT
, as shown below. By enabling client authentication in this way, client authentication is enabled only for a specific resource controlled by the security constraint.
<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 thattargets.xml
forks a client withjavax.net.debug
in its system properties, which could be added in a file such as<
INSTALL
>/jwstutorial13/examples/jaxrpc/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. The following example modifies therun-mutualauth-client
target from the<
INSTALL
>/jwstutorial13/examples/jaxrpc/common/targets.xml
file by addingsysproperty
as shown in bold:<target name="run-mutualauth-client" description="Runs a client with mutual authentication over SSL"> <java classname="${client.class}" fork="yes" > <arg line="${key.store} ${key.store.password} ${trust.store} ${trust.store.password} ${endpoint.address}" /><sysproperty key="javax.net.debug" value="ssl, handshake" /> <sysproperty key="javax.net.ssl.keyStore" value="${key.store}" /> <sysproperty key="java.net.ssl.keyStorePassword" value="${key.store.password}"/>
<classpath refid="run.classpath" /> </java> </target>
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.