# TLS

> Encrypt client connections, require client certificates, secure the cluster bus and replication links, and renew certificates without a restart.

URL: https://docs.hotkv.com/operate/tls/


**Availability:** All HotKV Cloud plans. On-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](https://docs.hotkv.com/security/index.md#tls)
page. This page shows how to put the pieces together.

## 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](https://docs.hotkv.com/quickstart-cloud/index.md#3-get-your-connection-details).

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

## 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:

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

Check the connection:

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

> **Note**
> Under the packaged systemd service the server runs as the `hotkv` user, so
> that user needs read access to the certificate and key files, for example
> `chown root:hotkv` and `chmod 640` on the key.

## 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](https://docs.hotkv.com/security/index.md#protected-mode)
applies to the TLS port as it does to the plain one.

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

> **Caution**
> Client certificates are checked only when `tls-ca-cert-file` or
> `tls-ca-cert-dir` is set. Set a CA whenever you rely on client
> certificates.

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](https://docs.hotkv.com/operate/acl/index.md). 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:

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

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

`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](https://docs.hotkv.com/clustering/tls/index.md), and see [Clustering](https://docs.hotkv.com/clustering/index.md).

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

- 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

- [Security](https://docs.hotkv.com/security/index.md#tls): the full directive table.
- [hotkv-cli](https://docs.hotkv.com/get-started/hotkv-cli/index.md#tls): TLS options of the client.
- [Connecting and SDKs](https://docs.hotkv.com/sdks/index.md): TLS in client libraries.