Adding SSL Support to Relativity

To enable SSL support in Relativity you need to add a new Http Binding via the Relativity Admin Tool or through the Relativity Web Interface. In addition you will need to install the SSL certificate, which can be done on Windows using IIS, or if you are on Mac/Linux you will need to use certmgr. Steps for adding an SSL certificate will be be detailed below.

Relativity Admin Tool

Start the Relativity Admin Tool and open the Network Settings pane of the server you are interested in.

Next set the Server Channel Type to either SuperHttpSys or HttpSys, for more information on consult the Channel Types concept.

The next step is to add a new Http Bindings by pressing on the blue icon with a >>, and then set the following parameters:

• Host = hostname of the server, default is *
• Port = the port the server should listen on, the default is 8099
• Use SSL = check to enable SSL, default is unchecked.

Finally save the new settings by pressing the green tick.

The next step is to install the SSL certificate. You will find the steps needed described below the setting up SSL via the Relativity Web Interface.

Relativity Web Interface

It is also possible to enable SSL for a particular channel by using the Relativity Web Interface. The steps to do so are:

Go to the web interface, typically http://localhost:7099/admin and enter the Adminstrator username and password.

Select Network settings and then scroll down to the NetworkServer.ServerChannel section and press the Add button.

Now set the following parameters, and when done scroll up/down and press the Apply Changes button.

• Host = hostname of the server, default is *
• Port = the port the server should listen on, the default is 8099
• Use SSL = check to enable SSL, default is unchecked.

The next step is to install the SSL certificate that will be used to enable SSL protection for the server binding configured above.

Install SSL certificate on Windows with IIS

The last step is to configure the IIS to use an SSL certificate. Either obtain a SSL certificate from one of the many providers or issue a self-signed SSL certificate (f.e. using SSL Diagnostics Tool (available from the Microsoft Downloads site) or OpenSSL toolset).

1) Open IIS Manager (for instance by via Start -> Run -> inetmgr). 2) Click on the root tree node and select the Server Certificates entry.

3) Import the certificate file (corresponding action is available in the Actions pane). 4) Right click on the web site entry in the IIS options tree and issue Edit Bindings... 5) Add Site Bindings with type https, port matching to the one used by the Relativity Server. Use the SSL certificate imported on the previous steps.

Now the Relativity Server connection is secured using SSL.

Install SSL certificate on Mac/Linux

The last step is to configure Mono to use your SSL certificate on the port(s) you are interested in. Either obtain an SSL certificate from one of the many providers, or create a self-signed SSL certificate (f.e using the OpenSSL toolset)

Here are the steps needed to create a self signed certificate for testing purposes:

Create a Self Signed SSL Certificate

The first step is to create a key file, changing yourdomain to whatever your domain actually is:

openssl genrsa -des3 -out yourdomain.pem 2048

This step will optionally remove the password you supplied when you created the key file above:

openssl rsa -in yourdomain.pem -out yourdomain.pem.nopass

The next step is to create the certificate signing request. The fields can be left in their default states for testing purposes, but the Common Name should be the domain name you want to secure:

openssl req -new -key yourdomain.pem.nopass -out yourdomain.csr

Lastly we need a cert file, for testing purposes you can generate that yourself using:

openssl x509 -req -in yourdomain.csr -signkey yourdomain.pem.nopass -out yourdomain.crt

Having got the cert we now need to register it with Mono.

Registering the SSL cert to Mono

The key file created in a previous step isn't compatible with Mono. If you tried to register the cert you have at this point you would receive the following error "error loading certificate or private key [Invalid data and/or password]"

To avoid this error we need to convert the private key to PVK, which is a proprietary Microsoft format. To do this we need the pvktool utility created by Dr. Stephen N Henson, who is a member of the OpenSSL team.

The pvktool can be downloaded from his website http://www.drh-consultancy.demon.co.uk/pvk.html. The file package comes as a *.tgz-bin, the -bin extension can simply be ignored. You need to unpack the download:

tar zxf pvksrc.tgz.bin

To build the pvktool you need the SSL dev headers installed. On Mac OS X these are already available, however you will likely need to install them on your Linux distribution yourself. If your using Ubuntu, then its as simple as issuing the following in the terminal.

apt-get install openssl-sdk

On Mac you need to edit the Makefile to change the locations of SSLINC & SSLLIB to point to the following folders:

SSLINC=/usr/include
SSLLIB=/usr/lib

You can then build the pvktool by simply issuing the make command.

To run the conversion from PEM to PVK

pvk -in yourdomain.pem.nopass -topvk -nocrypt -out yourdomain.pvk

The final step is to register your signed certificate with the httpcfg tool¹

sudo httpcfg -add -port 8099 -pvk yourdomain.pvk -cert yourdomain.crt

You can now point your browser to your domain. For the figure below, we created a self signed certificate for testing.com, edited the hosts file so that testing.com resolved to a local address and pointed the browser to https://testing.com:8099

Footnotes