Gateway Hub

Configure transport layer security

Overview

Transport Layer Security (TLS) is the successor to the now deprecated 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.

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.

Install TLS/SSL certificates

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

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.

Setup TLS using a KeyStore and TrustStore

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 a ssl subsection to the hub section in your JSON configuration file:
    {
        "hub": {
            "ssl": {
                "key_store": "<change me>",
                "key_store_password": "<change me>",
                "key_password": "<change me>",
                "trust_store": "<change me>",
                "trust_store_password": "<change me>",
                "use_default_passwd": false
            }
        }
    }
  2. Change the value of key_store to the location of your JKS KeyStore, this file must named ssl_keystore.
  3. Change the value of trust_store to the location of your TrustStore, this file must be named ssl_truststore.
  4. If you want to be prompted for passwords of the KeyStore and TrustStore omit the lines specifying these passwords.
  5. If you want specify the passwords in the file:
    1. Change the value of trust_store_password to your TrustStore password.
    2. Change the value of key_store_password to your KeyStore password.

    Note: The passwords of the KeyStore and TrustStore must be the same.

  6. Save your file.

For a full JSON configuration, see Examples.

Creating a KeyStore and TrustStore manually

To create the KeyStore and TrustStore you will need the following PEM formatted files, signed by an trusted certificate authority:

  • cert.key
  • cert.crt
  • CA.crt

The cert.crt must have the following OpenSSL extensions:

Extension Value
keyUsage nonRepudiation, digitalSignature, keyEncipherment
extendedKeyUsage serverAuth, clientAuth
subjectAltName List of the FQDNs of all nodes in the Gateway Hub cluster.

To generate the KeyStore and TrustStore files, use the openssl command line tool and the Java keytool:

  1. Create the PKCS12 keystore:

    openssl pkcs12 -export -chain \
        -in <client.crt> \
        -inkey <cert.key> \
        -out <cert.p12> \
        -name <cert_alias> \
        -CAfile <CA.crt> \
        -passout pass:<p12_keystore_password>
  2. Create the JKS ssl_keystore:

    keytool --importkeystore -noprompt \
        -srckeystore <client.p12> \
        -srcstoretype PKCS12 \
        -srcstorepass <p12_keystore_password> \
        -destkeystore ssl_keystore \
        -deststorepass <ssl_keystore_password>
  3. Import the CA certificate inside the ssl_keystore:

    keytool -importcert -trustcacerts -noprompt \
        -file <CA.crt> \
        -keystore ssl_keystore \
        -alias caroot \
        -keypass <ssl_keystore_password> \
        -storepass <ssl_keystore_password>
  4. Create the ssl_truststore:

    keytool -importcert -trustcacerts -noprompt \
        -file <CA.crt> \
        -keystore ssl_truststore \
        -alias <cert_alias> \
        -keypass <ssl_truststore_password> \
        -storepass <ssl_truststore_password>

This will create the ssl_keystore and ssl_truststore files.

Caution: You must not change the names of these files. Gateway Hub will search for files named ssl_keystore and ssl_truststore, if it cannot find them it will not start correctly.

Examples

Example with password prompts

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.
  • 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": {
		"user" : "hub",
		"group" : "gateway-hub",
		"ssl": {
			"key_store": "/tmp/ssl_keystore",
			"trust_store": "/tmp/ssl_truststore"
		}
	}
}

Example using SSH key

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. We must provide the FQDN of the host.
  • 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": {
		"user" : "hub",
		"group" : "gateway-hub",
		"ssl": {
			"key_store": "/tmp/ssl_keystore",
            		"key_store_password" "hub123", 
			"trust_store": "/tmp/ssl_truststore",
			"trust_store_password": "hub123",
			"key_password": "hub123"
		}
	}
}