Enabling HTTPS (SSL) for KeyReporter

KeyReporter 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 KeyReporter 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, configure KeyReporter

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 KeyReporter (and conversely).

For example purposes, we'll assume the host on which KeyReporter will run is named “server.ad.sample.net”. This is the name that a browser would use to connect to web services (KeyReporter) 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 with KeyReporter while the default certificate is active. To avoid these messages a new certificate, customized for the host on which KeyReporter 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 KeyReporter. 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.

> Show how to generate a certificate signing request on Mac OS X Server using the GUI

Since Mac OS X Server includes OpenSSL, it is possible to use the command for creating a CSR, as described above. Alternatively, the CSR can be created in the Mac OS X Server program. First select Certificates in Mac OS X Server and choose “Get a Trusted Certificate” from the “+” menu.

The Certificate Signing Request must include some identifying information, which will be added to your certificate and will also be used by the Certificate Authority to verify your identity. Enter your own company and host name in place of the examples:

You will be prompted to save the CSR, which we have named “server.ad.sample.net.csr”. This file will be used in the next step. You should see the new certificate in the Certificates list, marked as “Pending”.

There will be a private/public key pair stored in the System container of the KeyChain.

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.”

> Show how to check that the certificate was accepted using the GUI

From the Start menu (or the command prompt), run “mmc.exe” (Microsoft Management Console). From the File menu choose Add/Remove Snap-in. In the Add/Remove Snap-in dialog locate the Certificates snap-in and click Add (shown below).

Click on Computer account, then Next (shown below).

Verify that the Local Computer is selected and click Finish (shown below).

Click OK in the Add/Remove Snap-in dialog, and the main MMC window will now contain a Certificates container as shown below. Expand the Certificates and Personal containers and click the Certificates folder, as shown below. You should see the Certificate you created in the list on the right.

Double-click on the certificate to see more information. 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.” Click OK to dismiss this window.

If everything checks out, you can 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”. 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.

> Show how to export using the GUI

If you prefer to use the GUI to export the certificate and private key, you can do so using the Microsoft Management Console Certificates Snap-in. Expand and read the section “Show how to check that the certificate was accepted using the GUI” above for instructions on opening the Certificates snap-in. Once you've opened the Certificates Snap-in, select the certificate and right-click to choose the Export task, as below.

Wonder in the glory that is the “Welcome to the Certificate Export Wizard” page. Then click Next.

Choose to export the private key, then click Next.

We need a PKCS#12 (PKS) file, and it's good to have the full certification path as well. Click Next.

The exported PFX file will contain the private key, which needs to be protected with a password. Type a strong password, but do not use the “:”, “@” or “<” characters. Next.

Save the exported certificate in a file named “server.ad.sample.net.pfx”, in keeping with our file naming convention. Next.

We're almost there. Double-check that the settings are correct in the somewhat cramped final page, then click Finish.

If all goes well, the export will succeed.

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've got KeyReporter configured 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

> Show how to accept and export a signed certificate on Mac OS X Server using the GUI

If the CSR was created using the Mac OS X Server program, it must also be accepted using the same program (on the same computer where the CSR was generated). First select Certificates in Mac OS X Server and double-click the pending certifiate. Drag the “server.ad.sample.net.crt” (returned from the Certificate Authority) onto the window as shown:

Assuming the signed certificate matches a key pair stored on the Mac OS X Server computer, you will then be able to click OK to accept the signed certificate.:

Once the signed certificate has been accepted it should change from “Pending” status to short the appropriate expiration.

The certificate and key pair are stored in the KeyChain on the Mac OS X Server computer. These must be exported to a PFX file in order to be used in the next step. To export the certificate and key pair, run KeyChain Access and find the items. The picture below shows that searching for the server name “server.ad.sample.net” matches three items. Select only the certificate and private key items, leaving the public key unselected, then right click and choose “Export 2 items” from the menu.

You will be prompted to save the file. Make sure that the file format is “Personal Information Exchange (.p12)”, and save the file in a location that is convenient.

Be sure to use a strong password to encrypt the file. This password will be used in the next step.

The file will be saved with the extension “.p12”, so after the save is complete use the Finder to change the file extension to “.pfx”.

Step 4: Install the certificate and key, configure KeyReporter

The signed and accepted certificate and key pair can be used by KeyReporter, but first it must be placed in an accessible location, and KeyReporter 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 KeyReporter 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 folllowing 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 KeyReporter, 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 KeyReporter process (if KeyReporter is running as part of the KeyServer installation, run KeyConfigure and select KeyReporter Settings from the Config Menu, then Stop and Start KeyReporter from there). When KeyReporter 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 KeyReporter runs under).

Advanced: Storing the keys and certificate securely on Windows-based servers
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 KeyReporter 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 KeyReporter runs in the LocalSystem account AND you performed steps 1-3 on the host computer that runs KeyReporter, the keys and certificate are already stored securely in the Windows certificate store. 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 KeyReporter to look for your certificate not in a PFX file, but in the local machine certificate store.

Restart the KeyReporter process 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.

The Service Account Case: If KeyReporter runs in 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 KeyReporter as part of a KeyServer install. If KeyReporter 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 KeyReporter to look for your certificate not in a PFX file, but in the certificate store associated with the KeyServer service. (Again, if KeyReporter is running as a stand-alone service, replace “KeyServer” with “KeyReporter”.)

Restart the KeyReporter process 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.