Create certificates

Create self-signed certificates to install on a Redis Software cluster.

Redis Software

When you first install Redis Software, self-signed certificates are created to enable encryption for Redis Software endpoints. These certificates expire after a year (365 days) and must be renewed.

You can renew these certificates by replacing them with new self-signed certificates or by replacing them with certificates signed by a certificate authority (CA).

Renew self-signed certificates

As of v6.2.18-70, Redis Software includes a script to generate self-signed certificates.

By default, the generate_self_signed_certs.sh script is located in /opt/redislabs/utils/.

Here, you learn how to use this script to generate new certificates and how to install them.

Generate self-signed certs script options

You can run the generate_self_signed_certs.sh script with the following options:

Option Description
-h
--help		 Displays usage instructions. (Optional)
-d <days>
--days <days>		 Number of days the self-signed certificate is valid for. Setting this field longer than a year (365 days) is not recommended. (Optional, default: 365)
-f <names>
--fqdnNames <names>		 Space-separated list of fully qualified domain names (FQDNs). Used for Subject Alternative Names (SANs). (Required)
Example: -f "redis.example.com redis-1.example.com"
-t <type>
--type <type>		 Type of certificate to generate. (Optional, default: all)
Values:
cm: Cluster Manager UI certificate
api: REST API certificate
proxy: database endpoint proxy certificate
syncer: syncer component certificate
metrics: metrics exporter certificate
all: generates all certificate types

Step 1: Generate new certificates

Sign in to the machine hosting the cluster's master node and then run the following command:

% sudo -u redislabs /opt/redislabs/utils/generate_self_signed_certs.sh \
   -f "<DomainName1 DomainName2>" -d <Days> -t <Type>

When you run the script, it either reports success ("Self signed cert generated successfully") or an error message. Use the error message to troubleshoot any issues.

The following example generates all self signed certificates for mycluster.example.com; these certificates expire one year after the command is run:

