Last updated: 2026-06-25

CockroachDB TLS/SSL Configuration Guide

This guide provides recommended TLS/SSL settings for CockroachDB, a distributed SQL database. CockroachDB uses TLS for all inter-node and client-to-node communication in secure mode. Unlike most databases, CockroachDB requires TLS for production deployments and provides built-in tooling for certificate management.

Prerequisites#

• CockroachDB 25.x or later
• The cockroach CLI tool (includes certificate generation utilities)

CockroachDB is built with Go's crypto/tls library, which provides strong TLS defaults including TLS 1.2 and TLS 1.3 with secure cipher suites out of the box.

Certificate Architecture#

CockroachDB uses a directory-based certificate layout. All certificates are stored in a single --certs-dir directory:

• ca.crt - Certificate authority certificate
• node.crt / node.key - Node certificate and key (for inter-node and client-to-node communication)
• client.root.crt / client.root.key - Root user client certificate

Each node and client user has their own certificate signed by the same CA.

Certificate Generation#

Create the CA#

cockroach cert create-ca \
    --certs-dir=/etc/cockroachdb/certs \
    --ca-key=/etc/cockroachdb/certs/ca.key

Create Node Certificates#

Generate a certificate for each node. Include all hostnames and IP addresses the node will be accessed by:

cockroach cert create-node \
    localhost \
    node1.example.com \
    10.0.0.1 \
    --certs-dir=/etc/cockroachdb/certs \
    --ca-key=/etc/cockroachdb/certs/ca.key

For additional nodes, generate certificates on each machine or copy the ca.crt and ca.key and generate locally:

cockroach cert create-node \
    localhost \
    node2.example.com \
    10.0.0.2 \
    --certs-dir=/etc/cockroachdb/certs \
    --ca-key=/etc/cockroachdb/certs/ca.key

Create Client Certificates#

Generate a client certificate for the root user (required for administration):

cockroach cert create-client root \
    --certs-dir=/etc/cockroachdb/certs \
    --ca-key=/etc/cockroachdb/certs/ca.key

For application users:

cockroach cert create-client appuser \
    --certs-dir=/etc/cockroachdb/certs \
    --ca-key=/etc/cockroachdb/certs/ca.key

File Permissions#

chmod 700 /etc/cockroachdb/certs
chmod 600 /etc/cockroachdb/certs/*.key
chmod 644 /etc/cockroachdb/certs/*.crt
chown -R cockroach:cockroach /etc/cockroachdb/certs

Starting a Secure Cluster#

Start each node with the --certs-dir flag to enable TLS:

cockroach start \
    --certs-dir=/etc/cockroachdb/certs \
    --advertise-addr=node1.example.com \
    --join=node1.example.com,node2.example.com,node3.example.com \
    --store=/var/lib/cockroachdb

Omitting --certs-dir and using --insecure instead disables all TLS. Never use --insecure in production.

Initialize the cluster (first time only):

cockroach init --certs-dir=/etc/cockroachdb/certs --host=node1.example.com

Using External Certificates#

If you prefer to use certificates from an external CA (Let's Encrypt, internal PKI, etc.) instead of CockroachDB's built-in tool:

1. Place the CA certificate at certs/ca.crt
2. Place the node certificate and key at certs/node.crt and certs/node.key
3. Place client certificates at certs/client.<username>.crt and certs/client.<username>.key

The node certificate must include the node's hostname and IP in the SAN (Subject Alternative Name) field.

TLS Defaults#

CockroachDB is built with Go's crypto/tls library, which enforces TLS 1.2 as the minimum version by default. Go's default cipher suites are secure and include only AEAD ciphers with forward secrecy (AES-GCM, ChaCha20-Poly1305) using ECDHE key exchange.

CockroachDB does not expose cluster settings to change the minimum TLS version or cipher suites. The TLS configuration is determined by the Go runtime version used to build CockroachDB. Upgrading CockroachDB automatically picks up any TLS improvements in newer Go releases.

Client Connections#

cockroach sql#

Connect using the CockroachDB SQL shell:

cockroach sql \
    --certs-dir=/etc/cockroachdb/certs \
    --host=node1.example.com

Connection String#

Use a PostgreSQL-compatible connection string with sslmode and certificate paths:

postgresql://appuser@node1.example.com:26257/mydb?sslmode=verify-full&sslrootcert=/path/to/ca.crt&sslcert=/path/to/client.appuser.crt&sslkey=/path/to/client.appuser.key

Available sslmode values:

• require - Encrypt the connection, don't verify the server certificate
• verify-ca - Encrypt and verify the server certificate against the CA
• verify-full - Encrypt, verify the CA, and verify the server hostname (recommended)

See RFC 8446 §4.3.2 for the TLS Certificate Request specification, and Wikipedia: Mutual authentication for a general overview.

DB Console (Web UI)#

The DB Console is served over HTTPS automatically when the cluster is started in secure mode. Access it at:

https://node1.example.com:8080

Certificate Rotation#

CockroachDB supports online certificate rotation without downtime. To rotate certificates:

1. Generate new certificates with the same CA (or a new CA added to ca.crt)
2. Replace the certificate files in the --certs-dir
3. CockroachDB detects the change and reloads certificates automatically

To manually trigger a reload:

cockroach sql --certs-dir=/etc/cockroachdb/certs -e "SELECT crdb_internal.reload_tls_certificate();"

Security Notes#

CockroachDB uses Go's crypto/tls package, which has a different vulnerability history than OpenSSL:

• POODLE (CVE-2014-3566, 2014): SSL 3.0 has never been supported in Go's TLS implementation.
• BEAST (CVE-2011-3389, 2011): Mitigated by recommending TLS 1.2 as the minimum; AEAD-only ciphers eliminate the CBC padding oracle.
• CRIME (CVE-2012-4929, 2012): TLS compression is not supported in Go's crypto/tls.
• Lucky13 (2013): AEAD-only cipher list eliminates CBC padding timing side-channels entirely.
• FREAK (CVE-2015-0204, 2015): EXPORT-grade ciphers have never been supported in Go's crypto/tls.
• LOGJAM (CVE-2015-4000, 2015): DHE key exchange is not offered by default in Go; only ECDHE is used.
• Sweet32 (CVE-2016-2183, 2016): 3DES was removed from Go's default cipher list in Go 1.23 (August 2024) and is excluded from the recommended configuration.
• ROBOT (2017): Static RSA key exchange is not offered in Go's crypto/tls; only ECDHE is used.
• Downgrade attacks: Go's crypto/tls does not perform insecure version-fallback retries, and TLS 1.3 has built-in downgrade protection.

The following are not addressable through TLS configuration alone:

• Heartbleed (CVE-2014-0160, 2014): Not applicable. Go's crypto/tls is an independent TLS implementation and was never affected by Heartbleed.
• BREACH (CVE-2013-3587, 2013): Not applicable to the SQL wire protocol. The DB Console (web UI) serves HTTP; if HTTP compression is enabled on that interface, apply BREACH countermeasures at the application layer.
• DROWN (CVE-2016-0800, 2016): Not applicable. Go's crypto/tls does not support SSLv2.

Verification#

List all certificates and their expiration dates:

cockroach cert list --certs-dir=/etc/cockroachdb/certs

Check the cluster status:

cockroach node status --certs-dir=/etc/cockroachdb/certs --host=node1.example.com

Test the TLS connection with OpenSSL:

openssl s_client -connect node1.example.com:26257

Verify from the SQL shell:

cockroach sql --certs-dir=/etc/cockroachdb/certs --host=node1.example.com \
    -e "SELECT * FROM crdb_internal.node_build_info;"