Enabling HTTPS (SSL) for the Sassafras Web UI

The Web UI included with the Sassafras Server supports secure browser connections via HTTPS. By default, secure connections are made using a self-signed SSL certificate, which suffices for testing. However, browsers will display an error message and indicate there is a problem with the certificate, which might be disconcerting to users:

For the best user experience the default SSL certificate should be replaced with one that contains the correct host information and is signed by a trusted Certificate Authority.

This document describes how to generate the information needed to create an SSL key pair, and how to install a CA-signed certificate. The methods described below are not the only ways to accomplish the necessary tasks, but they are easy to follow and result in the desired outcome.

Outline

The process of setting up the Web UI to support HTTPS (SSL) connections consists of four steps:

1. Generate a key pair and Certificate Signing Request
2. Submit the Certificate Signing Request to a trusted Certificate Authority
3. Accept the signed certificate returned from the Certificate Authority
4. Install the certificate and key, edit a Sassafras configuration file

There are multiple ways to do each of these steps. The instructions describe two ways to do steps 1 and 3: one way for Windows-based servers, and another way for Unix-based servers (OS X and Linux). Steps 2 and 4 are the same for all platforms. Despite the slight differences on each platform, the results of steps 1-3, a “PKCS#12” (PFX) file, can be used on any platform. That is, you can follow the steps for Unix platforms below, and then use the resulting PFX file on a Windows-based server (and conversely). See also the Windows Specific section for the very brief steps for those familiar with certs already.

For example purposes, we'll assume the host on which the Web service will run is named “server.ad.sample.net”. This is the name that a browser would use to connect to the Web UI running on the host. All of the files that will be created during this process will use that name (with various extensions) in order to keep things organized.

Step 1: Generate a key pair and Certificate Signing Request

The SSL certificate installed by default is self-signed and has a generic host name. This means web browsers will present a warning or error message to the browser user who connects to the Web UI while the default certificate is active. To avoid these messages a new certificate, customized for the host on which the service will run, must be created and signed by a Certificate Authority (CA) that is trusted by the browser. The first step is to generate the private and public key pair and create a Certificate Signing Request (CSR) that will be sent to the trusted CA.

Windows-based servers
The command for creating a CSR can be run on any Windows computer, but it is recommended that you run it on the host that will be running the web service. In any case, the account you use to run the command must have Administrator rights.

First you must create a file that describes the keys to be generated, the host on which the certificate will be used, and other details. Open Notepad or any text editor and create a new file named “server.ad.sample.net.inf” in a convenient location on disk (e.g., on the Desktop). Copy the text below into that document, and change the text indicated in red to match your hostname, state, city, and organization name.

[Version]
Signature="$Windows NT$"

[NewRequest]
;Change to your,country code, company name and common name
Subject = "C=US, ST=Your State, L=Your City, O=Your Organization, CN=server.ad.sample.net"

KeySpec = 1
KeyLength = 2048
Exportable = TRUE
MachineKeySet = TRUE
SMIME = False
PrivateKeyArchive = FALSE
UserProtected = FALSE
UseExistingKeySet = FALSE
ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
ProviderType = 12
RequestType = PKCS10
KeyUsage = 0xa0

[EnhancedKeyUsageExtension]
OID=1.3.6.1.5.5.7.3.1 ; this is for Server Authentication / Token Signing

Save the changes you've made to the file. Open a command prompt window as Administrator. Change to the directory containing the INF file and run this command:

[dos-prompt] certreq -new server.ad.sample.net.inf server.ad.sample.net.csr

When this command runs successfully there will be no messages output to the command prompt window. The command will generate a private/public key pair, which it securely adds to the certificate store of the LocalSystem account. A Certificate Signing Request (CSR) file is also created, which we've named “server.ad.sample.net.csr”. This file is used in the next step.

Unix-based servers
The command for creating a CSR can be run on any Unix computer that has OpenSSL installed. For security you should create a new directory in your home directory and set its permissions so that only you can view files in it. In this example we'll create a directory named "cert" to store the files we'll work on.

[unix-prompt] cd ~
[unix-prompt] mkdir cert
[unix-prompt] chmod 0700 cert
[unix-prompt] cd cert

The command to generate a private/public key pair and Certificate Signing Request will prompt for some identifying information, which will be added to your certificate and will also be used by the Certificate Authority to verify your identity. The text in bold below is the information you should enter (with your own company and host name in place of the examples):

[unix-prompt] openssl req -out server.ad.sample.net.csr -new -newkey rsa:2048 -nodes -keyout server.ad.sample.net.key
Generating a 2048 bit RSA private key
................+++
writing new private key to 'server.ad.sample.net.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:New Hampshire
Locality Name (eg, city) []:Hanover
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Sassafras Software Inc.
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:server.ad.sample.net
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

