Manually configuring SSL

How to manually configure SSL

This section describes the procedures to configure SSL Connections manually.

It is important for you to review the following sections as it assumes you are familiar with those concepts of SSL requirements and general components.

To enable SSL connection to the ResolutionMD Server, the following steps must be taken:

  1. Generate a tomcat keystore.

  2. Generate a Certificate Signing Request (CSR).

  3. Submit the CSR to a Certificate Authority to receive signed SSL certificates.

  4. Import the signed certificates to the tomcat keystore (see the note below).

  5. Enable the SSL connector in the server.xml configuration file.

If the certificate provider suggests specific instructions on how to import the SSL Certificate into Tomcat, use those instructions. Note any specific alias names for the certificates and any specific order for certificate import.

Keytool

The tool used for the Manual SSL setup is the Java keytool, a keystore the keystore and SSL Certificates.

The tool is located in /usr/java/default/bin/keytool by default. You can use the full PATH of the tool in the commands below or you can:

  • Add the Java bin directory to your $PATH:

    Run the following command once to add it to your current session’s $PATH or add the command to your $HOME/.bashrc file to permanently add it to your $PATH.

    export PATH=$PATH:/usr/java/default/bin

Run the following command once to add it to your current session’s $PATH or add the command to your $HOME/.bashrc file to permanently add it to your $PATH.

Or:

  • Create a symbolic link of the java keytool and place it in the /opt/CSI/PureWeb/Server/tomcat/conf/ssl directory.

    ln -s /usr/java/default/bin/keytool /opt/CSI/PureWeb/Server/tomcat/conf/ssl/keytool

The keystore password file

The file /opt/CSI/PureWeb/Server/tomcat/conf/ssl/storepass.txt contains the password of the keystore. This password is generated randomly during the installation process and contains a secure password that the Web Configuration Interface uses when creating a keystore file or when accessing the keystore certificates.

When manually creating a keystore it is advised to use the password contained in that file. If using a password for your own then you MUST update the storepass.txt file with the password you used.

Also, during an upgrade, this file will need to be updated to contain the password of the old keystore.

 

After updating the /opt/CSI/PureWeb/Server/tomcat/conf/ssl/storepass.txt file, run the following command to remove the end of line character.

Manually Generate Keystore

To manually generate a keystore:

  1. Go to the /opt/CSI/PureWeb/Server/tomcat/conf/ssl directory:

    cd /opt/CSI/PureWeb/Server/tomcat/conf/ssl
    Note
    /opt/CSI/PureWeb/Server/tomcat. For the new Web Configuration Interface to work with SSL, the keystore needs to be located in /opt/CSI/PureWeb/Server/tomcat/conf/ssl.
  2. Run the following command:

    keytool -genkey -alias tomcat -keyalg RSA -keysize 2048 -keystore ./tomcat.keystore
  3. Enter a password of your choice as the keystore password.

    Note
    Your private key password and keystore password should be the same, otherwise, you will get an error along the lines of java.io.IOException: Cannot recover key.
  4. When asked for the first and last name, enter the server name including the

  5. Fill in the rest of the required fields:

    • Your organizational unit (OU).

    • Your organization (O).

    • The city or locality (L).

    • The state or province (ST).

    • The two letter country code. For example, US.

  6. Type yes when asked if the information is correct.

  7. Type your keystore password.

 

  • Your organizational unit (OU).

  • Your organization (O).

  • The city or locality (L).

  • The state or province (ST).

  • The two letter country code. For example, US.

Manually Generate Certificate Signing Request

 

To manually generate a CSR:

  1. Go to the /opt/CSI/PureWeb/Server/tomcat/conf/ssl directory:

    cd /opt/CSI/PureWeb/Server/tomcat/conf/ssl
  2. Run the following command:

    keytool -certreq -keyalg RSA -alias tomcat -keysize 2048 -file tomcat.csr -keystore tomcat.keystore
  3. Enter the keystore password.

The generated certificate will be placed in /opt/CSI/PureWeb/Server/tomcat/conf/ssl/tomcat.csr.

Submitting the manually generated CSR to the Certificate Authority

Submit the contents of the file /opt/CSI/PureWeb/Server/tomcat/conf/ssl/tomcat.csr (or the file itself) to your Certificate Authority to receive a signed certificate. You will need to import it as described in the next section below. You must ensure that the SSL is compatible with Apache Tomcat.

The certificate you receive might be in a text box, copy the contents of that text box and save them into a file called tomcat.pem inside /opt/CSI/PureWeb/Server/tomcat/conf/ssl.

You will also need to retrieve the root certificate from your Certificate Authority

Manually import Certificate or Certificate Bundles

All certificates returned from the Signing Authority must be imported to the tomcat keystore. These certificates must be imported using specific aliases as described below.

If the certificate provider suggests specific instructions on how to import the SSL Certificate into Tomcat, use those instructions. Note any specific alias names for the certificates and any specific order for certificate import.

The number of certificates returned from the Signing Authority is from 1-n, depending on the Signing Authority used. The certificates may be delivered in a .zip format containing the signed certificate and certificate chain, as individual certificate files, or as a single, bundled certificate.

Please note that the certificates received must be imported using specific aliases. As noted above, there are several forms of certificates, but in general, the follow rules apply:

  • When a single certificate is received, it must be imported using the alias tomcat. This will replace any self-signed certificates in the keystore.

  • When multiple certificates are received, they generally follow the filename form of:

    [provider]_[certName].crt.

    They should be imported using the alias certName.

    For example: gd_intermediate.crt is imported under the alias intermediate.

  • When multiple certificates are received, the server certificate must be imported under the alias tomcat.

    For example: gd_imagingServer.crt must be imported with alias tomcat.

They should be imported using the alias certName.

For example: gd_intermediate.crt is imported under the alias intermediate.

For example: gd_imagingServer.crt must be imported with alias tomcat.

For each certificate received from the Signing Authority, import the certificate to the tomcat keystore using the command below. If you obtained a root certificate, import that one first.

assuming that, after submitting a CSR, the following certificate is returned as a single file: gd_certBundle.crt. This certificate contains the proper certificate chain needed, but must be imported under the tomcat alias:

assuming that, after submitting a CSR, we receive multiple certificates: gd_cross_intermediate.crt, gd_intermediate.crt and gd_ServerName.crt. These certificates must be imported under the aliases cross, intermediate, and tomcat, respectively. To import these to the tomcat keystore file the following commands should be used:

Manually enable SSL

  1. Edit the following /opt/CSI/PureWeb/Server/tomcat/conf/server.xml file and remove the comments tags on <!-- SSL) and (SSL -->.

  2. Make sure the keystoreFile and keystorePass values are set appropriately.

  3. Remove the following if necessary: keystoreType="PKS12

  4. The set of available ciphers may be restricted to those that are considered to be cryptographically strong by including the ciphers configuration as part of the connector configuration.

  5. Restart the Pureweb service: service pureweb restart