Use Auto TLS (alpha) to generate security certificates

On this page

To secure your CockroachDB cluster's inter-node and client-node communication, the cluster requires a certificate authority (CA) certificate that is used to sign keys and certificates (SSLs) for:

• Nodes
• Clients
• Optionally: the DB Console.

With Auto TLS, your cluster creates the CA (certificate authority) certificate and key pair required for secure communication with other nodes and clients and then securely distributes these among the nodes. The cluster also creates the additional certificates that each node requires to connect to other nodes and enable connections from clients.

Auto TLS simplifies the default method for creating secure clusters. Rather than manually generating certificates and keys and distributing them to all nodes, you run a one-time cockroach connect command for each node, specifying a common token. A CA cert and key are distributed to all nodes, along with all other certificates that nodes require to communicate with other nodes and with clients, all signed by the CA.

Step 1: Configure nodes

The example commands below must be tailored for your environment and run for each node. In a production environment, this would typically require running the commands once on each machine for the single node that each one hosts. However, these examples depict multiple nodes running on a single machine, varying their ports rather than their hosts.

1. For each node, prepare a directory for the node to use to store the generated certificates and keys.

   cd node1
   mkdir certs
   

   Alternatively, the directory ~/.cockroach-certs is used, by default, if none is specified in the next step.

2. For each node, run cockroach connect. Specify a shared token, certs directory, number of nodes you'll have when starting the cluster, and the address and port on which the node will listen for connections from the others (which defaults to localhost:26257).

   For example, for the first node:

   cockroach connect \
   --listen-addr=localhost:26257 \
   --num-expected-initial-nodes 3 \
   --certs-dir=certs \
   --init-token={secret}
   

   The interface responds that it is waiting for handshake from 2 peers. The cockroach connect process remains active until the specified number of nodes are in communication and the cert distribution is complete.

   Prepare each additional node, specifying the addresses of those to join which are awaiting the handshake.

   cockroach connect \
   --listen-addr=localhost:26258 \
   --num-expected-initial-nodes 3 \
   --join=localhost:26257 \
   --certs-dir=certs \
   --init-token={secret}
   

   cockroach connect \
   --listen-addr=localhost:26259 \
   --num-expected-initial-nodes 3 \
   --join=localhost:26257,localhost:26258 \
   --certs-dir=certs \
   --init-token={secret}
   

   Each node displays feedback as it connects to each peer. For example, the first would report:

   waiting for handshake for 2 peers
   trusted peer: 127.0.0.1:26258
   trusted peer: 127.0.0.1:26259
   

   When the handshakes are successful among all expected nodes, one is automatically selected to generate the certificates and distribute them. It reports that it is generating and sending a cert bundle to its peers, while the others report that they are waiting for and then receiving the cert bundle.

   Finally, all nodes report server certificate generation complete. The certs-dir directory on each is populated with all required files.

3. Run cockroach start for each node. This starts the node, but does not yet initialize the cluster. If testing this process on a single machine, run the following in each node's directory, adjusting the port numbers for each.

  cockroach start \
  --listen-addr=localhost:26257 \
  --certs-dir=certs \
  --join=localhost:26258,localhost:26259
  --http-addr=localhost:8080

Step 2: Create a client certificate for the root user

On any node's machine, manually create the certificate and key pair for the root user.

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

Step 3: Initialize the cluster

Run cockroach-init.

cockroach init --certs-dir=certs --host=localhost:26257

Step 4: Create additional users to administer the cluster

1. Using the root user, log in to the SQL shell. Create additional users, specifying role options as parameters, or add the users as members of the admin role to confer all role options, if appropriate.

2. Create the certificate and key pair for each of the additional users.

   cockroach cert create-client {username} \
   --ca-key=certs/ca.key --certs-dir=certs
   

3. Securely send each user the certificate and key that matches their username: client.{username}.crt and client.{username}.key.

Was this helpful?