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. You must also generate a JKS KeyStore and TrustStore. An example of this can be found here.

In this topic, we will show you how to install the TLS certificates using the command line on your installation machine, then copy the TLS certificates, KeyStore, and TrustStore from your installation machine to the target nodes.

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.

Caution: Due a limitation with MapR your KeyStore and TrustStore password must be the same.

To configure your JSON file, perform the following:

  1. Add the following section to your JSON configuration file:
    {
    	"ansible" : { 
    		"variables" : { 
    			"hub_user": "<change_me>", 
    			"hub_group": "<change_me>" 
    		} 
    	}
    }

    You may have already added an ansible section if you could not provide passwordless sudo access for the Gateway Hub installation user.

  2. Add the following to the hub section in your JSON configuration file:
    {
    	"SSL": {
    		"key_store": "<change_me>",
    		"trust_store": "<change_me>",
    		"trust_store_password": "<change_me>",
    		"key_password": "<change_me>"
    	}
    }
  3. Change the value of key_store to the location of your JKS KeyStore.
  4. Change the value of trust_store to the location of your TrustStore.
  5. One of:
    1. If want to be prompted for the password of the KeyStore and TrustStore:
      1. Delete the line with trust_store_password.
      2. Delete the line with key_password.
    2. If you want enter the passwords in the file:
      1. Change the value of trust_store_password to your TrustStore password.
      2. Change the value of key_password to your KeyStore password.

        Note: The passwords must be the same.

  6. Change the value of hub_user to the runtime user. See Users.
    This is the same user as hub.user in the install step. See Add install information to JSON file.
  7. Change the value of hub_group to group that your runtime user belongs to.
  8. Save your file.

See Examples for a full JSON configuration.

Examples

Example 1

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.
  • The KeyStore we are installing to the Gateway Hub hosts is located at /tmp/ssl_keystore on the installation machine.
  • The TrustStore we are installing to the Gateway Hub hosts is located at /tmp/ssl_truststore on the installation machine.
  • We are not providing any of the password key/value pairs, and therefore are being prompted for the passwords.
  • This host has a runtime user hub.
    • The runtime user is in group gateway-hub.

The JSON configuration file is the following:

{
	"connection": {
		"ask_pass": true,
		"user": "hub-setup"
	},
	"hosts": ["hub.example.com"],
	"hub": {
		"ssl": {
			"key_store": "/tmp/ssl_keystore",
			"trust_store": "/tmp/ssl_truststore"
		}
	}
	"ansible" : { 
		"variables" : { 
			"hub_user": "hub", 
			"hub_group": "gateway-hub"
		} 
	}
}

Example 2

In the next example:

  • The SSH key for the setup user is located at ~/.ssh/HUB-SETUP-KEY.pem on the installation machine, specified with connection.private_key.
  • The hosts have an installation user hub-setup.
  • The hosts are specified in a list in a newline-delimited file at /tmp/hosts on the installation machine.
  • The KeyStore we are installing to the Gateway Hub hosts is located at /tmp/ssl_keystore on the installation machine.
  • The TrustStore we are installing to the Gateway Hub hosts is located at /tmp/ssl_truststore on the installation machine.
  • We are providing the passwords.
  • There is a runtime user on every host called hub.
    • The runtime user is in group gateway-hub.

The JSON configuration file is the following:

{
	"connection": {
		"private_key": "~/.ssh/HUB-SETUP-KEY.pem",
		"user": "hub-setup"
	},
	"hosts_file": "/tmp/hosts",
	"hub": {
		"ssl": {
			"key_store": "/tmp/ssl_keystore",
			"trust_store": "/tmp/ssl_truststore",
			"trust_store_password": "hub123",
			"key_password": "hub123"
		}
	}
	"ansible" : { 
		"variables" : { 
			"hub_user": "hub", 
			"hub_group": "gateway-hub" 
		} 
	}
}

How to install TLS certificates on a server

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.

If successful, 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=80   changed=35   unreachable=0    failed=0
localhost                  : ok=8    changed=0    unreachable=0    failed=0

Success