The command will generate a private key, which it saves in the file named “server.ad.sample.net.key”. This is a very important file that must be kept secret. The matching public key and Certificate Signing Request (CSR) are also created, and placed in a file which we've named “server.ad.sample.net.csr”. This file is used in the next step.

Step 2: Submit the Certificate Signing Request to a trusted Certificate Authority

When a trusted Certificate Authority signs an SSL certificate, browsers can securely verify that the certificate is authentic and can be trusted for secure communication with the web server. All browsers trust a large number of CAs by default, so you can use any of these CAs to sign your certificate. Getting a certificate signed by a trusted CA is typically not free, so which CA you use might depend on cost as well as any policies within your organization. Each CA has their own process for submitting a CSR.

One thing that all CAs will have in common when signing your certificate is that they will need the information in the “server.ad.sample.net.csr” file created in step 1. For some CAs you will submit this file directly. Other CAs will ask you to copy the file's contents (it is a simple text file) and paste them into a text field in a web form. Follow the instructions provided by your chosen CA. You might be required to prove your ownership of the host/domain for which the certificate is being created.

Some CAs might ask you what type of server you will be using the SSL certificate on. For this question, answer “other” if that is an option. Otherwise answer “Apache”.

The process of signing a certificate might take from a few hours to a few days, depending on the level of verification that a CA requires. Once the CA has signed your certificate they will make it available to you, either via their web site or via e-mail. The signed certificate might be provided in the form of a file, or in the form of simple text that can be copied and pasted into a file you create. However it is delivered, save the signed certificate in a file named “server.ad.sample.net.crt”, and save it in the same place as the other files we've created during this process.

Step 3: Accept the signed certificate returned from the Certificate Authority

After a CA has signed your certificate you must accept the signed cert, which matches it with the private key that was generated in step 1. Once accepted, the certificate and key pair can be used for secure communication.

Windows-based servers
The command for accepting a signed certificate must be run on the same computer that you used in step 1, using an account with Administrator rights. Open a command prompt window as Administrator. Change to the directory containing the CRT file you received from the CA and run this command:

[dos-prompt] certreq -accept server.ad.sample.net.crt

When this command runs successfully there will be no messages output to the command prompt window. The command will match your certificate with the private key that was generated in step 1, and add the certificate to the LocalSystem store. From there we will export the signed and matched pair. You can check whether everything worked as expected using the following command:

[dos-prompt] certutil -viewstore MY server.ad.sample.net.crt

This command will display a dialog with information about your certificate:

Click the highlighted link to see more details. You should see that the certificate “ensures the identity of a remote computer”, and that “you have a private key that corresponds to this certificate.”

If everything checks out, you can (if needed) export the certificate and private key to a PKCS#12 (PFX) file. The exported private key needs to be protected with a password. The password should not contain the “:”, “@” or “<” characters. Pick a strong password, e.g., “x3oM.8pv^Eud”. Note this is not needed on Windows in many cases, and it is more secure if you do not do this step. See below for Advanced options in this case.

Back in the command prompt window (running as Administrator), run the following command and enter your chosen password when prompted:

[dos-prompt] certutil -exportpfx server.ad.sample.net server.ad.sample.net.pfx
MY "Personal"
================ Certificate 1 ================
Serial Number: 04
Issuer: E=ca@sassafras.com, CN=Sassafras CA, L=Hanover, S=NH, C=US
 NotBefore: 11/14/2014 2:45 PM
 NotAfter: 8/10/2017 2:45 PM
Subject: CN=server.ad.sample.net, O=Sassafras Software Inc., C=US
Non-root Certificate
Cert Hash(sha1): b8 81 8c 12 aa d4 c7 94 f7 97 6d a1 3c 46 56 c7 dc f2 00 10
  Key Container = 40428c704df5117bccc610b2b9b66276_c1299b2f-7484-4d2e-9fd9-c0e9dccd2284
  Simple container name: CertReq-e0b34435-eec7-4629-a7db-23247a1f8539
  Provider = Microsoft RSA SChannel Cryptographic Provider
Encryption test passed
Enter new password for output file server.ad.sample.net.pfxEnter new password:
Enter new password: x3oM.8pv^Eud
Confirm new password: x3oM.8pv^Eud
CertUtil: -exportPFX command completed successfully.

The output message will be slightly different from the example above, since your host name will be different, as will your organization and CA. The important part is the last line, which indicates the command worked. The certificate and key will have been exported to the “server.ad.sample.net.pfx” file, which will be used in step 4.

