We would like to secure our LISTSERV web interface with SSL/https.  How is this done?


There are three major (required) components and one optional final step to making this change:


1.[REQUIRED] Obtain and install a digital certificate on the web server

2.[REQUIRED] Configure LISTSERV itself to generate and recognize https URLs

3.[REQUIRED] Configure the web server to redirect http requests to https

4.Optionally, configure HSTS "Strict Transport Security"

1. [REQUIRED] Obtain and install a digital certificate on the web server


This component must be accomplished by the customer without assistance from L-Soft.  It involves obtaining a digital certificate which is in turn installed on the LISTSERV machine's web server, following which the web server must be configured to enable the https protocol.  Because there are several different approaches to this, we recommend careful research before starting this process.  Google (whose search engine has for several years given https sites preferred weighting) has a help page at this link which explains the process in some detail, although it does not provide specifics for different web servers.


Once your web server has its certificate installed and has been properly configured to use the https protocol, test it by navigating to a test page on your server using https.  (Most web servers provide a test page in the document root by default when they are installed.)  Ensure that you get the lock character in the address bar that indicates that you have connected securely.  You may also test to ensure that your server certificate is correctly installed by using the SSL Checker found here.  If you want a more in-depth scan run of your server and its security protocols, you can try the SSL Server Test found here.  (The latter test is extremely in-depth and will take a couple of minutes to run.)


If all is well, you may then proceed to the next step.

2. [REQUIRED] Configuring LISTSERV itself to generate and recognize https URLs


First, you'll need to change the WWW_ARCHIVE_CGI variable in your SITE.CFG file (Windows) or go.user file (unix) to use https.  This means you'll need to specify the full URL that points to WA.EXE (Windows) or wa (unix) instead of providing just a relative link.  For example, you may have (for Windows)


WWW_ARCHIVE_CGI=/scripts/wa.exe


In that case, you would need to change the setting to


WWW_ARCHIVE_CGI= https://listserv.yourhost.com/scripts/wa.exe


For unix, you will probably have


WWW_ARCHIVE_CGI=/cgi-bin/wa


In that case, you would need to change the setting to


WWW_ARCHIVE_CGI= https://listserv.yourhost.com/cgi-bin/wa


Note that the hostname (highlighted in yellow) will be the same as the value in the NODE= site configuration setting.


For both Windows and unix servers, you'll need to restart LISTSERV after making this change.


Note:  While it is possible to change the value of WWW_ARCHIVE_CGI using the web administration interface, we recommend that this change be made manually in the top-level site configuration file, as explained above.


Then (for LISTSERV 16.5 and earlier) you'll need to edit the SKIN web template (found in the web interface under Server Administration/Customization/Web Templates) and change:


+SE WWWHOST http://&+MYHOST;&+SCRIPT

+SE HTMLIMAGES http://&+MYHOST;/archives/htmlmail


to


+SE WWWHOST https://&+MYHOST;&+SCRIPT

+SE HTMLIMAGES https://&+MYHOST;/archives/htmlmail


For LISTSERV 17.0 and later, it is no longer necessary to edit the SKIN template for this purpose, as the template has been revised to detect whether or not you are using https.


Once LISTSERV has been configured as above and restarted, test it by navigating to the default WA URL, which would be something like


Windows: https://listserv.yourhost.com/scripts/wa.exe


Unix: https://listserv.yourhost.com/cgi-bin/wa


Again, note that the hostname (highlighted in yellow) will be the same as the value in the NODE= site configuration setting.


Assuming you get the lock icon and all of the links on that page are https links, you may move on to the next step.

3. [REQUIRED] Configure the web server to redirect http requests to https


This component must be accomplished by the customer without assistance from L-Soft.  Typically, the procedures for this step are highly specific to the web server you are using to serve web requests.  For Apache in particular, it may vary from OS to OS and from OS version to OS version.  Be sure to read your web server's documentation carefully.

For Unix


For Unix customers running Apache, you can read Apache's best advice for this here:  https://cwiki.apache.org/confluence/display/HTTPD/RedirectSSL

For Windows


