How to configure SSL from web configuration interface - RHEL

How to configure SSL from web configuration interface - RHEL

1. Configuring SSL From Web Configuration Interface

Using Secure Socket Layer (SSL) connections to access the ResolutionMD server is optional; some sites implement their own private security.

When you are logged into the server as an administrator, the options to manage SSL security are available from the Settings | Security menu option.

The status messages at the top of the page will gradually change from red to green as you complete the configuration steps.

2. Prerequisites

Before you begin to configure SSL for the ResolutionMD server, ensure that you have the following information:

  • Which Certificate Authority (CA) will be providing the signed certificates? e.g. GoDaddy, VeriSign, Thawte

  • What is the contact information for the IT person responsible for SSL (name, phone number, email address)?

  • What is the fully qualified domain name (FQDN) for the server?

  • Also, ensure the system is set to the current date, time and time zone. The default time zone is MDT. This section outlines the steps to change this if necessary.

    • To verify the time zone:

      • Log in via SSH to the ResolutionMD server.

      • Run the following command: date

    • To change the time zone:

      • Go to the following directory to find all the cities for the America’s (North, Central & South) time zones: /usr/share/zoneinfo/America

      • Set the localtime file in the /etc directory use the following command: ln -sf /usr/share/zoneinfo/America/[city] /etc/localtime

      • In the command above, replace [city] with the name of a city from step 1 above. Here’s an example using Los Angeles for the Pacific Time Zone: ln -sf /usr/share/zoneinfo/America/Los_Angeles /etc/localtime

  • To verify the time zone:

    • Log in via SSH to the ResolutionMD server.

    • Run the following command: date

  • Log in via SSH to the ResolutionMD server.

  • Run the following command: date

  • To change the time zone:

    • Go to the following directory to find all the cities for the America’s (North, Central & South) time zones: /usr/share/zoneinfo/America

    • Set the localtime file in the /etc directory use the following command: ln -sf /usr/share/zoneinfo/America/[city] /etc/localtime

    • In the command above, replace [city] with the name of a city from step 1 above. Here’s an example using Los Angeles for the Pacific Time Zone: ln -sf /usr/share/zoneinfo/America/Los_Angeles /etc/localtime

  • Go to the following directory to find all the cities for the America’s (North, Central & South) time zones: /usr/share/zoneinfo/America

  • Set the localtime file in the /etc directory use the following command: ln -sf /usr/share/zoneinfo/America/[city] /etc/localtime

  • In the command above, replace [city] with the name of a city from step 1 above. Here’s an example using Los Angeles for the Pacific Time Zone: ln -sf /usr/share/zoneinfo/America/Los_Angeles /etc/localtime

2.1. General Components

ResolutionMD SSL has the following components:

  • .keystore file - Created with the java keytool utility. It stores the private key used to generate the certificate request the .csr file and it also stores the .pem certificate and the CA .crt root certificate. The .keystore file can live anywhere on the server.

  • ssl folder - This is a ResolutionMD folder that is created when SSL is enabled. It holds the storepass.txt file.

  • storepass.txt file - The file contains the password of the .keystore. This password is generated randomly during the .csr creation from the ResolutionMD web UI. For the manual setup and configuration of SSL, the site must pick a password to be used.

    During an upgrade, this file will need to be updated to contain the password of the old keystore. Even though the file extension is .txt, the file is a BINARY file and cannot contain an end of line character. 
  • .csr file - The Certificate Signed Request (CSR) file uses the private key from the .keystore. For ResolutionMD, named it as tomcat.csr. The .csr file can be given to the Certificate Authority by copy and pasting the contents or sending the actual .csr file.

    It is recommended to send the actual .csr file to ensure there was no copy/paste errors. e.g. Extra blank spaces or hidden characters may get added when using copy/paste to submit the .csr. As a result, the .crt files that are returned may be invalid and will cause some confusion/frustration. In the end, the site will have to re-submit the .csr again.
  • SSL Certificate(s) - The CA will return the signed certificate(s) for the site to import into the .keystore file prior to enabling SSL.

    • The certificate(s) must be in PEM format.

    • The SSL certificate(s) have an expiration date. If the certificate(s) expires, the site will have to create a new .csr file and repeat the process.

    • Normally you will get a single certificate, that you should name tomcat.pem, plus the root certificate, root.crt.

      e.g. With GoDaddy, they will provide multiple certificates (SHA-1, SHA-2, etc.) for use.

  • server.xml file - This file contains the functionality to enable/disable SSL. Within the SSL parameters, it stores the .keystore location and the .keystore password.

  • keytool - This is a keystore utility included in the Java Development Kit (JDK), used by ResolutionMD to handle the .keystore and its SSL certificate(s).

  • The certificate(s) must be in PEM format.

  • The SSL certificate(s) have an expiration date. If the certificate(s) expire, the site will have to create a new .csr file and repeat the process.

  • Normally you will get a single certificate, that you should name tomcat.pem, plus the root certificate, root.crt.

    e.g. With GoDaddy, they will provide multiple certificates (SHA-1, SHA-2, etc.) for use.

