Skip to main content
CockroachDB provides enterprise-grade security features including TLS encryption, certificate-based authentication, role-based access control (RBAC), and encryption at rest.

​
Security Architecture

CockroachDB implements a defense-in-depth security model:

Transport Encryption

TLS 1.2/1.3 for all inter-node and client communication

Authentication

Certificate-based and password authentication

Authorization

Role-based access control with granular privileges

Encryption at Rest

AES encryption for data stored on disk

​
Certificate Management

​
Creating the Certificate Authority (CA)

Establish a certificate authority for your cluster:
1

Create CA Certificate

mkdir certs my-safe-directory

cockroach cert create-ca \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key
Store ca.key securely. Anyone with access to this file can create valid certificates for your cluster.
2

Verify CA Creation

ls -l certs/
# Should show: ca.crt

ls -l my-safe-directory/
# Should show: ca.key

​
Creating Node Certificates

Generate certificates for each node in the cluster:
Create Node Certificate
cockroach cert create-node \
  <node-hostname> \
  <node-ip-address> \
  localhost \
  127.0.0.1 \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

cockroach cert create-node \
  node1.example.com \
  10.0.0.1 \
  localhost \
  127.0.0.1 \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key
Include all hostnames, IP addresses, and DNS names that clients might use to connect to the node.

​
Creating Client Certificates

Create certificates for database users:
Root User Certificate
cockroach cert create-client \
  root \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key
Application User Certificate
cockroach cert create-client \
  myapp \
  --certs-dir=certs \
  --ca-key=my-safe-directory/ca.key

​
Certificate Distribution

1

Copy Certificates to Nodes

Each node needs:
  • ca.crt (CA certificate)
  • node.crt (node certificate)
  • node.key (node private key)
# Copy to each node
scp certs/ca.crt node1:/path/to/certs/
scp certs/node.crt node1:/path/to/certs/
scp certs/node.key node1:/path/to/certs/
2

Set Permissions

chmod 600 /path/to/certs/node.key
chmod 644 /path/to/certs/node.crt
chmod 644 /path/to/certs/ca.crt
3

Distribute Client Certificates

Application servers need:
  • ca.crt
  • client.<username>.crt
  • client.<username>.key

​
Starting a Secure Cluster

​
Start Nodes with TLS

Start Secure Node
cockroach start \
  --certs-dir=certs \
  --advertise-addr=<node-address> \
  --join=<node1>,<node2>,<node3> \
  --cache=.25 \
  --max-sql-memory=.25 \
  --background
Omitting --insecure requires TLS certificates. The cluster will not start without proper certificates.

​
Initialize Secure Cluster

cockroach init \
  --certs-dir=certs \
  --host=<any-node-address>

​
Authentication Methods

​
Certificate Authentication

Connect using client certificates:
SQL Client with Certificate
cockroach sql \
  --certs-dir=certs \
  --host=<node-address> \
  --user=root
Application Connection String
postgresql://myapp@node1:26257/mydb?sslmode=verify-full&sslrootcert=certs/ca.crt&sslcert=certs/client.myapp.crt&sslkey=certs/client.myapp.key

​
Password Authentication

Create users with password authentication:
Create User with Password
CREATE USER myuser WITH PASSWORD 'secure-password';
Change User Password
ALTER USER myuser WITH PASSWORD 'new-secure-password';
Connect with Password
cockroach sql \
  --certs-dir=certs \
  --host=<node-address> \
  --user=myuser
# Prompts for password
Password authentication requires TLS encryption. CockroachDB will reject password authentication over insecure connections.

​
Disable Root Password Login

For enhanced security, disable password authentication for the root user: 
SET CLUSTER SETTING server.user_login.password_encryption = 'scram-sha-256';
SET CLUSTER SETTING server.user_login.min_password_length = 12;
SET CLUSTER SETTING server.user_login.root_login.enabled = false;

​
Role-Based Access Control

​
Creating Roles

Create Custom Role
CREATE ROLE developers;
CREATE ROLE analysts;
CREATE ROLE app_writers;

​
Granting Privileges

-- Grant all privileges on database
GRANT ALL ON DATABASE mydb TO developers;

-- Grant specific privileges
GRANT CREATE, DROP ON DATABASE mydb TO developers;

-- Grant read-only access
GRANT SELECT ON DATABASE mydb TO analysts;

​
Assigning Users to Roles

Assign Roles to Users
GRANT developers TO alice, bob;
GRANT analysts TO charlie;
GRANT app_writers TO app_service_account;

​
Viewing Privileges