Unix-based servers
The private key and signed certificate files are now merged into a PKCS#12 (PFX) file. The private key needs to be protected with a password. The password should not contain the “:”, “@” or “<” characters. Pick a strong password, e.g., “x3oM.8pv^Eud”. Run the following command to place the private key and signed certificate into a password-protected PFX file. Enter your chosen password when prompted.

[unix-prompt] cat server.ad.sample.net.key server.ad.sample.net.crt | openssl pkcs12 -export -out server.ad.sample.net.pfx -name server.ad.sample.net
Enter Export Password: x3oM.8pv^Eud
Verifying - Enter Export Password: x3oM.8pv^Eud

The certificate and key will be exported to the “server.ad.sample.net.pfx” file, which will be used in step 4.

At this point you have four files, only one of which you need to keep. Once you have configured the Sassafras service to use your certificate and have verified that everything works, you should delete all the files except for the PFX file, since they contain sensitive and unencrypted data that is no longer needed. This command will delete the unneeded files (make sure you know the password for the PFX file, otherwise you will have to go through this entire process again):

[unix-prompt] rm server.ad.sample.net.key server.ad.sample.net.crt server.ad.sample.net.crt

Step 4: Install the certificate and key, configure the Web Service

The signed and accepted certificate and key pair must be placed in an accessible location, and the Web service must be configured with some information about the certificate.

Move the “server.ad.sample.net.pfx” file created in step 3 into the KeyReporter Data Folder. If the Web service is running as part of a KeyServer installation, this folder is located within the Helper Data directory within the KeyServer Data Folder. You will also see a file named “kr.conf” in this directory. Open the “kr.conf” file with any text editor and look for the following entry:

<key>certname</key>
<string>keyreporter:Sassafras@kr.pfx</string>

By default this entry points to the self-signed certificate. Change it to point to your customized certificate, with the password you used when exporting the certificate:

<key>certname</key>
<string>server.ad.sample.net:x3oM.8pv^Eud@server.ad.sample.net.pfx</string>

The format of this setting is the subject name of the certificate (which should be the same as the host name of the computer running the Web service, if all of the preceding steps were followed), then the “:” character, then the password used when exporting the certificate and private key, then the “@” character, then the name of the file that contains the certificate and private key.

Once the “server.ad.sample.net.pfx” file is in place next to the “kr.conf” that refers to it, restart the Web process (if it is running as part of the KeyServer installation, run KeyConfigure and select Web Service Settings from the Config Menu, then Stop and Start from there). When the Web service is running again you should be able to connect over HTTPS from any browser. The browser should not display any certificate error message, and instead should indicate that the page is secure. Most browsers show a padlock as an indication of a secure connection.

In most browsers, clicking the padlock icon displays information about the certificate that was used to secure the connection. View the certificate to make sure it is the one you just installed and configured.

The “server.ad.sample.net.pfx” and “kr.conf” files contain sensitive information that you do not want untrusted people to access. It is advisable to set the permissions on these files so that they can only be read by the appropriate accounts (including the account that the Web service runs under).

Windows Specific Information:

While the above has full details for the certificate process that cover a wide array of information, this can often be very simple on a Windows server. If we make a few assumptions:

