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

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.

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"
		}
	}
}