Cascade Administration reference

SSL/TLS Configuration

Overview

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

Creating/preparing the Java keystore.
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:

Velocity

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

Enter the following command from the terminal:
XML
```
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
When prompted, enter the passphrase for your key (if you have one)
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

Change into the jre/bin directory of your Java installation
Enter the following command:
XML
```
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
When prompted, enter the password for your keystore in order to import the chain certificate

Configuring SSL/TLS in the Tomcat connector

Edit the tomcat/conf/server.xml file.

Uncomment the area for SSL/TLS Connector configuration:

XML

<!-- 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" /><

Add the keystoreFile, keystorePass, and keystoreAlias (optional) attributes to the <Connector> element:

XML

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

XML

<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: & < > " '

Start Cascade CMS.

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