Enabling Secure Socket Layer (SSL) protocol for the Apache Tomcat web application server

To enable the Apache Tomcat web application server to support the Secure Socket Layer (SSL) protocol to configure a secure connection (HTTPS), you must obtain and load the appropriate SSL certificates.

Before you begin

Ensure that the %JAVA_HOME% ($JAVA_HOME on Linux) path and the Apache Tomcat JVM path are synchronized, such as shown below:

Apache Tomcat JVMEnvironment Variable
C:\Program Files\Java\jdk7\bin\server\jvm.dll%JAVA_HOME%

C:\Program Files\Java\jdk7\

/usr/java/jdk7$JAVA_HOME

/usr/java/jdk7

Ensure that the %PATH% ($PATH on Linux) environment variable setting contains the %JAVA_HOME%\bin ($JAVA_HOME/bin on Linux) path.

Procedure

  1. Generate a keystore file for use with Apache Tomcat:
    1. In a Command Prompt or Terminal window (run as administrator), cd to the JDK bin directory. For example C:\Program Files\Java\jdk7\bin (/usr/java/jdk7 on Linux).
    2. Generate a keystore file using the keytool -genkey command.

      On Windows:

      keytool -genkey -keystore C:\server_name.jks -alias server_name -keyalg RSA -keysize 2048 -validity 3650

      On Linux:

      keytool -genkey -keystore /usr/server_name.jks -alias server_name -keyalg RSA -keysize 2048 -validity 3650

      While running this command, you specify a password for the keystore and provide organizational information about the Apache Tomcat site.
  2. Obtain a certificate from a trusted Certificate Authority for your implementation of the Apache Tomcat application.

    If you already have a certificate, either as a PFX (Personal Information Exchange) certificate or non-PFX, then you can skip this step and the next step.

    You can create a server authentication certificate via IIS if your domain controller is configured with Certificate Services. The following web pages explain how to create and export the PFX certificate.
    1. Generate a certificate request using the keytool -certreq command with the keystore you created in the previous step:
      On Windows:

      keytool -certreq -keystore c:\server_name.jks -keyalg RSA -alias server_name -file c:\certreq.csr -storepass *****

      On Linux:

      keytool -certreq -keystore /usr/server_name.jks -keyalg RSA -alias server_name -file /usr/certreq.csr -storepass *****

      where ***** is the keystore password

    2. Submit the certificate request file c:\certreq.csr (/usr/certreq.csr on Linux) to a trusted Certificate Authority.
    3. Once the certificate has been issued, follow the steps provided by your certificate provider and save the certificate that you received back from the CA, either in PKSC#7 or in X.509 format, according to their procedures.
    Subsequent steps in this process assume that you have saved two files from the Certificate Authority to the locations on the Apache Tomcat server noted for each file.
    CA certificate
    C:\CACert.cer (/usr/CAcert.cer on Linux) or C:\signedTomcatCert.p7b (/usr/signedTomcatCert.p7b on Linux).
    Signed certificate for the associated Apache Tomcat server alias
    C:\signedTomcatCert.cer (/usr/signedTomcatCert.cer on Linux)
  3. Import the certificate files into the Tomcat keystore.
    1. Import the CA certificate file into the keystore:

      On Windows:

      keytool -import -keystore c:\server_name.jks -trustcacerts -alias CACert -file C:\CACert.cer -storepass *****

      On Linux:

      keytool -import -keystore /usr/server_name.jks -trustcacerts -alias CACert -file /usr/CACert.cer -storepass *****

    2. Import the signed Apache Tomcat certificate file for the associated server alias into the Apache Tomcat keystore:

      On Windows:

      keytool -import -keystore c:\server_name.jks -trustcacerts -alias server_name -file c:\signedTomcatCert.cer -storepass *****

      -or-

      keytool -import -keystore c:\server_name.jks -trustcacerts -alias server_name -file c:\signedTomcatCert.p7b -storepass *****

      On Linux:

      keytool -import -keystore /usr/server_name.jks -trustcacerts -alias server_name -file /usr/signedTomcatCert.cer -storepass *****

      -or-

      keytool -import -keystore /usr/server_name.jks -trustcacerts -alias server_name -file /usr/signedTomcatCert.p7b -storepass *****

    3. Verify that the keystore file contains the certificates for the application.

      On Windows:

      keytool -list -keystore c:\server_name.jks -v -storepass *****

      On Linux:

      keytool -list -keystore /usr/server_name.jks -v -storepass *****

      Your keystore will have only two entries: one for your CAcert (Entry type: trustedCertEntry) and one for your "machine cert" (Entry type: PrivateKeyEntry).
  4. Import the root certificate information into the Java VM trusted certificates (cacerts) file.
    1. Import the root certificate (which you imported into the tomcat keystore in Step 3.a (above) into the Java VM trusted certificates ( cacerts) file:

      On Windows:

      keytool -import -keystore %JAVA_HOME%\jre\lib\security\cacerts -trustcacerts -alias CACert -file c:\CACert.cer

      On Linux:

      keytool -import -keystore $JAVA_HOME/jdk/lib/security/cacerts -trustcacerts -alias CACert -file /usr/CACert.cer
    2. Verify that the Java cacerts keystore file contains the certificates for the application.

      On Windows:

      keytool -list -keystore %JAVA_HOME%\jre\lib\security\cacerts -v -storepass *****

      On Linux:

      keytool -list -keystore $JAVA_HOME/jre/lib/security/cacerts -v -storepass *****

      You can then search the output for the -alias you specified in previous step when importing the root certificate (in this example: CACert).

  5. If you are planning to use a PFX certificate, export the private key and certificate from the JKS store.

    On Windows:

    keytool -importkeystore -srckeystore c:\server_name.jks -srcstoretype JKS -srcstorepass ****** -srcalias server_name -destkeystore c:\server_name.pfx -deststoretype PKCS12 -deststorepass ***** -destalias server_name

    On Linux:

    keytool –importkeystore –srckeystore /usr/server_name.jks –srcstoretype JKS –srcstorepass ****** -srcalias server_name -destkeystore /usr/server_name.pfx –deststoretype PKCS12 –deststorepass ***** -destalias server_name

  6. Copy server_name.jks or server_name.pfx to the conf subdirectory underneath the Apache Tomcat installation.

    Typically, this directory is located:

    On Windows:

    C:\Program Files\Apache Software Foundation\Tomcat 7.0\conf\

    On Linux:

    /usr/Apache Software Foundation/Tomcat 7.0/conf/

  7. Configure the Apache Tomcat web application server to point to the new keystore.
    1. Open the server.xml file, found underneath the conf subdirectory, in a text editor.
    2. Insert these keystoreFile and keystorePass lines where indicated:

      On Windows (non-PFX certificate)

      <Connector port="8443" protocol="HTTP/1.1" 
      SSLEnabled="true"
      maxThreads="150" scheme="https" secure="true"
      keystoreFile="C:\Program Files\Apache Software Foundation\Tomcat 7.0
      \conf\server_name.jks" 
      keystorePass="*****" clientAuth="false" sslProtocol="TLS" 
      useBodyEncodingForURI="false" 
      URIEncoding="UTF-8"
      connectionTimeout="72000000"
      compression="on"
      compressionMinSize="10"
      compressableMimeType="text/html,text/xml,application/xml,
      text/javascript,text/css,application/x-javascript" 
      maxHttpHeaderSize="65536" />
      

      On Linux (non-PFX certificate)

      <Connector port="8443" protocol="HTTP/1.1" 
      SSLEnabled="true"
      maxThreads="150" scheme="https" secure="true"
      keystoreFile="/usr/Apache Software Foundation/Tomcat 7.0/conf/server_name.jks" 
      keystorePass="*****" clientAuth="false" sslProtocol="TLS" 
      useBodyEncodingForURI="false" 
      URIEncoding="UTF-8"
      connectionTimeout="72000000"
      compression="on"
      compressionMinSize="10"
      compressableMimeType="text/html,text/xml,application/xml,
      text/javascript,text/css,application/x-javascript" 
      maxHttpHeaderSize="65536" />
      

      On Windows (PFX certificate)

      <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
      maxThreads="150" scheme="https" secure="true" 
      keystoreFile="C:\Program Files\Apache Software Foundation\Tomcat 7.0
      \conf\server_name.pfx"
      keystorePass="*****" keystoreType="PKCS12" clientAuth="false" sslProtocol="TLS"
      useBodyEncodingForURI="false" URIEncoding="UTF-8" 
      connectionTimeout="72000000" compression="on" compressionMinSize="10"
      compressableMimeType="text/html,text/xml,application/x ml,
      text/javascript,text/css,application/x-javascript" maxHttpHeaderSize="65536" />
      

      On Linux (PFX certificate)

      <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" 
      scheme="https" secure="true" keystoreFile="/usr/Apache Software Foundation/Tomcat 7.0
      /conf/server_name.pfx" keystorePass="*****" keystoreType="PKCS12" clientAuth="false"
      sslProtocol="TLS" useBodyEncodingForURI="false" URIEncoding="UTF-8"
      connectionTimeout="72000000" compression="on" compressionMinSize="10"
      compressableMimeType="text/html,text/xml,application/x ml,
      text/javascript,text/css,application/x-javascript"
      maxHttpHeaderSize="65536" />
      

      where ***** is the keystore password

    3. Comment out the section shown below:
      <Connector port="8080" protocol="HTTP/1.1"
      connectionTimeout="20000"
      redirectPort="8443" />
      For example:
      <!--
      <Connector port="8080" protocol="HTTP/1.1"
      connectionTimeout="20000"
      redirectPort="8443" />
      -->
  8. Verify that the configuration changes are correct by restarting the Apache Tomcat service. You should be able to open the Apache Tomcat default web location (https://server.company.com:8443/) in a browser to see the Apache Tomcat home page.