Show User Grants
SHOW GRANTS ON DATABASE mydb;
SHOW GRANTS ON TABLE mydb.users;
SHOW GRANTS FOR alice;

​
Revoking Privileges

Revoke Access
REVOKE INSERT, UPDATE ON TABLE mydb.users FROM app_writers;
REVOKE developers FROM bob;

​
Network Security

​
Firewall Configuration

Configure firewalls to allow only necessary traffic:
  • 26257: Inter-node and client SQL connections (TCP)
  • 8080: Admin UI and HTTP endpoints (TCP)
  • 26258: Internal communication (TCP, optional)
Firewall Rules:
  • Allow port 26257 from application servers to database nodes
  • Allow port 26257 between all database nodes
  • Restrict port 8080 to admin networks only
  • Block all other inbound traffic

​
Connection Security

Enforce SSL Connections
SET CLUSTER SETTING server.host_based_authentication.configuration = 
'host all all all cert-password';

​
Bind Address Configuration

Restrict Listening Address
cockroach start \
  --certs-dir=certs \
  --listen-addr=10.0.0.1:26257 \
  --http-addr=10.0.0.1:8080 \
  --advertise-addr=node1.example.com:26257
Use --listen-addr to bind to specific network interfaces. Never use 0.0.0.0 in production unless behind a firewall.

​
Encryption at Rest

Enable encryption for data stored on disk:
Enable Encryption at Rest
cockroach start \
  --certs-dir=certs \
  --store=path=/data,encryption-type=aes-128-gcm,key=/path/to/store.key \
  --advertise-addr=<node-address> \
  --join=<join-addresses>

​
Managing Encryption Keys

1

Generate Store Key

openssl rand -hex 32 > store.key
chmod 600 store.key
2

Rotate Encryption Keys

Generate a new key and update cluster settings:
openssl rand -hex 32 > store-new.key
Restart nodes with the new key configuration.

​
Audit Logging

Enable audit logging for compliance and security monitoring:
Enable Audit Logging
ALTER TABLE mydb.sensitive_data SET (
  sql_audit = 'all'
);
Audit Specific Operations
ALTER TABLE mydb.users SET (
  sql_audit = 'read_write'
);

​
Viewing Audit Logs

Audit events are logged to the SQL audit log: 
tail -f /path/to/cockroach-data/logs/cockroach-sql-audit.log

​
Security Best Practices

1

Use Certificate Authentication

Prefer certificate-based authentication over passwords for automated systems and inter-service communication.
2

Implement Least Privilege

Grant users and applications only the minimum privileges required for their function.
3

Rotate Certificates Regularly

Establish a certificate rotation schedule (annually or more frequently) and automate the process.
4

Enable Encryption at Rest

Use encryption at rest for all production clusters, especially those handling sensitive data.
5

Secure the Admin UI

Restrict Admin UI access to VPN or internal networks and use certificate authentication.
6

Monitor Authentication Failures

Set up alerts for repeated authentication failures which may indicate attacks.
7

Regular Security Audits

Periodically review user privileges, roles, and access patterns.

​
Certificate Expiration Monitoring

Check Certificate Expiration
SELECT 
  node_id,
  expiration,
  expiration - now() AS time_until_expiry
FROM crdb_internal.node_certificates
ORDER BY expiration;
Certificate expiration will cause node failures. Monitor certificate expiration dates and rotate well before expiry.

​
Troubleshooting Security Issues

​
Certificate Errors

Certificate Not Found

Verify file paths and permissions in --certs-dir

Certificate Expired

Generate new certificates and distribute to nodes

Hostname Mismatch

Recreate certificates with correct hostnames/IPs

CA Verification Failed

Ensure all nodes use the same CA certificate

​
Authentication Failures

Check User Permissions
SHOW GRANTS FOR myuser;
SHOW ROLES;
Verify User Exists
SELECT * FROM system.users WHERE username = 'myuser';

​
Security Checklist

  • TLS enabled for all connections
  • Certificate-based authentication configured
  • Strong passwords enforced (min 12 characters)
  • Root password login disabled
  • Principle of least privilege applied to all users
  • Firewall rules configured to restrict access
  • Encryption at rest enabled
  • Audit logging enabled for sensitive tables
  • Certificate expiration monitoring in place
  • Regular security audits scheduled
  • Admin UI access restricted to internal networks
  • Backup encryption enabled
  • Connection strings secured (no hardcoded passwords)
  • Network segregation between tiers

​
Next Steps

Backup & Restore

Secure your backup strategy

Migration

Securely migrate data

Upgrade

Upgrade with security in mind

Build docs developers (and LLMs) love

Get started for freeTalk to us