How to Configure TLS in Redis

How to Configure TLS in Redis

TLS is a secure transport-layer protocol used to encrypt data in transit. Its primary purpose is to prevent man-in-the-middle attacks and protect the data exchanged between clients and the Redis server.

How to Configure TLS

Edit the redis.conf file.

1. Enable the TLS port

port 0           # disable the plaintext port (optional)
tls-port 6380    # enable the TLS port

Or run both plaintext and TLS at once (not recommended for production; production should disable the plaintext port):

port 6379
tls-port 6380

2. Configure the TLS certificate and key

tls-cert-file /etc/redis/redis.crt   # server certificate (PEM)
tls-key-file /etc/redis/redis.key    # private key (PEM); redis.key perms 600, owned by redis user
tls-key-file-pass secret             # private key password, used to decrypt the key

The certificate must be signed by a trusted CA, or you build your own CA and have clients trust it.

3. Configure DH parameters (stronger forward secrecy)

tls-dh-params-file /etc/redis/redis.dh  # DH params file, PEM

Generate the DH params file with openssl:

openssl dhparam -out /etc/redis/redis.dh 2048

4. Configure TLS client authentication

tls-ca-cert-file /etc/redis/ca.crt  # CA certificate file
tls-ca-cert-dir /etc/ssl/certs      # CA certificate directory

Configure at least one of these, used to verify client certificates as well as master/replica and cluster node certificates.

5. Configure client certificate authentication (mutual-TLS control)

tls-auth-client no       # one-way TLS (server-only auth, most common)
tls-auth-client yes      # mutual TLS (both server and client authenticated; default)
tls-auth-client optional # client may optionally present a certificate

In most scenarios tls-auth-client is set to no, and clients authenticate with a password via ACL users.

6. Enable TLS for master-replica replication

tls-replication yes

By default replication does not use TLS; set this to yes to enable it. Both master and replica need TLS certificates and tls-replication yes, and the replica’s replicaof must point at the master’s TLS port.

7. Enable TLS for the cluster

tls-cluster yes

By default the Redis cluster does not use TLS; set this to yes to enable it.

8. Configure TLS protocols and cipher suites

tls-protocols "TLSv1.2 TLSv1.3"   # TLS protocol versions; default is TLSv1.2
tls-ciphers DEFAULT:!MEDIUM       # cipher suites for TLSv1.2 and below
tls-ciphersuites TLS_CHACHA20_POLY1305_SHA256  # TLSv1.3 cipher suite
tls-prefer-server-ciphers yes     # prefer the server's chosen cipher suite

9. Configure the TLS session cache (performance)

tls-session-caching yes    # on by default; no to disable
tls-session-cache-size 20480   # default 20480; 0 means unlimited
tls-session-cache-timeout 300   # timeout 300 seconds

Configuration Example

Step 1: Create a private CA

First create the certificate and key files (self-signed), which you will use to sign the Redis server certificate.

# create the certs directory
mkdir certs

# generate the CA private key
openssl genrsa -out ca.key 4096
# generate the CA certificate
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt -nodes -sha256 -subj "/C=CN/ST=Zhejiang/L=Hangzhou/O=MyOrg/CN=Redis CA"

The resulting ca.crt is the CA certificate. It contains the CA’s public key, the CA’s identity information, the CA’s digital signature (self-signed), its validity period, serial number, and so on. It is used to verify whether other certificates were legitimately signed by this CA. Its security depends on the CA’s private key, which must be kept strictly secret.

Inspect the certificate contents:

openssl x509 -in ca.crt -text

(The output includes Version, Serial Number, Issuer/Subject, Public-Key, X509v3 extensions—including CA:TRUE—and the signature value. The long hexadecimal dump is omitted here.)

Step 2: Create the server Certificate Signing Request (CSR)

A CSR (Certificate Signing Request) is the standardized request file submitted to a CA when applying for a digital certificate. It contains the applicant’s public key and identity information. Its purposes are:

• Securely deliver the public key to the CA without exposing the private key
• Declare the applicant’s identity
• Prepare the data for the CA to sign

# create the server private key
openssl genrsa -out redis.key 2048
chmod 600 redis.key

# generate the server CSR
openssl req -new -key redis.key -out redis.csr -subj "/C=CN/ST=Zhejiang/L=Hangzhou/O=MyOrg/CN=redis.example.com"

You can inspect the CSR:

openssl req -in redis.csr -text

(The output includes Subject, Subject Public Key Info—a 2048-bit RSA public key—and the signature value. The long hexadecimal dump is omitted here.)

To support IPs and multiple domains (via SAN), create a redis.ext file:

cat > redis.ext <<EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names

[alt_names]
DNS.1 = redis.example.com
DNS.2 = localhost
IP.1 = 127.0.0.1
IP.2 = 192.168.232.128   # ← replace with your actual IP
EOF

