TLS

Valkey GLIDE supports secure TLS connections to a data store.

It’s important to note that TLS support in Valkey GLIDE relies on rusttls. Currently, Valkey GLIDE employs the default rustls settings with no option for customization.

Example: Connecting with TLS Mode Enabled to a Cluster

from glide import (
    GlideClusterClient,
    GlideClusterClientConfiguration,
    NodeAddress
)

addresses = [NodeAddress(host="address.example.com", port=6379)]
client_config = GlideClusterClientConfiguration(addresses, use_tls=True)

client = await GlideClusterClient.create(client_config)

Example: Connecting with TLS Mode Enabled to a Standalone server

from glide import (
    GlideClient,
    GlideClientConfiguration,
    NodeAddress
)

addresses = [
    NodeAddress(host="primary.example.com", port=6379),
    NodeAddress(host="replica1.example.com", port=6379),
    NodeAddress(host="replica2.example.com", port=6379)
  ]
client_config = GlideClientConfiguration(addresses, use_tls=True)

client = await GlideClient.create(client_config)

TLS Advanced Configuration

The TlsAdvancedConfiguration class provides advanced TLS settings for both standalone and cluster clients.

Insecure TLS Mode

Insecure TLS mode bypasses certificate verification. This is useful when connecting to servers using self-signed certificates or when DNS entries don’t match certificate hostnames.

⚠️ Warning: This setting is typically used in development or testing environments. It is strongly discouraged in production, as it introduces security risks such as man-in-the-middle attacks.

Example - Connecting with Insecure TLS Mode

from glide import (
    GlideClusterClient,
    GlideClusterClientConfiguration,
    NodeAddress,
    TlsAdvancedConfiguration,
    AdvancedGlideClusterClientConfiguration
)

tls_config = TlsAdvancedConfiguration(use_insecure_tls=True)

advanced_config = AdvancedGlideClusterClientConfiguration(
    tls_advanced_configuration=tls_config
)

addresses = [NodeAddress(host="address.example.com", port=6379)]
client_config = GlideClusterClientConfiguration(
    addresses,
    use_tls=True,
    advanced_configuration=advanced_config
)

client = await GlideClusterClient.create(client_config)

Custom Root Certificates

You can provide custom root certificates for TLS connections. This is useful when connecting to servers with self-signed certificates or corporate certificate authorities.

Certificate Behavior:

• If root_pem_cacerts is None (default), the system’s default certificate trust store is used
• If root_pem_cacerts is an empty bytes object, an error will be returned
• Certificates must be in PEM format as a bytes object
• Multiple certificates can be provided by concatenating them in PEM format

Example - Connecting with Custom Root Certificate from File

from glide import (
    GlideClusterClient,
    GlideClusterClientConfiguration,
    NodeAddress,
    TlsAdvancedConfiguration,
    AdvancedGlideClusterClientConfiguration
)

# Read certificate file
with open("/path/to/ca-cert.pem", "rb") as f:
    root_cert = f.read()

tls_config = TlsAdvancedConfiguration(root_pem_cacerts=root_cert)

advanced_config = AdvancedGlideClusterClientConfiguration(
    tls_advanced_configuration=tls_config
)

addresses = [NodeAddress(host="address.example.com", port=6379)]
client_config = GlideClusterClientConfiguration(
    addresses,
    use_tls=True,
    advanced_configuration=advanced_config
)

client = await GlideClusterClient.create(client_config)

Example - Using Certificate as Bytes

from glide import (
    GlideClient,
    GlideClientConfiguration,
    NodeAddress,
    TlsAdvancedConfiguration,
    AdvancedGlideClientConfiguration
)

cert_data = b"""-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKL0UG+mRKmzMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
...
-----END CERTIFICATE-----"""

tls_config = TlsAdvancedConfiguration(root_pem_cacerts=cert_data)

advanced_config = AdvancedGlideClientConfiguration(
    tls_advanced_configuration=tls_config
)

addresses = [NodeAddress(host="primary.example.com", port=6379)]
client_config = GlideClientConfiguration(
    addresses,
    use_tls=True,
    advanced_configuration=advanced_config
)

client = await GlideClient.create(client_config)

Example - Multiple Certificates (Certificate Chain)

from glide import (
    GlideClusterClient,
    GlideClusterClientConfiguration,
    NodeAddress,
    TlsAdvancedConfiguration,
    AdvancedGlideClusterClientConfiguration
)

# Read multiple certificate files
with open("/path/to/cert1.pem", "rb") as f:
    cert1 = f.read()
with open("/path/to/cert2.pem", "rb") as f:
    cert2 = f.read()
with open("/path/to/cert3.pem", "rb") as f:
    cert3 = f.read()

# Concatenate certificates
combined_certs = cert1 + cert2 + cert3

tls_config = TlsAdvancedConfiguration(root_pem_cacerts=combined_certs)

advanced_config = AdvancedGlideClusterClientConfiguration(
    tls_advanced_configuration=tls_config
)

addresses = [NodeAddress(host="address.example.com", port=6379)]
client_config = GlideClusterClientConfiguration(
    addresses,
    use_tls=True,
    advanced_configuration=advanced_config
)

client = await GlideClusterClient.create(client_config)

Example - Combining Insecure Mode with Custom Certificates

from glide import (
    GlideClient,
    GlideClientConfiguration,
    NodeAddress,
    TlsAdvancedConfiguration,
    AdvancedGlideClientConfiguration
)

with open("/path/to/ca-cert.pem", "rb") as f:
    root_cert = f.read()

tls_config = TlsAdvancedConfiguration(
    use_insecure_tls=True,
    root_pem_cacerts=root_cert
)

advanced_config = AdvancedGlideClientConfiguration(
    tls_advanced_configuration=tls_config
)

addresses = [NodeAddress(host="primary.example.com", port=6379)]
client_config = GlideClientConfiguration(
    addresses,
    use_tls=True,
    advanced_configuration=advanced_config
)

client = await GlideClient.create(client_config)

TLS Certificate Format

All certificates must be in PEM format. A PEM certificate looks like this:

-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKL0UG+mRKmzMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
...
-----END CERTIFICATE-----

Troubleshooting TLS Connections

Common Issues:

1. Certificate Verification Failed

   • Ensure the certificate is valid and not expired
   • Verify the hostname matches the certificate’s Common Name (CN) or Subject Alternative Name (SAN)
   • Check that the certificate chain is complete

2. Connection Refused

   • Verify the server is configured to accept TLS connections
   • Ensure the port number is correct (typically 6379 for TLS)

3. Empty Certificate Error

   • Do not provide an empty bytes object for root_pem_cacerts
   • Either provide valid certificates or leave it as None to use system certificates

4. File Not Found

   • Verify the certificate file path is correct
   • Ensure the file is accessible with proper read permissions