SSL Certificate Installation

A properly installed secure sockets layer (SSL) certificate is critical to the secure operation of your SAFR Server. SAFR uses SSL certificates to establish secure network connections and data transfers. (i.e. https connections) SAFR requires https connections between SAFR Servers and between SAFR Servers and iOS Mobile clients. None of the other SAFR components require https connections.

Before you can install an SSL certificate on your SAFR Server, you must first configure a Domain Name System (DNS) hostname for your server within your network domain, as described below.

DNS Hostnames

If you do not currently have a domain, you need to first obtain a domain name registered and configured with an accredited domain registrar.

How to Obtain a Domain Name

In order to set up a DNS, you need a domain within which you can register hostnames. ICANN maintains a list of accredited registrars from which to choose.

The following is a list of common registrars:

Follow the processes on these websites to find, purchase, and configure your domain name. Most registrars offer the ability to host your DNS for you and most also give you a web interface for managing it.

The following links lead to instructions on how to modify DNS entries:

After you have your domain, you can create a DNS hostname entry for your SAFR Server.

What a DNS Hostname Entry Does

DNS is a system that translates a hostname to a network IP address. For example, when a user types www.example.com into their browser, DNS servers resolve it to the IP address where the website is hosted.

To provide this translation, DNS requires an entry for each hostname. This entry typically takes the form of an A record (the A stands for “Address”) which defines the hostname to IP address translation in DNS. An A record is the most basic type of syntax used in DNS records.

The following is an example of an A record:

safr.example.com    A   12.34.56.78

Set Up a DNS Hostname Entry for your Primary Server

DNS can be managed in numerous ways. This might be a text file or a web interface for configuring the DNS entries. If you are not sure, contact the person managing the domain name for your network.

What Type of IP Address Should I Use?

You should use a static IP address. If you instead choose to use DHCP to get a dynamically assigned IP address, and your IP address happens to change, your DNS hostname entry will stop working until you update the entry.

Configure a Static IP

  1. Obtain a static IP from your network administrator. The information should include the following:
    • Static IP address
    • Subnet mask
    • Default gateway
  2. Configure your system as described below:

The IP address should be the internal IP address of the computer running the SAFR Server. This should not be your public IP address because the public IP address usually points at your router, modem, or similar device. The internal IP address is the IP used locally by the computer. It can be determined by doing the following:

For Windows 10

  1. Open a command prompt (cmd.exe).

  2. Run ipconfig.

  3. The IP address is listed as the IPv4 Address.

For macOS

  1. Open System Preferences.

  2. Open Network.

  3. Click the active network connection (usually WiFi or Ethernet).

  4. The IP address is displayed in the dialog.

SSL Certificates

After you have configured a DNS hostname for your primary server, you can now install an SSL certificate.

What an SSL Certificate Does

SSL certificates are small data files that digitally bind a cryptographic key to an organization’s information. When installed on a server, an SSL certificate allows secure connections from the server to a browser or other program and protects sensitive information.

A common use for SSL certificates is to enable a web server to provide a secure connection with a web browser (i.e. an https:// connection instead of an http:// connection).

Obtain an SSL Certificate

SSL certificates need to be issued from either a trusted certificate authority or from an accredited domain registrar.

Browsers, operating systems, and mobile devices maintain lists of trusted certificate authority root certificates, which must be present on a computer for it to trust the certificate.

The following is a list of popular certificate authorities from which you can obtain an SSL certificate:

Go to ICANN for a complete list of accredited domain registrars.

Because SAFR uses Apache as its web server, request SSL certificate files for Apache web server. You will receive the following three files SAFR uses to configure the Apache web server:

Note: Self-signed certificates do not work.

Provision SSL Certificates for your Primary Server

Do the following to configure Apache to serve the request over HTTPS:

  1. Log in to your primary server.

  2. It is recommended that you make a backup of the default SSL files and save them in case you need to perform a rollback to the earlier version.

    • On macOS, back up the following files:
      • /etc/apache2/ssl/SAFR.key
      • /etc/apache2/ssl/SAFR.crt
    • On Windows, back up the following files:
      • C:\Program Files\RealNetworks\SAFR\httpd\conf\ssl\SAFR.key
      • C:\Program Files\RealNetworks\SAFR\httpd\conf\ssl\SAFR.crt
    • On Linux, back up the following files:
      • /opt/RealNetworks/SAFR/httpd/ssl/SAFR.key
      • /opt/RealNetworks/SAFR/httpd/ssl/SAFR.crt
  3. Upload the certificate-related files to the SSL certificate folder:

    • SSLCertificateFile – Certificate CRT
    • SSLCertificateKeyFile – Private.a key file
  4. Change the names of the following files:

    • Rename *_certificate.crt to SAFR.crt
    • Rename *_private.key to SAFR.key
  5. If your certificate authority provided an intermediate certificate chain, do the following:

    1. Save your SSL intermediate certificate chain file to the following location:
      • On macOS:
        • /etc/apache2/ssl/SAFR-ca.crt
      • On Windows:
        • C:\Program Files\RealNetworks\SAFR\httpd\conf\ssl\SAFR-ca.crt
      • On Linux:
        • /opt/RealNetworks/SAFR/httpd/ssl/SAFR-ca.crt
    2. Check the SAFR-ssl-cert.inc file to connect your SSL certificate to the certificate chain.
      • On macOS:

        • /etc/apache2/other/SAFR-ssl-cert.inc
        • #Define ssl_certificate_chain_file "/private/etc/apache2/ssl/SAFR-ca.crt"
      • On Windows:

        • C:\Program Files\RealNetworks\SAFR\httpd\conf\ssl\SAFR-ca.crt
        • #Define ssl_certificate_chain_file "conf/ssl/SAFR-ca.crt"
      • On Linux:

        • /opt/RealNetworks/SAFR/httpd/ssl/SAFR-ca.crt
        • #Define ssl_certificate_chain_file "/opt/RealNetworks/SAFR/httpd/ssl/SAFR-ca.crt"
      • Certificate file mappings

        Certificate file Certificate file in SAFR
        *.domainname.key SAFR.key
        *.domainname_chain.crt SAFR-ca.crt
        *.domainname_public.crt SAFR.crt
  6. Run the SAFR reconfigure script, as described below.

    • On macOS:
      • Open Applications > Utilities > Terminal to open a Terminal window.
      • Run the following command after replacing hostname.domain.com with your hostname and domain:
        • /Library/RealNetworks/SAFR/bin/reconfigure hostname.domain.com
    • On Windows:
      • Enter this command: "C:\Program Files\RealNetworks\SAFR\bin\reconfigure.bat"
      • Enter the hostname and click Yes when prompted if your SSL certificate uses a certificate chain.
      • Click Yes when prompted by User Account Control.
    • On Linux:
      • Open a Terminal window. Run the following command after replacing hostname.domain.com with your hostname and domain:

        • /opt/RealNetworks/SAFR/bin/reconfigure hostname.domain.com
      • Click Yes when prompted by User Account Control.

    See SAFR Support Tools and Scripts for more information about this script.

  7. Verify that your services are running and your SSL certificate is properly installed by opening a browser and opening https://hostname.domain.com:8085/health. (Replace hostname.domain.com with your hostname and domain.)

    You should receive the following message:

    { "status" : "up" }

Troubleshoot

Database Service Down

Problem: You receive an error report saying Database (MongoDB) Service Down when you run the check command after you install SSL.

Solution: The cause may be that the DNS hostname IP is different from the IP when you installed SAFR without SSL installed.

Use the following workaround:

Add the following line to your primary server /etc/hosts file: 127.0.0.1 hostname.domain.com

See Also