TLS

Overview

From version 1.13.0, Humio can encrypt communication using TLS to/from Zookeeper, Kafka, and other Humio nodes. To enable encryption, two files must be provided: a truststore containing the public certificates to trust, and a keystore containing the private key to identify the node.

The truststore and keystore can be either JKS or PKCS12 (recommended).

Due to how Java reads PKCS12 files, certificates in a PKCS12 truststore must be marked with a bag attribute with OID 2.16.840.1.113894.746875.1.1 or they will not be recognized. The easiest way of ensuring this is to create the truststore PKCS12 file using the JDK Keytool.

TLS uses public certificates and private keys to encrypt communication. Generally, you either:

  1. Have the certificate of each node in the truststore.
  2. Have a certificate authority (CA) in the truststore and use the CA to sign certificates of each node.

One benefit of the CA approach is that it allows adding new nodes without updating old nodes. A downside is that there is no convenient way of revoking access other than replacing the CA certificate.

Encrypting Humio

Encrypting a Humio cluster involves configuring TLS for Zookeeper, Kafka, and Humio itself.

See how to encrypt Zookeeper in the Zookeeper SSL user guide and how to encrypt Kafka in the Kafka SSL user guide.

Note that, due to historical reasons, Kafka and Zookeeper both refer to TLS encryption as SSL. SSL is an older, deprecated cryptographic protocol that has been superceeded by TLS. Both Kafka and Zookeeper use TLS, even though the configuraion settings refer to it as SSL.

By default, Humio will encrypt Humio-to-client, Humio-to-Humio, Humio-to-Kafka and Humio-to-Zookeeper using the same truststore and keystore if no explicit Kafka or Zookeeper encryption settings are set.

When Humio makes a HTTPS client request, the Humio truststore and system truststore is used. This enables Humio to communicate with other Humio nodes and also with external services such as Amazon S3 or Google Cloud Storage.

Client Authentication

Humio can use TLS client authentication. When client authentication is enabled, Humio will only accept traffic that can present a trusted certificate. This adds an additional layer of security by verifying that the machine contacting Humio is one known by Humio.

This is only used for allowing/rejecting requests to Humio, not for authentication within Humio. A user/machine with a trusted certificate will still need to log in to Humio or provide a token as proof of identity.

Unlike when Humio makes a HTTPS request, client authentication requires the client to be in the Humio truststore - not just the system truststore.

Example

The example below details only the settings required for Humio-to-X connections. In order for all traffic to be encrypted you must also setup encryption on the Kafka-to-Kafka, Kafka-to-Zookeeper and Zookeeper-to-Zookeeper traffic as described in the user guides above.

Example

# The path to the truststore
TLS_TRUSTSTORE_LOCATION=/path/to/truststore

# The password to unlock the truststore, if any
TLS_TRUSTSTORE_PASSWORD=sometruststorepassword

# The type of the truststore. Can either be PKCS12 or JKS.
# If not set, the type will be inferred from the filename extension
#  TLS_TRUSTSTORE_TYPE=PKCS12

# The path to the keystore
TLS_KEYSTORE_LOCATION=/path/to/keystore

# The password to unlock the keystore, if any
TLS_KEYSTORE_PASSWORD=somekeystorepassword

# The type of the keystore. Can either be PKCS12 or JKS.
# If not set, the type will be inferred from the filename extension
#  TLS_KEYSTORE_TYPE=PKCS12

# The key password.
# For PKCS12, this should be the same as the keystore password.
TLS_KEY_PASSWORD=somekeypassword

# Whether Humio should use TLS when serving the web interface, API, and
# internal API. This is enabled by default if keystore is provided.
# This is useful if you eg. want Humio to present a specific certificate
# when doing HTTPS client requests (for eg. TLS authentication), but do
# not need a fully encrypted Humio cluster. 
#  TLS_SERVER=true

# Whether to require TLS client authentication. Defaults to false.
#  TLS_CLIENT_AUTH=true

# Which TLS protocols and cipher suites to allow when communicating.
# If not set, then Humio follows Mozilla's intermediate compatility. See
# https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28recommended.29
#  TLS_PROTOCOLS=TLSv1.2,TLSv1.3
#  TLS_CIPHER_SUITES=TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

Explicit Zookeeper and Kafka settings

The above will use the same keystore and truststore to communicate with other Humio node, Zookeeper, and Kafka. If you want to use different keystores, you can configure settings explicitly for Zookeeper and Kafka.

For Zookeeper clients, setting Zookeeper SSL settings is done using JVM arguments. In setups using the official Humio docker image, this can be done by setting the HUMIO_JVM_ARGS environment variable. For example, you can use a specific truststore and keystore for Zookeeper like so:

HUMIO_JVM_ARGS=                                                    \
    -Dzookeeper.ssl.keyStore.location="/path/to/your/keystore"     \
    -Dzookeeper.ssl.keyStore.password="keystore_password"          \
    -Dzookeeper.ssl.trustStore.location="/path/to/your/truststore" \
    -Dzookeeper.ssl.trustStore.password="truststore_password"

The Kafka SSL configuration parameters can be set using the EXTRA_KAFKA_CONFIGS_FILE detailed on the Kafka configuration page.