SAN (Subject Alternative Name) is an X.509 certificate extension that specifies which domain names, IP addresses, or other identifiers a certificate protects. CN (Common Name) is an attribute of the Subject field in an X.509 certificate, used to identify the certificate holder.

Step 3: Sign the certificate with the CA

Based on the CSR, the CA uses its private key and CA certificate to sign the Redis server certificate—in essence, the CA signs the server certificate (the server’s public key) with its private key. Clients use the CA’s public key (from ca.crt) to verify that signature.

openssl x509 -req -in redis.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out redis.crt \
  -days 365 -sha256 \
  -extfile redis.ext
# Certificate request self-signature ok
# subject=C = CN, ST = Zhejiang, L = Hangzhou, O = MyOrg, CN = redis.example.co

ca.srl is the certificate serial-number file, generated and maintained by openssl when signing certificates, ensuring every issued certificate gets a unique, monotonically increasing serial number. The first signing generates ca.srl via -CAcreateserial; later signings read and update it automatically.

# subsequent signings automatically use and update ca.srl
openssl x509 -req -in client.csr \
  -CA ca.crt -CAkey ca.key \
  -CAserial ca.srl \
  -out client.crt -days 365

Step 4: Generate DH parameters for forward secrecy

DH parameters support DHE (Ephemeral Diffie-Hellman) or ECDHE (Elliptic Curve DHE) key exchange, enabling forward secrecy.

openssl dhparam -out redis.dh 2048
chmod 600 redis.dh

After signing, configure the TLS/SSL section of redis.conf (adjust paths to your actual layout):

port 0
tls-port 6380
# server certificate and key
tls-cert-file /etc/redis/certs/redis.crt
tls-key-file /etc/redis/certs/redis.key

# CA certificate (used to verify clients)
tls-ca-cert-file /etc/redis/certs/ca.crt

# DH parameters
tls-dh-params-file /etc/redis/certs/redis.dh

# client cert auth: no = server-only auth (one-way TLS)
tls-auth-client no

# enable TLS for replication; master no, replica yes
tls-replication no

# allow only secure protocols
tls-protocols "TLSv1.2 TLSv1.3"

# cipher suites (disable weak algorithms)
tls-ciphers DEFAULT:!MEDIUM
tls-ciphersuites TLS_CHACHA20_POLY1305_SHA256

# prefer the server's chosen cipher suite
tls-prefer-server-ciphers yes

The replica needs replicaof, pointing at the master’s TLS port:

replicaof 127.0.0.1 6380

Clients must present the CA certificate when connecting (provided by the CA, or, for a self-built CA, securely distributed by the service provider to the application). The client uses ca.crt to verify the server certificate—this distribution must happen securely.

./bin/redis-cli --tls --cacert certs/ca.crt -p 6380
127.0.0.1:6380> ping
PONG
127.0.0.1:6380> keys *
(empty array)
127.0.0.1:6380> set k1 v1
OK

Notes

If you enable TLS, you must compile Redis with make BUILD_TLS=yes.

Reference: Redis TLS Support

Master-Replica Replication

The Redis master handles client connections and replica connections the same way, so the tls-port and tls-auth-client directives above also apply to replication connections. On the replica side, set tls-replication yes so that outgoing connections to the master use TLS.

Cluster

When using Redis Cluster, set tls-cluster yes to enable TLS on the cluster bus and cross-node connections.

Sentinel

Sentinel inherits its network configuration from the general Redis configuration, so everything above also applies to Sentinel. When connecting to a master, Sentinel uses the tls-replication directive to decide whether TLS is required. The same tls-replication directive also determines whether Sentinel’s port (accepting connections from other Sentinels) supports TLS—Sentinel uses tls-port if and only if tls-replication is enabled.

Best Practices

1. Create a dedicated ca.srl file for the Redis CA
2. Back up the serial-number file regularly
3. Monitor serial-number usage
4. Automate certificate signing with scripts
5. Ensure the serial-number length is enough for the expected number of certificates

Example directory layout:

/etc/redis/tls/
├── ca/
│   ├── redis-ca.crt
│   ├── redis-ca.key
│   └── redis-ca.srl    # serial-number file
├── server/
│   ├── redis-server.crt
│   └── redis-server.key
└── client/
    ├── redis-client.crt
    └── redis-client.key

Supplementary Background

CA (Certificate Authority): a root certificate authority that creates signatures for other certificates.

Trust analysis: At the root, we trust the CA’s private key, from which the CA certificate is generated. Clients then trust the CA certificate and use it to verify the server’s certificate. The server submits a certificate request to the CA; the CA signs the server certificate (the server’s public key) with its private key, meaning “this server is authenticated by me and is legitimate.” An illegitimate server has no CA signature, and even if it forges a server certificate, the CA’s private key is secret, so the forged certificate cannot pass verification against the client’s CA certificate (the CA’s public key). This guarantees the client can confirm it is talking to a legitimate server.