SSL/TLS Configuration

Overview

Configuring SSL/TLS for the application requires two steps (as described in the official Tomcat documentation):

  1. Creating/preparing the Java keystore.
  2. Configuring the server.xml file to point to the keystore.

See this article and the official Tomcat documentation for more details.

Preparing the keystore (self-signed certificate)

Note: The following command will create a new keystore containing the server's private key and a self-signed certificate which is not recommended for production use (test/development only). To import an existing server certificate from a Certificate Authority (CA) instead, skip to the next section.

Create a keystore by executing the following command:

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA

Once created, the .keystore file can typically be found in the home directory of the user who created it, ex. /home/user in Linux/*nix or C:\Documents and Settings\Administrator in Windows.

Preparing the keystore (with an existing certificate))

Import the certificate and private key

  1. Enter the following command from the terminal:

    openssl pkcs12 -export -in <path/to/cert>.crt -inkey 
    <path/to/key>.key -out <keystore-name> -name <alias>
    where:

    <path/to/cert> is the full path to the location of your certificate.
    <path/to/key> is the full path to the location of your private key
    <alias> is the name you wish to use to identify this keystore entry
    <keystore-name> is the name you wish to use for your new keystore

  2. When prompted, enter the passphrase for your key (if you have one)
  3. When prompted, provide a password to use for the keystore
Import the root certificates

Note: this step may or may not be necessary for your certificate
  1. Change into the jre/bin directory of your Java installation
  2. Enter the following command: 
     keytool -import -alias root -keystore <your_keystore_filename>
     -trustcacerts -file <filename_of_the_chain_certificate>

    where:

    <your_keystore_filename> is the full path to the location of your keystore
    <filename_of_the_chain_certificate> is the full path to your chain certificate

  3. When prompted, enter the password for your keystore in order to import the chain certificate

Configuring SSL/TLS in the Connector

  1. Edit the tomcat/conf/server.xml file.
  2. Uncomment the area for SSL/TLS Connector configuration:

    <!-- Define a SSL HTTP/1.1 Connector on port 8443 
     This connector uses the JSSE configuration, when using APR, the 
     connector should be using the OpenSSL style configuration
     described in the APR documentation -->

     <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
     maxThreads="150" scheme="https" secure="true" clientAuth="false"
     sslProtocol="TLS" /><    /pre>
  3. Add the keystoreFile, keystorePass, and keystoreAlias (optional) attributes to the <Connector> element:

    <!-- Define a SSL HTTP/1.1 Connector on port 8443 
     This connector uses the JSSE configuration, when using APR, the 
     connector should be using the OpenSSL style configuration
     described in the APR documentation -->
    <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
          maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
          clientAuth="false" sslProtocol="TLS"
          keystoreFile="<path/to/keystore>" keystorePass="<keystore_pass_from_above>" 
          keystoreAlias="<alias>" keystoreType="PKCS12" />
    where:

    <alias> is the name you chose to use to identify your keystore entry above
    <path/to/keystore> is the full path to the location of the keystore you created above
    <keystore_pass_from_above> is the keystore password you had set above

    Note: To prevent issues, we recommend that you avoid using any of the following characters in your keystore password: & < > " '
  4. Start Cascade CMS.

The application should now be accessible at https://{host}:8443. See this article for instructions on forcing connections to use SSL.