Configuring SSL and Using Your Own Certificate/Key on the Web Server

Status:	Published
Version:	1.0
Authors:	HTL QA
Applies to:	Hornbill Core Services Version 3.0 and later

Configuring SSL and Using Your Own Certificate/Key on the Web Server

From Core Services version 3.0 onwards, SwHttpServer has been provided with full SSL support. This means you can use SSL (HTTPS - port 443) as well as normal HTTP (port 80) for Web-page access. On a clean Core Services installation, SSL is enabled by default in the Web server's httpd.conf file just for the home page of the Core Services installation. Thus, that page would be viewable by a user entering a URL of either http://your-server-name/ (for HTTP) or https://your-server-name/ (for HTTPS).

A clean Supportworks ESP installation (Version 7.5 onwards) will modify the Web server's httpd.conf file such that SSL is enabled for all other Web pages relating to Supportworks. Technically, it does this by transferring the required aliases from the port-80 VirtualHost section of the file to the port-443 section. All you then need to do is (a) replace the temporary SSL certificate/key files provided by Hornbill with your own and (b) replace the generic/default details of the configuration within the port-443 VirtualHost section of the httpd.conf file with your own installation-specific ones (including the certificate/key file references).

However, when you perform a Supportworks upgrade, the upgrade process will not overwrite your existing httpd.conf file with the SSL-enabled version, thereby preserving any manual changes you may have made to it. In that case, after the upgrade, you will need to enable SSL yourself by following the procedure given here:

1. Ensure that Core Services version 3.0 or above has been installed and is functioning correctly, with the Web server running, MySQL running and no errors in the log files.
2. Open the httpd.conf file (located by default in C:\Program Files\Hornbill\Core Services\SwHttpServer\conf) using a text editor and add the configuration lines indicated in the following three steps.
3. Make the server listen on port 443 by locating the "Listen 80" line and adding the following line after it:

   Listen 443

4. Make the server load the SSL module by adding the following two lines:

   LoadModule ssl_module modules/mod_ssl.so

   LoadModule deflate_module modules/mod_deflate.so

5. Add one or more virtual host sections relating to SSL (port 443), each consisting of the following set of lines:

   <VirtualHost *:443>

   ServerAdmin server-admin-email-address

   DocumentRoot "Hornbill-install-path\Core Services\SwHttpServer\htdocs"

   ServerName presented-server-name

   ErrorLog logs/secure_error_log

   CustomLog logs/secure_access_log common

   SSLEngine on

   SSLCertificateFile conf/ssl.crt/hslcsdef.crt

   SSLCertificateKeyFile conf/ssl.key/hslcsdef.key

   </VirtualHost>

   Note 1: You must ensure that these new <VirtualHost *:443> sections are located before the <VirtualHost *> section(s) in the configuration file, otherwise the Web server will not be able to bind to port 443.

   Note 2: Substitute the variables in italics above with what is pertinent to your specific installation of the server.

   Note 3: The document root specified above is the \htdocs\ folder on the Web server, containing the file from which the Core Services home page is generated. This is the default, and you may wish to specify some other root instead for certain virtual hosts.

   Note 4: The configuration above points to the temporary Hornbill certificate/key provided. For security reasons, you are advised to use your own certificate and key. The locations of these files (on a default installation) are as follows:

   C:\Program Files\Hornbill\Core Services\SwHttpServer\conf\ssl.crt\
   

   C:\Program Files\Hornbill\Core Services\SwHttpServer\conf\ssl.key\

   Just replace the hslcsdef.crt and hslcsdef.key files with those obtained from your provider, and be sure to modify the two SSL Certificate directives shown in the configuration above so as to show the correct filenames.

6. SSL is now enabled for each virtual host you have added, and you can transfer all aliases from the <VirtualHost *> section(s) to these.
7. Restart the Web server.