Configure transport layer security

Overview

Transport Layer Security (TLS) is the successor to the now depreciated Secure Sockets Layer (SSL). TLS certificates ensure that the communication between Gateway Hub nodes and client applications are secured.

A default installation of Gateway Hub will automatically generate self-signed certificates for TLS/SSL. However, self-signed certificates should not be used in a production environment and many applications will report security errors when self-signed certificates are encountered.

When running Gateway Hub in production, you must provide trusted TLS/SSL certificates. You should obtain the certificate files for your subdomain from your system administrator. These must be generated using fully qualified domain names (FQDNs), IP addresses are not supported.

Install TLS/SSL certificates

Production installation

To configure Gateway Hub to use TLS/SSL provide a .pem file that contains all the required keys and certificates. If this file has been encrypted you must also provide a password for decryption.

You should create an SSL section in the JSON configuration file with the following form:

{
    "hub": {
        "ssl": {
            	"pem_file":"<change me>",
         	"pem_file_password":"<change me>"
        }
    }
}

To install the TLS certificates to a Gateway Hub node, follow these steps:

  1. Navigate to the hub folder.
  2. Run hubctl setup ssl <JSON file>, replacing <JSON file> with the location of your JSON file.
  3. When you see the following message:
    ##########################################################################
    # WARNING! This will stop the Hub while the SSL certificates are installed
    ##########################################################################
    
    Are you sure you wish to do this? [y/N]
    Press y followed by Enter on your keyboard to continue with the installation of the certificates.
  4. Wait for the installation to finish.

Success: The PLAY RECAP output on the command line states a number of ok or changed configurations, and zero unreachable or failed, similar to the example below:

PLAY RECAP *******************************************************************
node1.example.itrs.com : ok=287  changed=183  unreachable=0    failed=0
localhost                  : ok=6    changed=0    unreachable=0    failed=0

Success

If the installation fails, please consult your system administrator. Installations may fail if certificates are incorrectly configured, such as using IP addresses rather than FQDNs or an invalid chain of trust.

Self-signed certificate Installation

You can configure Gateway Hub to use self-signed certificates for use in testing or development.

Caution: Self-signed certificates should not be used in production environments.

To use self-signed TLS/SSL certificates you should set the SSL section in the JSON configuration file to an empty object.

{
	"ssl": {}
}

To generate and install self-signed TLS/SSL certificates on a Gateway Hub node, follow these steps:

  1. Go to the folder called hub in your chosen directory.
  2. Run hubctl setup ssl --self-signed <JSON file>, replacing <JSON file> with the location of your JSON file.
  3. When you see the following message:
    ##########################################################################
    # WARNING! This will stop the Hub while the SSL certificates are installed
    ##########################################################################
    
    Are you sure you wish to do this? [y/N]
    Press y followed by Enter on your keyboard to continue with the installation of the certificates.
  4. When you see the following message:
    #####################################################################################################
    WARNING! You're generating SSL self signed certificate, this is only
    recommended to use in a Test/Demo Environment. Generated important
    files under '/tmp/tmpV87RsW/hub-cert-output', it's recommended to save it to a private location.
    #####################################################################################################

    Press y followed by Enter on your keyboard to continue with the installation of the certificates.

  5. Wait for the installation to finish.

Success: The PLAY RECAP output on the command line states a number of ok or changed configurations, and zero unreachable or failed, similar to the example below:

PLAY RECAP *******************************************************************
node1.example.itrs.com : ok=287  changed=183  unreachable=0    failed=0
localhost                  : ok=6    changed=0    unreachable=0    failed=0

Success

The installation scripts produce the following files:

File Description
cert.key The private key used by Gateway Hub. Use this to connect to the Gateway Hub.
cert.crt The self-signed certificate used by Gateway Hub. Use this to connect to the Gateway Hub.
CA.crt The certificate of your local certificate authority. Add this to your browser to trust the self-signed certificates, this removes any SSL warnings.

These files are located at /opt/hub/self-signed/ . If the default Gateway Hub installation path has been changed, they will be available at /<path_to_hub_installation>/self-signed/.

Trusting Gateway Hub

To establish secure connections to Gateway Hub all client applications, such as web browsers or Grafana, must trust the CA certificates used to sign Gateway Hub TLS/SSL certificates.

Caution: If you replace the certificates used by Gateway Hub you must sure the new certificates are trusted by all client applications.