e.g. With GoDaddy, they will provide multiple certificates (SHA-1, SHA-2, etc.) for use.

3. Setup SSL

  • The procedures in this section describe how to configure SSL for the first time. If the server is already configured for SSL and your current certificate is about to expire, refer to Renewing Expired Certificate instead.

  • If the server is already configured for SSL, or if you were using an earlier version of ResolutionMD, please ensure the certificate is in the following location: /[Installed_Location]/tomcat/conf

  • If no other files other than the storepass.txt file is in the ssl folder, the folder can be renamed. When the pureweb service restarts, the ssl folder will be re-created with the proper references to the certificate in the /tomcat/conf folder.

  1. Log in to the server using administrator-level credentials and navigate to the Settings | Security page.

  2. When you first access this page, it displays the SSL Configuration page, as illustrated below.

3.1. Generate Keystore

To Generate a new keystore, fill out the fields in the Generate Keystore section of the server’s Settings | Security page. This form is user-friendly, and provides the following cues to help fill it out:

Each text box contains hints (text in light gray) regarding the expected format. Only Hostname is mandatory. The label for each field is followed by the icon of a question mark in a circle; hover your mouse over that icon to display a description of the content expected in that field.

When you are done filling out the form, click on the Generate button.

  • Press the Generate button only once.

  • If there is already a keystore file present and if you click this button again, a backup of your keystore will be created in a file called tomcat.keystore.YYYYMMDDHHmmss.bak in the tomcat\conf\ssl directory.

  • If you accidentally press the button more than once, you can recover from this by removing the tomcat.keystore file and renaming the appropriate backup file to tomcat.keystore.

If the form contains errors, the system will display an error message. Otherwise, the following will take place:

  • The Keystore is not present warning under SSL Status at the top of the page will change to a green Keystore is present.

  • The Server Certificate Is Not Present warning will change to a green Server Certificate Is Present.

  • A new box that reads Your Certificate is not Expired. It Expires: MM/DD/YYYY will be displayed.

All of the remaining warnings will change to green as we continue on with the SSL configuration. NOTE: After you have created the keystore file once, you should never delete the file, unless you must re-implement SSL from the ground up. Even when your SSL certificates expire, do not delete the keystore.

See Renewing Expired Certificate.

3.2. Submitting a Certificate

After you generate the keystore information, you can generate the certificate signing request (CSR), which is based on that information.

This is step 2 in the Settings | Security page:

  1. Click the Generate button in the Generate Certificate Signing Request section; the system will automatically add the necessary text for the request into the text box.

  2. Copy and paste the generated text and submit it to a certificate authority as described below.

  3. Submit the .csr to the CA.

There are two options for submitting your CSR to the CA:

  • You can submit your CSR to the site IT team, who will then submit it to the CA used by the site.

  • You can submit the CSR directly to the service providing the SSL certificate.

 

However, you may have to upload a file instead. In this case, upload the following file:

[Installed_Location]/tomcat/conf/ssl/tomcat.csr

 

The CA will provide both the SSL certificate and the root certificate. You may receive either a certificate bundle or separate files, depending on the CA:

  • If a bundle, it will contain a server-specific SSL certificate, a root certificate, and may contain intermediate certificates depending on the CA.

  • If separate files, there will be one for the server-specific SSL certificate (if the filename is not tomcat.pem, rename the file), one for the root certificate, and one or more intermediate certificates depending on the CA.

The SSL certificate content could be in a text box instead of a file. In this case copy the content of that text box and save it to a file. Name the file tomcat.pem.

You must ensure that the SSL certificates returned from your authority are compatible with Apache Tomcat.

3.3. Import Certificate(s)

After you generate the keystore and obtain certificates from a Certificate Authority, you must import the certificates. To do so, navigate to section 3 of the Settings | Security page of the ResolutionMD server:

The procedure for importing the certificate varies depending on whether you received a bundle of individual certificates:

  1. Select the Certificate Bundle option.

  2. Click the Add Bundle button to open a file list.

  3. Navigate to the location of the certificate bundle and select it.

  4. Click on the Upload Bundle button.

