Gateway Hub

Configure transport layer security

Overview

After installation of Gateway Hub, you must add valid TLS/SSL certificates to the nodes in the cluster.

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. Obtain the certificate files for your subdomain from your system administrator.

How to install TLS certificates

Default installation

Gateway Hub is configured to use TSL/SSL by default. During installation, the Gateway Hub will extract the appropriate domain name from the JSON configuration file and create a valid wildcard certificate. Self-signed certificates must not be used in production.

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

Production installation

TLS/SSL certificates can only be added to a node after a successful installation of Gateway Hub.

Make sure you have configured your JSON file with the correct information. See Add TLS information to JSON file.

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

  1. Go to the folder called hub in your chosen directory.
  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

Re-install self-signed certificates

Gateway Hub uses self-signed certificates for TLS/SSL by default. If you have replaced the certificates generated during installation you can generate new self-signed certificates.

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

If you are using self-signed TLS/SSL certificates you should omit the contents of the SSL section in the JSON configuration file.

{
	"ssl": {}
}

To generate and install self-signed TLS certificates to 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

Add TLS information to JSON file

To install the TLS/SSL certificates for Gateway Hub, you must add another section to the JSON file. Use the same JSON file that you made in the installation procedure.

Set up TLS using a PEM file

You can set up TLS/SSL in Gateway Hub by providing a single server.bundle.pem file that contains all the required keys and certificates. Gateway Hub uses this file to generate KeyStore and TrustStore files for TLS/SSL.

The server.bundle.pem file must have the following structure:

-----BEGIN PRIVATE KEY-----
Private Key
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
Certificate (Subject Alternative Name=www.mydomain.com)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Intermediate (Intermediate CA, if exists)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Root (ROOT CA, who signs the Certificate)
-----END CERTIFICATE-----

Note: This file must be formatted using Linux end of line characters.

Caution: The domain specified in the Subject Alternative Name must match the Gateway Hub domain. If it does not, then TLS/SSL connection will fail.

To use the server.bundle.pem file, add a ssl subsection to the hub section of your JSON configuration file containing the following:

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

Encryption

If the server.bundle.pem file contains an encrypted private key you must specify a pem_file_password. If the private key is encrypted this will be indicated in the private key header. The pem_file_password must be at least 6 characters in length.

The KeyStore and TrustStore files that Gateway Hub generates are encrypted using a default password.

For a full JSON configuration, see Examples.

Examples

Basic example

In the following example:

  • We have included the value connection.ask-pass, so are being prompted for the password of the setup user.
  • This host has an installation user hub-setup.
  • We are installing to the host hub.example.com. We must provide the FQDN of the host.
  • This host has a runtime user hub.
    • The runtime user is in group gateway-hub.
{
	"connection": {
		"ask_pass": true,
		"user": "hub-setup"
	},
	"hosts": ["hub.example.com"],
	"hub": {
		"user" : "hub",
		"group" : "gateway-hub",
		"ssl": {
            		"pem_file":"<change me>",
         		"pem_file_password":"<change me>"
        	}
	}
}