LDAPWiki: Tomcat And SSL

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 Public Key Infrastructure is used to create this environment.

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

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. As this is not very well suited for a server based application, we reccomend <$CATALINA_HOME/bin/.keystore> be used for the <keystore_filename>.

The keytool utility prompts you for the following information:

Keystore password--Enter a password. (You may want to use changeit to be consistent with the default password of the J2SE SDK keystore.)
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.
Organizational unit--Enter the appropriate value.
Organization--Enter the appropriate value.
City or locality--Enter the appropriate value.
State or province--Enter the unabbreviated name.
Two-letter country code--For the USA, the two-letter country code is US.
Review the information you've entered so far, enter Yes if it is correct.
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#

Get your certificate digitally signed by a CA. To do this,#

Generate a Certificate Signing Request (CSR).

keytool -certreq -alias tomcat -keyalg RSA -file <csr_filename> -keystore <keystore_filename>

Send the contents of the <csr_filename> for signing.
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.
Import the signed certificate that you received in email into the server:

keytool -import -alias root -trustcacerts -file <signed_cert_file> -keystore <keystore_filename>

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:

Request the CA certificate from your CA. Store the certificate in a file.
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 <trustcacerts-filename>

NOTE:We recommend that the <trustcacerts-filename> be <$CATALINA_HOME/conf/cacerts>

Configuring the TLS Connector#

By default, an TLS Connector is not enabled. You will need to Configure the TLS Connector in server.xml

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

Shutdown Tomcat, if it is running. Changes to the file <JWSDP_HOME>/conf/server.xml are read by Tomcat when it is started.
Open the file <TOMCAT_HOME>/conf/server.xml in a text editor.
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>
  -->

These settings will still show (in some browsers) "secure, but with minor errors" due to SHA-1 Deprecation

Edit this section so the section looks similar to:

<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
    port="8443" SSLEnabled="true" maxThreads="200"
    disableuploadtimeout="true"
    scheme="https" secure="true"
    keystoreFile="/usr/share/tomcat/conf/ldapwiki.jks"
    keystorePass="secret" clientAuth="false"
    sslEnabledProtocols="TLSv1, TLSv1.1, TLSv1.2"
  ciphers="TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA"
/>

As far as we know, this will pass the SHA-1 Deprecation but we are not confident how many browsers will be able to support this restricted list of Cipher Suite:

<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
    port="8443" SSLEnabled="true" maxThreads="200"
    disableuploadtimeout="true"
    scheme="https" secure="true"
    keystoreFile="/usr/share/tomcat/conf/ldapwiki.jks"
    keystorePass="content-supressed" clientAuth="false"
    sslEnabledProtocols="TLSv1, TLSv1.1, TLSv1.2" 
    ciphers="TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256"
/>

* Save and close the file.

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://<yourserverIP>: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.

Configuring Container Authentication and Authorization#

We have a couple of examples for Configuring Container Authentication and Authorization:

Tomcat And LDAP
Using User Attribute Values for Tomcat Roles!! More Information

There might be more information for this subject on one of the following:

Tomcat And LDAP