Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

TLS

Last updated
All Cloud plansOn-Premise: no license needed

HotKV encrypts connections with TLS 1.2 and 1.3 (through OpenSSL). It can serve plain and TLS clients on two ports at once, or TLS only; it can require client certificates (mutual TLS); and it can encrypt the links between the nodes of a cluster. The directives have the same names as in Redis, so a Redis TLS configuration carries over.

The directive table with every default is on the Security page. This page shows how to put the pieces together.

HotKV Cloud

Section titled “HotKV Cloud”

Every HotKV Cloud instance accepts TLS connections only, on the port shown on its Connection tab. Each instance has its own host name, such as k7f3q9x2ab.hotkv.io, with a certificate from Let’s Encrypt that is renewed automatically before it expires. Clients need no CA file: turn on TLS (--tls, a hotkvs:// or rediss:// URL, or the SDK’s TLS option) and connect to the host name exactly as shown, so that the certificate’s name matches. See Quick start: HotKV Cloud.

The rest of this page is about HotKV On-Premise.

Turn on TLS

Section titled “Turn on TLS”

Give the server a certificate, its private key, and a port:

tls-port 6380
tls-cert-file /etc/hotkv/tls/server.crt
tls-key-file /etc/hotkv/tls/server.key

Both files are PEM. tls-cert-file may hold the full chain (the server certificate followed by its intermediates). For a key protected with a passphrase, set tls-key-file-pass. The plain port keeps serving next to the TLS port.

In hotkv.toml the same settings go under [tls], without the tls- prefix and with underscores:

[tls]
port = 6380
cert_file = "/etc/hotkv/tls/server.crt"
key_file = "/etc/hotkv/tls/server.key"

Check the connection:

Terminal window
hotkv-cli --tls -h db.example.com -p 6380 -a "$PASSWORD" PING
# PONG

TLS only, or TLS for remote clients

Section titled “TLS only, or TLS for remote clients”

To refuse plain connections entirely, set port 0:

port 0
tls-port 6379
tls-cert-file /etc/hotkv/tls/server.crt
tls-key-file /etc/hotkv/tls/server.key

To keep plain connections for local tools while every remote client must use TLS, give the TLS listener its own address:

bind 127.0.0.1
port 6379
tls-bind 0.0.0.0
tls-port 6380
tls-cert-file /etc/hotkv/tls/server.crt
tls-key-file /etc/hotkv/tls/server.key
requirepass "a-long-random-password"

Remote clients still need a password: protected mode applies to the TLS port as it does to the plain one.

Mutual TLS

Section titled “Mutual TLS”

With a CA configured, HotKV asks every TLS client for a certificate signed by that CA, and refuses clients without one:

tls-ca-cert-file /etc/hotkv/tls/ca.crt
tls-auth-clients yes

tls-ca-cert-dir names a directory of CA certificates instead (in OpenSSL’s hashed layout, as openssl rehash makes it). tls-auth-clients decides what happens to clients:

Value Clients
yes (default) Must present a certificate the CA signed
optional May present one; if they do, it must verify
no Are not asked for a certificate

By default, a client certificate proves only that the client holds a certificate from your CA, and the client still authenticates with a password or an ACL user. With tls-auth-clients-user CN the certificate also logs the client in, with no password, as the ACL user named by its common name (URI uses the first URI subject alternative name that is an enabled user). A name that is no enabled user leaves the client the default user, and it may still AUTH.

Connect with a client certificate:

Terminal window
hotkv-cli --tls -h db.internal -p 6380 --cacert ca.crt \
  --cert client.crt --key client.key PING

Protocols and ciphers

Section titled “Protocols and ciphers”
Directive Default Description
tls-protocols TLS 1.2 and 1.3 Versions to allow, for example "TLSv1.3". TLSv1 and TLSv1.1 are allowed only when listed.
tls-ciphers OpenSSL’s default Cipher list for TLS 1.2 and lower, in OpenSSL’s syntax
tls-ciphersuites OpenSSL’s default Ciphersuites for TLS 1.3, such as TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
tls-prefer-server-ciphers yes Use the server’s cipher order rather than the client’s
tls-dh-params-file DH parameters, for DHE cipher suites
tls-session-caching yes Let clients resume TLS sessions
tls-session-cache-size 20480 Sessions kept for resumption (0 for no limit)
tls-session-cache-timeout 300 Seconds a session can be resumed

An invalid cipher list stops the start (or fails the CONFIG SET that sets it) rather than falling back to defaults.

TLS between nodes

Section titled “TLS between nodes”

tls-cluster yes encrypts the cluster bus and tls-replication yes the replication links. They use the same tls-cert-file, tls-key-file and CA, and do not need a tls-port: clients can stay on plain connections or use TLS too.

tls-cert-file /etc/hotkv/tls/node.crt
tls-key-file /etc/hotkv/tls/node.key
tls-ca-cert-file /etc/hotkv/tls/ca.crt
tls-cluster yes
tls-replication yes

On these links:

  • Both sides present certificates, always. Each node checks the other’s certificate against the CA, whatever tls-auth-clients says (that setting is for clients). A CA is required: a node with either setting and no tls-ca-cert-file or tls-ca-cert-dir does not start. The names in the certificates are not checked unless you set tls-expected-peer-name to one or more names that the other node’s certificate must carry, so without it use a CA that signs certificates for your nodes only.
  • Plain connections are refused on the bus port (with tls-cluster) and the replication port (with tls-replication). Turn the setting on for every node of a cluster, or a primary and all its replicas, in the same restart.
  • Changing them. tls-replication needs a restart. tls-cluster can be changed with CONFIG SET: bus connections made from then on follow it, links that are already up keep what they have, and turning it on without a certificate is refused.
  • Passwords still apply. A replica still proves it knows the replication password inside the TLS link.

If your node certificates are issued for server use only (extended key usage serverAuth without clientAuth), the other node refuses them on the links a node opens. Give each node a client certificate for those links:

tls-client-cert-file /etc/hotkv/tls/node-client.crt
tls-client-key-file /etc/hotkv/tls/node-client.key

Set both together (and tls-client-key-file-pass for an encrypted key).

With tls-cluster yes and a tls-port, a node goes by its TLS port in the cluster, as in Redis: its bus listens on the TLS port + 10000 unless you set cluster-port, and clients connected over TLS are given TLS ports in redirects, CLUSTER SLOTS and CLUSTER NODES. For a walkthrough with certificates, ports and the log lines of a failed handshake, see Cluster over TLS, and see Clustering.

Renew certificates without a restart

Section titled “Renew certificates without a restart”

CONFIG SET on any certificate, key, CA or cipher setting reloads TLS:

CONFIG SET tls-cert-file /etc/hotkv/tls/server.crt tls-key-file /etc/hotkv/tls/server.key

Setting a file to the path it already has reloads it, so a renewal job only needs to replace the files and run that command. New connections use the new certificate at once, on the client port and on the cluster bus and replication links; connections already open keep theirs. If the new files cannot be loaded (missing, unreadable, or a key that does not match the certificate), the command fails with ERR Unable to update TLS configuration: ..., the previous settings are restored, and the server keeps serving the old certificate.

The settings that reload this way are tls-cert-file, tls-key-file, tls-key-file-pass, tls-ca-cert-file, tls-ca-cert-dir, tls-auth-clients, tls-protocols, tls-ciphers, tls-ciphersuites, tls-dh-params-file, tls-client-cert-file, tls-client-key-file, tls-client-key-file-pass and tls-expected-peer-name. By default HotKV does not watch the files for changes: run the CONFIG SET after each renewal, or set tls-auto-reload-interval to a number of seconds (0, the default, is off) and the server looks at the certificate, key, CA and DH files that often and reloads TLS by itself when one changed, so a renewal only has to replace the files. A reload that fails is logged and the certificates in use stay.

CONFIG SET tls-port moves or opens the TLS listener at runtime when a certificate is configured, and tls-port 0 closes it as long as the plain port stays open. tls-bind needs a restart.

Production checklist

Section titled “Production checklist”
  • Use certificates from a CA you trust (an internal PKI, or a public CA for names clients reach over the internet).
  • Keep tls-protocols at TLS 1.2 and 1.3 or stricter.
  • Set a CA and tls-auth-clients yes when only your own clients should connect.
  • Turn on tls-cluster and tls-replication when nodes talk over a network you do not control.
  • Automate renewal: replace the files, then run CONFIG SET, or let tls-auto-reload-interval reload them.
  • Keep a password or ACL users on: TLS encrypts the connection but does not decide who may run commands.

Next steps

Section titled “Next steps”