For Windows customers running IIS, be aware that Microsoft's advice to use the HTTP Redirect applet in the website's Home screen will NOT work.  Windows customers will need to download and install the IIS URL Rewrite module from IIS.NET in order to get a rewrite module that will dynamically rewrite all http requests to https and not simply dump all such requests to a particular defined page.  This module is fully-supported by Microsoft, so there should be no worries on that score.  (We question only why it is not installed by default as part of IIS.)


Once you have the IIS URL Rewrite Module installed, you can then add a web.config file to your WWW_ARCHIVE_DIR directory containing a redirect rule.  Please read carefully the documentation for the IIS URL Rewrite Module before crafting your rule.  At L-Soft, we have found the following "recipe" to work, but your experience may vary, and we cannot assist you if our particular approach is not satisfactory in your production setting.


<?xml version="1.0" encoding="UTF-8"?>

<configuration>

    <system.webServer>

        <rewrite>

            <rules>

                <clear />

                <rule name="HTTPS Rewrite" enabled="true" patternSyntax="Wildcard" stopProcessing="true">

                    <match url="*" />

                    <conditions logicalGrouping="MatchAll" trackAllCaptures="false">

                        <add input="{HTTPS}" pattern="off" />

                    </conditions>

                    <action type="Redirect" url="https://{HTTP_HOST}/{R:1}" />

                </rule>

            </rules>

        </rewrite>

    </system.webServer>

</configuration>


After adding the rule section, save web.config and restart the IIS instance.  (LISTSERV does not need to be restarted in this case.)


If a web.config file already exists, you need add to it only the parts of the above that aren't already present.  For instance, if there is already a <system.webServer> block present, simply add to it the section of the code starting with <rewrite> and ending with </rewrite>.


These rules can also be added using the URL Rewrite wizard found in the Home pane for the IIS instance in question.  Please see the documentation for the IIS URL Rewrite Module for specifics regarding use of the wizard.


Finally, test this rule by browsing to http URLs on your LISTSERV site.  They should all be automatically redirected to the https URL.  Again, if the rule provided above does not work, we cannot assist you to debug it.

4. Optionally, configure HSTS "Strict Transport Security"


U.S. Federal government executive agencies may be required by DHS Directive BOD 18-01 to enable HSTS "Strict Transport Security" on all of their websites.  Other entities not affected by BOD 18-01 may wish to opt into this high-security https enhancement, as well.


HSTS seems quite simple on its face, but can be a challenging item to set up in a web server.  However, if LISTSERV is the only web-enabled application running on your machine, or if it is deemed necessary to secure only LISTSERV with HSTS, you may prefer to avoid configuring the web server itself for HSTS and let LISTSERV and WA generate the Strict-Transport-Security headers for you.  This can be done easily by adding the following setting to site.cfg or go.user, and then restarting LISTSERV:


Unix:

WWW_HSTS_MAX_AGE=31536000

export WWW_HSTS_MAX_AGE

Windows:

WWW_HSTS_MAX_AGE=31536000


When set to a non-zero value, the WWW_HSTS_MAX_AGE setting causes WA to output the header "Strict-Transport-Security: max-age=x", where "x" is the non-zero variable setting representing the number of seconds the STS header will persist in a user's cache (unless the user clears their cache before that time).  The value 31536000 shown in the example represents 365 days or one year, which is the standard, recommended setting.


Again, this is intended primarily to address DHS directive BOD 18-01, but will enhance security for any LISTSERV site which uses the HTTPS protocol in the LISTSERV web interface.


IMPORTANT NOTES: 


•WA functions named DEBUG-* (e.g., DEBUG-SHOW-VERSION) do not load the configuration file, and therefore will not output the Strict-Transport-Security: header.  However, these are not well-known or commonly-used web functions, and are not linked directly from within the LISTSERV web interface.


•If you already have the webserver configured for HSTS, the webserver HSTS value will preferentially override the setting provided by WA.  The LISTSERV setting is provided for situations where the entire website is not already configured for HSTS but it is desired to use HSTS with LISTSERV.


•With HSTS enabled site-wide in IIS, you may find that:


oThe "archives" directory no longer works correctly if it is implemented as an IIS virtual directory

oSome images served by WA.EXE may be broken


WWW_HSTS_MAX_AGE can be used to solve this problem rather than enabling site-wide HSTS in IIS.