TLS

LogScale can use HTTPS/TLS to communicate securely with external services such as bucket storage, webhook actions, or authentication providers. LogScale follows the Mozilla intermediate compatibility configuration by default when making requests and the LogScale cluster is internally using TLS.

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. 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. LogScale can encrypt internal communication using TLS to/from ZooKeeper, Kafka, and other LogScale 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).

Warning

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:

  • Have the certificate of each node in the truststore.

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

Enabling LogScale Communication Encryption

Enabling encryption for network traffic within a LogScale cluster involves configuring TLS for ZooKeeper, Kafka, and LogScale itself.

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

Important

Kafka and ZooKeeper both refer to TLS encryption as SSL. SSL is an older, deprecated cryptographic protocol that has been superseded by TLS. Both Kafka and ZooKeeper use TLS, even though the configuration settings refer to it as SSL.

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

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

LogScale automatically reloads certificates should they change on disk. This will currently only update the keystore and truststore used by LogScale in serving HTTPS and making HTTPS requests. Kafka and ZooKeeper certificates will not be updated.

Client Authentication

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

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

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

Server Name Indication (SNI)

LogScale 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 LogScale receives a TLS connection with instance.example.com in the SNI header, then LogScale will present the private key with the alias instance.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 LogScale-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.

ini
# Configs that are commented out are optional.

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

# Password to unlock the truststore
TLS_TRUSTSTORE_PASSWORD=sometruststorepassword

# The type of the truststore. Can either be PKCS12, JKS, or JCEKS.
# If this is not specified, the type will be inferred from the truststore filename extension,
# defaulting to PKCS12 if none can be inferred.
#  TLS_TRUSTSTORE_TYPE=PKCS12

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

# Password to unlock keystore
TLS_KEYSTORE_PASSWORD=somekeystorepassword

# Type of keystore. Same as for TLS_TRUSTSTORE_TYPE
#  TLS_KEYSTORE_TYPE=PKCS12

# Password to unlock the individual key within the keystore
TLS_KEY_PASSWORD=somekeypassword

# Whether to serve TLS. This is enabled by default when a keystore is defined.
# This can be used to enable TLS when using a key in the system keystore instead.
#  TLS_SERVER=true

# Whether to enable client auth. See the above "Client Authentication" section.
#  TLS_CLIENT_AUTH=false

# TLS configuration. Default corresponds with the Mozilla Intermediate Compatility
# configuration
#  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

# The alias of the private key in the keystore to use when LogScale makes requests.
# If not specified, an arbitrary private key is used.
#  TLS_CLIENT_ALIAS=humio.example.com

# The alias of the private key in the keystore to use when LogScale can not determine a suitable
# private key via SNI. If not specified, an arbitrary private key is used.
#  TLS_DEFAULT_SERVER_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 LogScale 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 LogScale docker image, this can be done by setting the HUMIO_OPTS environment variable. For example, you can use a specific truststore and keystore for ZooKeeper like so:

ini
HUMIO_OPTS=                                                        \
    -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 reference page.