You are already familiar with obtaining certs and adding them to the Windows Certificate store (using MMC not IIS as we don't use IIS)/ adding your wildcard cert to Windows Server,

You do not have multiple certs for the same DNS name, or multiple certs for multiple cnames,

The KeyServer process is running under the local system account (or you understand using service accounts and delegating rights to them in the cert store),

Your DNS is cleanly configured,

The Hostname setting in the Web settings is correct to match the cert/domain in question,

then it is likely your setup of SSL in the Sassafras server is as easy as putting your certificate in place and restarting the Web UI in KeyConfigure. As of 7.7 we should automatically pick up the certificate if the above conditions are met. Otherwise, you may need to still configure the kr.conf file with the specific cert DNS name in question. It has also been seen where a wildcard would not work without being exported for reasons specific to that cert provider.

On Windows systems it is possible to place the keys and certificate in the secure Windows certificate store instead of in the PFX file. The PFX file is secure, since it is protected by a password, but because the password must be stored in the “kr.conf” file there is the potential that an adversary could get access to the private key (this can be mitigated by setting strict permissions on the “kr.conf” file).

If you want the Web UI to use your keys and certificate from within the Windows certificate store, you should first follow all of the above steps, and make sure that everything works (ultimately, that the browser uses your certificate to create a secure connection). Once that is working properly, follow the instructions below.

The LocalSystem Case: If the Web Service runs in the LocalSystem account AND you performed steps 1-3 on the host computer that runs the service, the keys and certificate are already stored securely in the Windows certificate store. In many cases as of 7.7 this means you are done, but you may need to point the configuration explicitly if there are multiper certs. Open the “kr.conf” file with any text editor and look for the “certname” entry as before. Change it to point to your certificate in the Windows certificate store:

<key>certname</key>
<string>server.ad.sample.net@*</string>

Notice that we've removed the password from the “kr.conf”, so that is no longer a potential security hole. This new setting is telling the Web Service to look for your certificate not in a PFX file, but in the local machine certificate store.

Restart the Web Service and test the browser connection again. Make sure that the browser can create a secure connection, and that your certificate is being used to make the connection. Once you have verified that things are working as expected, you can remove the “server.ad.sample.net.pfx” file from the KeyReporter Data Folder.

You can also use wildcard certificates by specifying the wildcard domain instead of a FQDN, as in *.ad.sample.net. You can also simply specify *@* to say "look for any matching certificate in the cert store". Make sure however if you do this that only one certificate is in the store, otherwise it could pick up the wrong one. This means you should remove older expired certs when renewing as well.

The Service Account Case: If the Web Service runs under a service account you will need to import the “server.ad.sample.net.pfx” file using the “svcpfx.exe” tool provided by Sassafras. Place this tool in the same directory as the PFX file and run this command:

svcpfx -n server.ad.sample.net -p x3oM.8pv^Eud -s KeyServer server.ad.sample.net.pfx

This command assumes you are running the Web Service as part of a KeyServer install. If it is running as a stand-alone service, replace “KeyServer” with “KeyReporter” in the above command. On success, your keys and certificate will be imported from the PFX file into the Windows certificate store, and will be made accessible to the KeyReporter process.

Open the “kr.conf” file with any text editor and look for the “certname” entry as before. Change it to point to your certificate in the Windows certificate store:

<key>certname</key>
<string>server.ad.sample.net@KeyServer</string>

Notice that we've removed the password from the “kr.conf”, so that is no longer a potential security hole. This new setting is telling the Web Service to look for your certificate not in a PFX file, but in the certificate store associated with the KeyServer service. (Again, if it is running as a stand-alone service, replace “KeyServer” with “KeyReporter”.)

Restart the Web Service and test the browser connection again. Make sure that the browser can create a secure connection, and that your certificate is being used to make the connection. Once you have verified that things are working as expected, you can remove the “server.ad.sample.net.pfx” file from the KeyReporter Data Folder.

Security Settings

Setting the Protocol Level
In the kr.conf file, you can add this section:

<key>sslprotocol</key>
<integer>6</integer>

With a value based upon this chart:

0: default, use highest protocol that the client supports
1: SSL2 or higher
2: SSL3 or higher
3: TLS 1.0 or higher
4: TLS highest version supported by client
5: TLS 1.1 or higher
6: TLS 1.2 or higher

This will work for Windows and MacOS based servers. Linux OpenSSL uses a local configuration to determine allowed protocols which is outside our scope and control.

Note that if you are running the Web Service on a Windows Server OS it is advised by Microsoft that you manage these protocols in the OS rather than by the above setting. Set the sslprotocol per above to 0 then manage the host settings in the Windows Registry. See https://docs.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings for more details.

Setting the Ciphers
Also in the kr.conf you can use the following keys to set what cipher suites you want to allow:

By algorithm:

<key>ciphers</key>
<string>AES,ECDH,MD5,SHA1</string>

Allow Windows (only) to pick what it thinks is best:

<key>ciphers</key>
<string>STRONG</string>

Set specific ciphers only:

<key>ciphers</key>
<string>EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH</string>

Note that these options are not available when the Web Service is running on MacOS.

Other Options
Some of these are in newer installations by default, older installations may want to add them for security. Depending on your environment you may need to consider the available values. e.g. If you are embedding Web elements in other pages, or embedding other pages in Dashboard widgets, then certain cross site settings would prevent this from working. These examples are to indicate what options are available, it is left to the customer to determine the best settings for their needs.

<key>headers</key>
<string>
	X-Content-Type-Options: nosniff
	X-XSS-Protection: 1; mode=block
	X-Frame-Options: sameorigin | DENY
	Content-Security-Policy: frame-ancestors 'none' | 'self' https://www.example.org;
</string>

See also:

• X-XSS-Protection
• X-Frame-Options
• Content-Security-Policy

To manage cross site origins use:

<key>corsurl</key>
<string>host.here.org; other.there.net; http://test.cloud.com:8080; https://test.cloud.com:8443</string>