Your certificate authority may provide the certificate chain in several separate files, for instance, the root certificate could be its own file. In this case, you will have to use the Import Individual Certificates option.

  • When individual certificate files are used, one of these files MUST be named tomcat.pem.

  • This is because when the original key is created (when generating the keystore), the alias is automatically set to tomcat. The filename (without extension) is used as the alias within the keystore.

  • Also, the root and intermediate certificates that come from your certificate signing authority must be uploaded in PEM format.

 

  1. Select the Individual Certificates option.

  2. Click the Add Certificates button to open a file list.

  3. Navigate to the location of the individual certificate files and select a file. You can also use the Ctrl key with the right-click mouse button to select multiple files at once.

  4. The files you selected appear in a list below the Add Certificates button. If you made an error, you can use the Remove button to remove any files accidentally selected.

  5. Click the Upload Certificates button.

    If you accidentally click Upload Certificates more than once, you will get the certificate import conflict error message. This won’t affect the server. At this point in the process, all the messages in the SSL status section at the top should be green, except the message SSL is not configured and the warning Server Restart Required.

If you accidentally click Upload Certificates more than once, you will get the certificate import conflict error message. This won’t affect the server. At this point in the process, all the messages in the SSL status section at the top should be green, except the message SSL is not configured and the warning Server Restart Required.

3.4. Enable SSL

Click the Enable SSL button at the bottom of the page. If all goes well, you should now see the message SSL is Configured under the SSL Status heading at the top of the page.

 

  • That this message is not a confirmation that SSL is running, but an indication that the server.xml file contains the SSL connector element.

  • In order for SSL to be enabled, a full restart of the tomcat server is required. Simply reloading the plug-ins will not be sufficient.

  • Following the server restart, all of the boxes should be green and the warning box should disappear.

After setting up SSL, you should verify that HTTPS is enabled correctly:

  1. Restart the Pureweb service.

  2. Execute the following to validate that the connector started up: netstat -an | grep 8443

  3. Browse to the Dashboard page: https://[IP or hostname]:8443/pureweb/configurator/default/index.jsp#!

  4. Select Security. The SSL checks should all display in green.

  5. Test the SSL by going to a 3rd-party site like SSL Checker. Enter the server hostsname (e.g. https://demo.calgaryscientific.com).

  6. Testing on Mobile Devices:

    1. Set Secure Connection to ON.

    2. Enter the address [hostname]:8443.

    3. Tap Connect.

    • Set Secure Connection to ON.

    • Enter the address [hostname]:8443.

    • Tap Connect.

    4. Renewing Expired Certificate

    The process to update an expired certificate is the same as the new SSL setup procedure except for the fact that you already have a keystore file.

    • Never delete the .keystore unless the site is requesting a new certificate from the CA and plan to start from scratch.

    • Backup the .keystore file in a safe location so it can be used again if mistakes are made.

    1. Generate a .csr.

    2. Submit the .csr to a CA and have it return signed SSL certificate(s).

    3. Import the signed certificate(s) or bundle(s) to the tomcat.keystore.

    4. Restart the pureweb serivce.

    5. Network Configuration Options for SSL

    Although it should not be necessary to manually configure SSL, advanced system administrators could be interested in doing this. 

    5.1. Network Configuration Options

    You have the option to use SSL on both the internal and external network or just in the external network.

    5.2. Single Port

    Use it when you want both internal and external networks to use SSL.

    The server uses port 8443. Both external and internal devices use port 8443. The use of encryption in the SSL protocol may slow down a network’s performance and can impact the user’s experience.

    This option is illustrated by the diagrams below.

    SSL Config Opt1

     

    Mobile Edit Server

     

    To accomplish this edit the file /opt/CSI/PureWeb/Server/tomcat/conf/server.xml and comment out the XML bean for the 8080 connection.

    The enabled bean looks like the following:

    To comment out the connector just add standard XML comments around the block, <!-- and -->.

    Once the server.xml file is saved restart the service with service pureweb restart.

     

    5.2.1. Two Ports

    Use it when you want only the external network to require SSL.

    With this option, the default port of 8080 is used as the Tomcat Connector port; after SSL is configured, port 8443 is enabled as an additional connector port. This second connector port allows clients to connect using HTTPS on port 8443. This allows internal users to take advantage of the network performance (since SSL requires additional encryption overhead, the number of effective concurrent sessions could otherwise potentially be reduced).

    This option requires two separate connector elements in the server.xml file, the second connector element, the SSL gets added automatically when you enable SSL.

    SSL Config Opt2

    SSL Off

      

    SSL On

    5.3. Port redirection

    If you want client devices to be able to use the regular http and https ports, 80 and 443 respectively, you will have to ask the IT administrator to redirect requests from those ports to the ports 8080 and 8443 of the ResolutionMD server.

    The ResolutionMD server will work seamlessly with port redirection.