TLS

Humio can use HTTPS/TLS to communicate securely with external services such as bucket storage, webhook actions, or authentication providers. From version 1.13.0, Humio follows the Mozilla intermediate compatibility configuration by default when making requests and the Humio cluster is internally using TLS. From version 1.17.0, Humio follows this configuration by default, irrespective of whether it is serving TLS or not.

From version 1.13.0, the accepted protocols and ciphers can be changed by setting TLS_PROTOCOLS and TLS_CIPHER_SUITES, respectively. TLS_PROTOCOLS and TLS_CIPHER_SUITES are both comma-separated lists where TLS_PROTOCOLS must be a list of Java protocol names and TLS_CIPHER_SUITES must be a list of Java cipher suite names. Note that the order matters as the earliest protocols and cipher suites in the lists will be preferred.

TLS to external services requires no configuration, but does not encrypt internal communication. From version 1.13.0, Humio can encrypt internal 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.

From version 1.17, Humio automatically reloads certificates should they change on disk. This will currently only update the keystore and truststore used by Humio in serving HTTPS and making HTTPS requests. Kafka and Zookeeper certificates will not be updated.

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.

Server Name Indication (SNI)

Humio supports presenting multiple certificates using the SNI TLS extension. The alias of the keys in the keystore must match the hostname specified in the SNI header. For example, if Humio receives a TLS connection with humio.example.com in the SNI header, then Humio will present the private key with the alias humio.example.com or an arbitrary key if no key with a matching alias is found.

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.

TLS_TRUSTSTORE_LOCATION=/path/to/truststore
TLS_TRUSTSTORE_PASSWORD=sometruststorepassword
#  TLS_TRUSTSTORE_TYPE=PKCS12
TLS_KEYSTORE_LOCATION=/path/to/keystore
TLS_KEYSTORE_PASSWORD=somekeystorepassword
#  TLS_KEYSTORE_TYPE=PKCS12
TLS_KEY_PASSWORD=somekeypassword
#  TLS_SERVER=true
#  TLS_CLIENT_AUTH=true
#  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
#  TLS_CLIENT_ALIAS=humio.example.com
#  TLS_DEFAULT_ALIAS=humio.example.com

For more information on each of these environment variables, see the Configuration reference page.

Explicit Zookeeper & Kafka Settings

The above will use the same keystore and truststore to communicate with other Humio nodes, 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] (/reference/configuration/kafka-config/#additional-kafka-client-properties).