HOWTO: Configuring ProjectForum with SSL

Last modified 7/13/2015.

ProjectForum provides support for communication via Secure Sockets Layer (SSL). This means that all communication between your web browser and the ProjectForum server is encrypted. This document describes how you can setup SSL on your own ProjectForum server.

Note: SSL support is only available in ProjectForum, not CourseForum. As well, SSL is only available in the full version of the software, not the free version.

Supplying Private and Public Keys

To use SSL, you must first supply an SSL certificate, consisting of 'private' and 'public' keys, to the ProjectForum server; these are used in encrypting the communication.

These keys can be generated or obtained in any number of ways; two examples are included at the bottom of this page.

Once you have your keys, you will need to put them in a place where ProjectForum will find them. Locate the "Group Data" directory where ProjectForum stores all of its data files. Within that directory, place your two key files. They must be named "public.pem" and "private.pem" for ProjectForum to recognize them.

Starting with version 7.4, you can also include an optional "ca.pem" which holds the certificate authority chain. Previously, this had to be included in the public.pem file. For convenience, this can now be separated out, which is how many SSL providers now supply their certificates.

Activating and Deactivating SSL

SSL support is activated and deactivated by the ProjectForum Site Administration page. You can navigate to this page by going to the Group Directory page (via the 'Site Home' button on any page) and click on the 'Administration' link at the bottom right.

With the keys in place, there should be a new option allowing you to specify a port for SSL to use, as well as a button labelled 'Enable SSL'. Fill in the port to use, and click the button. You can choose any port that is not already used; note that the standard SSL port is 443.

Once SSL has been started, it will stay running, including if you restart your ProjectForum server. To turn off SSL, again visit the Site Administration page. From there, click the 'Disable SSL' button.

Connecting to ProjectForum with SSL

When SSL has been enabled, you can connect to the server from your web browser by using a URL like the following:

https://servername:9876/

In this case, "9876" would be replaced by the port number you told SSL to use. The "https" (rather than the normal "http") tells your web browser to connect securely using SSL.

Note that when running SSL, the regular (non-encrypted) port is still available for making standard "http" connections.

Example: Generating Self-Signed Keys with OpenSSL

One way to generate the keys needed for SSL in ProjectForum is via the freely-available OpenSSL software. In doing so, you are essentially acting as your own certificate authority (CA), rather than relying on another CA such as Verisign, Geotrust or Thawte.

IMPORTANT: Before using this approach, understand that most browsers will generate various obscure and difficult to understand error messages to your site's users about the certificate being from an unknown authority. For a real site, you almost certainly want to obtain a certificate from a recognized authority (see example below). However, for initial experimenting, generating your own keys is an option.

To use OpenSSL, first obtain the software, which is available for many platforms, and comes installed standard on many Linux distributions as well as Mac OS X 10.2 or above.

From a command prompt, enter the following openssl commands:

openssl genrsa -out private.pem
openssl req -new -x509 -key private.pem -out public.pem -days 365

After answering a series of questions, this will generate the two files "private.pem" and "public.pem", which you can copy to your ProjectForum "Group Data" directory.

Example: Getting a Signed Key from a Certificate Authority

For production use, you'll probably want to purchase a SSL certificate from a certificate authority, such as Verisign or GeoTrust (their QuickSSL certificates are an affordable option), or Thawte (who also offer affordable options, as well as free test certificates).

Here we'll step through an example of what would be required to use a CA. Each certificate authority requires you to do things a little bit differently, but the process should be similar for most. As always, consult the information provided by the CA that you will be using.

Generate a private key. A usual first step is to generate your private key. Again, we'll use OpenSSL to do this, so make sure you've obtained the software. Use the following command:
```
     openssl genrsa -out private.pem
     
```
This will generate the file 'private.pem' (it should start with -----BEGIN RSA PRIVATE KEY-----), which is your private key, not to be shared with anyone.
Generate a certificate signing request. A certificate signing request (CSR) is needed for you to get a final certificate from your CA. It is created based on your private key. Use the following command:
```
     openssl req -new -key private.pem -out request.csr
     
```
During the process, you will be asked a series of questions about your organization etc. which you need to fill in. When done, the file 'request.csr' will contain your request, and should start with -----BEGIN CERTIFICATE REQUEST-----.
Submit the request. Submit the 'request.csr' file to your CA, where they will use it to generate an actual certificate. If offered a choice of certificate, usually the standard/generic SSL certificate is fine. If asked for type of web server, usually you'd choose "other web server".
Retrieve the certificate. The certificate you get back will start with -----BEGIN CERTIFICATE-----. Rename the certificate file you receive to 'public.pem'. If the CA provides the certificate in a web page, copy and paste it from the web page into a text editor, and save that as public.pem.
Install the certificate. Following the instructions above, place your 'private.pem' and 'public.pem' files in your 'Group Data' directory, and enable SSL in ProjectForum.