$ sudo -u redislabs /opt/redislabs/utils/generate_self_signed_certs.sh \
    -f "mycluster.example.com"`

Suppose you want to create a Cluster Manager UI certificate to support two clusters for a period of two years. The following example shows how:

$ sudo -u redislabs /opt/redislabs/utils/generate_self_signed_certs.sh \
    -f "mycluster.example.com anothercluster.example.com" -d 730 -t cm

Here, a certificate file and certificate key are generated to support the following domains:

mycluster.example.com
*.mycluster.example.com
anothercluster.example.com 
*.anothercluster.example.com

Step 2: Locate the new certificate files

When successful, the script generates two .PEM files for each generated certificate: a certificate file and a certificate key, each named after the type of certificate generated (see earlier table for individual certificate names.)

These files can be found in the /tmp directory.

$ ls -la /tmp/*.pem

Step 3: Set permissions

We recommend setting the permissions of your new certificate files to limit read and write access to the file owner and to set group and other user permissions to read access.

$ sudo chmod 644 /tmp/*.pem

Step 4: Replace existing certificates

You can use rladmin to replace the existing certificates with new certificates:

$ rladmin cluster certificate set <CertName> certificate_file \
   <CertFilename>.pem key_file <KeyFilename>.pem

The following values are supported for the <CertName> parameter:

Value Description
api The REST API
cm The Cluster Manager UI
metrics_exporter The metrics exporter
proxy The database endpoint
syncer The synchronization process

You can also use the REST API. To learn more, see Update certificates.

Create CA-signed certificates

You can use certificates signed by a certificate authority (CA) for Redis Software cluster security.

For best results, use the following guidelines to create the certificates.

Certificate requirements

  • Certificates must include both of the following in the extended key usage extension:

    • TLS Web Server Authentication (OID: 1.3.6.1.5.5.7.3.1)

    • TLS Web Client Authentication (OID: 1.3.6.1.5.5.7.3.2)

    Warning:
    Using certificate templates that only include Server Authentication will cause SSL and TLS errors.

  • Include the full certificate chain when creating certificate .PEM files. List certificates in order from leaf to root. Some deployments may not require the root CA in the certificate file.

    -----BEGIN CERTIFICATE-----
<Leaf/Domain Certificate>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Intermediate CA Certificate>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Root CA Certificate>
-----END CERTIFICATE-----

  • The Subject Alternative Name (SAN) extension must include the following DNS entries based on your cluster's fully qualified domain name (FQDN):

    dns=<cluster-fqdn>
dns=*.<cluster-fqdn>
dns=internal.<cluster-fqdn>
dns=*.internal.<cluster-fqdn>

    For example, if the cluster FQDN is redis.example.com, the DNS entries include:

    dns=redis.example.com
dns=*.redis.example.com
dns=internal.redis.example.com
dns=*.internal.redis.example.com

  • The key usage extension must include:

    • Digital Signature

    • Key Encipherment

  • Use the cluster's fully qualified domain name (FQDN) for the Common Name (CN).

  • Use SHA-256 or SHA-512 for the signature algorithm.

    Note:
    SHA-1 is deprecated and may be blocked by some operating systems.

  • The minimum RSA key size is 2048 bits. 4096 bits is recommended for enhanced security.

  • A validity period of 1 year or less is recommended.

Create certificates with OpenSSL

  1. Create a configuration file named redis-cert.cnf with the following content:

    [req]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn
req_extensions = v3_req

[dn]
C = US
ST = California
L = Los Angeles
O = Your Organization
CN = redis-cluster.example.com

[v3_req]
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = redis-cluster.example.com
DNS.2 = *.redis-cluster.example.com
DNS.3 = internal.redis-cluster.example.com
DNS.4 = *.internal.redis-cluster.example.com

    Replace redis-cluster.example.com with your cluster's FQDN and replace the [dn] section with your own details. Check with your security team or certificate authority for help creating a valid configuration file for your environment.

  2. Create a private key:

    openssl genrsa -out redis-key.pem 2048

    For enhanced security, use a 4096-bit key:

    openssl genrsa -out redis-key.pem 4096

  3. Create a certificate signing request (CSR):

    openssl req -new \
    -key redis-key.pem \
    -out redis-cert.csr \
    -config redis-cert.cnf

  4. Verify the certificate signing request and submit it to your CA.

  5. Create a certificate chain file.

Submit CSR to the certificate authority

  1. Before submitting to your CA, verify the certificate signing request contains all required attributes:

    openssl req -text -noout -verify -in redis-cert.csr

    Check the output for the following:

    • Subject contains the correct Common Name.

    • Subject Alternative Names include all required DNS entries.

    • Key Usage includes Digital Signature, Key Encipherment.

    • Extended Key Usage includes TLS Web Server Authentication, TLS Web Client Authentication.

  2. Submit redis-cert.csr to your certificate authority for signing. The process varies by CA:

    • For an internal CA, follow your organization's certificate request process.

    • For a commercial CA, use their web portal or API.

    • For testing or development purposes only, you can create a self-signed certificate:

      openssl x509 -req \
  -in redis-cert.csr \
  -signkey redis-key.pem \
  -out redis-cert.pem \
  -days 365 \
  -extensions v3_req \
  -extfile redis-cert.cnf
      Warning:
      Do not use self-signed certificates in production.

Create a certificate chain file

After receiving the signed certificate from your CA, create a certificate chain file by combining the certificates in the correct order:

cat redis-cert.pem intermediate-ca.pem root-ca.pem > redis-cert-chain.pem

You must order your certificates as follows:

  1. Leaf certificate, which is your domain certificate.

  2. Intermediate CA certificates.

  3. Root CA certificate, which is optional depending on your deployment.

Create certificates with Windows Active Directory Certificate Services

To create certificates using Windows Active Directory Certificate Services:

  1. Complete the prerequisites.

  2. Create a modified Web Server template.

  3. Publish the template.

  4. Request a certificate using certreq.

  5. Export the certificate and private key.

Prerequisites

Before you can create certificates with Windows Active Directory Certificate Services, you need:

  • Access to Windows Active Directory Certificate Services.

  • Permissions to modify certificate templates.

  • Certificate Templates Console certtmpl.msc.

Create certificate template

The default Web Server template in Windows AD CS only includes Server Authentication. You must create a modified template that includes both Server and Client Authentication.

  1. Open the Certificate Templates Console as an administrator:

    certtmpl.msc

  2. Right-click the Web Server template, then select Duplicate Template.

  3. In the General tab:

    1. Set Template name to Redis Software Server.

    2. Set the Validity period to 1 year.

  4. In the Extensions tab:

    1. Select Application Policies.

    2. Click Edit and verify both of the following are present:

      • Server Authentication (1.3.6.1.5.5.7.3.1)

      • Client Authentication (1.3.6.1.5.5.7.3.2)

    3. If Client Authentication is missing, click Add, select Client Authentication, and click OK.

  5. In the Subject Name tab, select Supply in the request to allow specifying Subject Alternative Names during the certificate request.

  6. In the Extensions tab:

    1. Select Key Usage.

    2. Click Edit.

    3. Make sure Digital signature and Key encipherment are selected.

  7. In the Security tab:

    1. Add appropriate users and groups.

    2. Grant Read and Enroll permissions.

  8. Click OK to save the template.

Publish the template

  1. Open the Certification Authority console:

    certsrv.msc

  2. Expand your CA.

  3. Right-click Certificate Templates, then select New > Certificate Template to Issue.

  4. Select Redis Software Server and click OK.

Request a certificate using certreq

  1. Create a certificate request file redis-cert.inf:

    [NewRequest]
Subject = "CN=redis-cluster.example.com,O=Your Organization,L=City,ST=State,C=US"
KeyLength = 2048
KeySpec = 1
Exportable = TRUE
MachineKeySet = TRUE
ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
RequestType = PKCS10

[Extensions]
2.5.29.17 = "{text}"
_continue_ = "dns=redis-cluster.example.com&"
_continue_ = "dns=*.redis-cluster.example.com&"
_continue_ = "dns=internal.redis-cluster.example.com&"
_continue_ = "dns=*.internal.redis-cluster.example.com"

    Replace redis-cluster.example.com with your cluster's FQDN.

  2. Generate the certificate request:

    certreq -new redis-cert.inf redis-cert.req

  3. Submit the request to your CA:

    certreq -submit -config "CA-SERVER\CA-Name" redis-cert.req redis-cert.cer

  4. Accept the issued certificate:

    certreq -accept redis-cert.cer

Export certificate and private key

  1. Open Certificate Manager:

    certlm.msc

  2. Go to Personal > Certificates.

  3. Right-click your certificate, then select All Tasks > Export.

  4. Export the certificate with the private key:

    1. Select Yes, export the private key.

    2. Choose Personal Information Exchange - PKCS #12 (.PFX).

    3. Set a password.

    4. Save as redis-cert.pfx.

  5. Convert the certificate and key to PEM format using OpenSSL:

    1. Extract the certificate chain:

      openssl pkcs12 -in redis-cert.pfx -nokeys -out redis-cert.pem

    2. Extract the private key:

      openssl pkcs12 -in redis-cert.pfx -nocerts -out redis-key.pem -nodes

Validate certificates

Before you upload certificates to Redis Software, validate that they meet all requirements:

  1. Validate extended key usage:

    openssl x509 -in redis-cert-chain.pem -text -noout | grep -A 3 "Extended Key Usage"

    Expected output:

    X509v3 Extended Key Usage:
    TLS Web Server Authentication, TLS Web Client Authentication

    If Client Authentication is missing, the certificate will fail. You must reissue the certificate with both Server and Client Authentication.

  2. Validate key usage:

    openssl x509 -in redis-cert-chain.pem -text -noout | grep -A 2 "Key Usage"

    Expected output:

    X509v3 Key Usage: critical
    Digital Signature, Key Encipherment

  3. Validate Subject Alternative Names:

    openssl x509 -in redis-cert-chain.pem -text -noout | grep -A 10 "Subject Alternative Name"

    Expected output:

    X509v3 Subject Alternative Name:
    DNS:redis-cluster.example.com
    DNS:*.redis-cluster.example.com
    DNS:internal.redis-cluster.example.com
    DNS:*.internal.redis-cluster.example.com

  4. Validate certificate chain:

    1. Count the certificates in the chain:

      grep -c "BEGIN CERTIFICATE" redis-cert-chain.pem

      Expected output: 2 or 3 if the root CA is included.

    2. View all certificates in the chain:

      openssl crl2pkcs7 -nocrl -certfile redis-cert-chain.pem | \
    openssl pkcs7 -print_certs -text -noout | \
    grep -E "Subject:|Issuer:"

    3. Verify the chain order. Each certificate's Issuer should match the Subject of the next certificate.

  5. Validate the signature algorithm:

    openssl x509 -in redis-cert-chain.pem -text -noout | grep "Signature Algorithm"

    Expected output: sha256WithRSAEncryption or sha512WithRSAEncryption.

    Note:
    Avoid sha1WithRSAEncryption because it is deprecated and might be blocked.

  6. Validate the public key size:

    openssl x509 -in redis-cert-chain.pem -text -noout | grep "Public-Key"

    Expected output: Public-Key: (2048 bit) or higher.

  7. Verify the private key matches the certificate:

    1. Get the certificate modulus:

      openssl x509 -noout -modulus -in redis-cert-chain.pem | openssl md5

    2. Get the key modulus:

      openssl rsa -noout -modulus -in redis-key.pem | openssl md5

    3. If the MD5 hashes do not match, you have the wrong private key file.

  8. Verify the certificate is currently valid and not expired:

    openssl x509 -in redis-cert-chain.pem -noout -dates

Install certificates

After creating and validating your certificates, install them on the Redis Software cluster:

  1. Set restrictive file permissions for the private key:

    $ chmod 600 redis-key.pem
$ chown redislabs:redislabs redis-key.pem

  2. Set readable file permissions for the certificate:

    $ chmod 644 redis-cert-chain.pem
$ chown redislabs:redislabs redis-cert-chain.pem

  3. Replace the existing certificates with the new certificates using rladmin cluster certificate:

    rladmin cluster certificate set <cert-name> \
    certificate_file /path/to/redis-cert-chain.pem \
    key_file /path/to/redis-key.pem

    Replace <cert-name> with the relevant certificate name:

    Value Description
    api REST API certificate
    cm Cluster Manager UI certificate
    metrics_exporter Metrics exporter certificate
    proxy Database endpoint proxy certificate
    syncer Synchronization process certificate

  4. Check certificate status:

    rladmin status certificates

  5. View certificate details:

    rladmin info cluster

Troubleshooting

SSLV3_ALERT_UNSUPPORTED_CERTIFICATE error

If the certificate's extended key usage does not include TLS Web Client Authentication, the following error occurs:

[SSL: SSLV3_ALERT_UNSUPPORTED_CERTIFICATE] ssl/tls alert unsupported certificate

To fix this error:

  1. Validate extended key usage:

    openssl x509 -in redis-cert-chain.pem -text -noout | grep -A 3 "Extended Key Usage"

  2. If Client Authentication is missing, reissue the certificate:

    • For OpenSSL, add the following line to the configuration file.

      extendedKeyUsage = serverAuth, clientAuth

    • For Windows AD CS, modify the certificate template and add Client Authentication to Application Policies.

CERTIFICATE_VERIFY_FAILED error

If a CERTIFICATE_VERIFY_FAILED error occurs, the certificate chain is incomplete or in the wrong order.

To fix this error:

  1. Verify the certificate chain order. Each certificate's Issuer should match the Subject of the next certificate.

    openssl crl2pkcs7 -nocrl -certfile redis-cert-chain.pem | \
    openssl pkcs7 -print_certs -text -noout | \
    grep -E "Subject:|Issuer:"

  2. Rebuild the certificate chain in the correct order:

    -----BEGIN CERTIFICATE-----
<Leaf/Domain Certificate>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Intermediate CA Certificate>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Root CA Certificate>
-----END CERTIFICATE-----

Key values mismatch error

If a key_values_mismatch error occurs, the private key does not match the certificate.

Verify the private key matches the certificate:

  1. Get the certificate modulus:

    openssl x509 -noout -modulus -in redis-cert-chain.pem | openssl md5

  2. Get the key modulus:

    openssl rsa -noout -modulus -in redis-key.pem | openssl md5

  3. If the MD5 hashes don't match, you have the wrong private key file. To fix this error, find the correct private key file.

Missing Subject Alternative Names

If a certificate only has a Common Name, but no Subject Alternative Names, modern TLS implementations might reject it.

To fix this issue, reissue the certificate with proper Subject Alternative Names, including all required DNS entries.

RATE THIS PAGE
Back to top ↑