Create Security Certificates

On this page

A secure CockroachDB cluster uses TLS for encrypted inter-node and client-node communication and requires CA, node, and client certificates and keys. To create these certificates and keys, use the cockroach cert command with the appropriate subcommands and flags.

When using cockroach cert to create node and client certificates, you will need access to a local copy of the CA certificate and key. It is therefore recommended to create all certificates and keys in one place and then distribute node and client certificates and keys appropriately. For the CA key, be sure to store it somewhere safe and keep a backup; if you lose it, you will not be able to add new nodes or clients to your cluster. For a walkthrough of this process, see Manual Deployment.

Subcommands

Certificate Directory

The create-* subcommands generate the CA certificate and all node and client certificates and keys in a single directory specified by the --certs-dir flag, with the files named as follows:

Note the following:

• The CA key is never loaded automatically by cockroach commands, so it should be created in a separate directory, identified by the --ca-key flag.

• Keys (files ending in .key) must not have group or world permissions (maximum permissions are 0700, or rwx------). This check can be disabled by setting the environment variable COCKROACH_SKIP_KEY_PERMISSION_CHECK=true.

Synopsis

# Create the CA certificate and key:
$ cockroach cert create-ca \
 --certs-dir=[path-to-certs-directory] \
 --ca-key=[path-to-ca-key]

# Create a node certificate and key, specifying all addresses at which the node can be reached:
$ cockroach cert create-node \
 [node-hostname] \
 [node-other-hostname] \
 [node-yet-another-hostname] \
 --certs-dir=[path-to-certs-directory] \
 --ca-key=[path-to-ca-key]

# Create a client certificate and key:
$ cockroach cert create-client \
 [username] \
 --certs-dir=[path-to-certs-directory] \
 --ca-key=[path-to-ca-key]

# List certificates and keys:
$ cockroach cert list \
 --certs-dir=[path-to-certs-directory]

# View help:
$ cockroach cert --help
$ cockroach cert create-ca --help
$ cockroach cert create-node --help
$ cockroach cert create-client --help
$ cockroach cert list --help

Flags

The cert command and subcommands support the following general-use and logging flags.

General

Logging

By default, the cert command logs errors to stderr.

If you need to troubleshoot this command's behavior, you can change its logging behavior.

Examples

Create the CA certificate and key pair

1. Create two directories:

   $ mkdir certs
   

   $ mkdir my-safe-directory
   

   • certs: You'll generate your CA certificate and all node and client certificates and keys in this directory and then upload some of the files to your nodes.
   • my-safe-directory: You'll generate your CA key in this directory and then reference the key when generating node and client certificates. After that, you'll keep the key safe and secret; you will not upload it to your nodes.

2. Generate the CA certificate and key:

   $ cockroach cert create-ca \
   --certs-dir=certs \
   --ca-key=my-safe-directory/ca.key
   

   $ ls -l certs
   

   total 8
   -rw-r--r--  1 maxroach  maxroach  1.1K Jul 10 14:12 ca.crt
   

Create the certificate and key pairs for nodes

1. Generate the certificate and key for the first node:

   $ cockroach cert create-node \
   node1.example.com \
   node1.another-example.com \
   --certs-dir=certs \
   --ca-key=my-safe-directory/ca.key
   

   $ ls -l certs
   

   total 24
   -rw-r--r--  1 maxroach  maxroach  1.1K Jul 10 14:12 ca.crt
   -rw-r--r--  1 maxroach  maxroach  1.2K Jul 10 14:16 node.crt
   -rw-------  1 maxroach  maxroach  1.6K Jul 10 14:16 node.key
   

2. Upload certificates to the first node:

   # Create the certs directory:
   $ ssh <username>@<node1 address> "mkdir certs"
   

   # Upload the CA certificate and node certificate and key:
   $ scp certs/ca.crt \
   certs/node.crt \
   certs/node.key \
   <username>@<node1 address>:~/certs
   

3. Delete the local copy of the first node's certificate and key:

   $ rm certs/node.crt certs/node.key
   

   Note:

   This is necessary because the certificates and keys for additional nodes will also be named node.crt and node.key As an alternative to deleting these files, you can run the next cockroach cert create-node commands with the --overwrite flag.

4. Create the certificate and key for the second node:

   $ cockroach cert create-node \
   node2.example.com \
   node2.another-example.com \
   --certs-dir=certs \
   --ca-key=my-safe-directory/ca.key
   

   $ ls -l certs
   

   total 24
   -rw-r--r--  1 maxroach  maxroach  1.1K Jul 10 14:12 ca.crt
   -rw-r--r--  1 maxroach  maxroach  1.2K Jul 10 14:17 node.crt
   -rw-------  1 maxroach  maxroach  1.6K Jul 10 14:17 node.key
   

5. Upload certificates to the second node:

   # Create the certs directory:
   $ ssh <username>@<node2 address> "mkdir certs"
   

   # Upload the CA certificate and node certificate and key:
   $ scp certs/ca.crt \
   certs/node.crt \
   certs/node.key \
   <username>@<node2 address>:~/certs
   

6. Repeat steps 3 - 5 for each additional node.

Create the certificate and key pair for a client

$ cockroach cert create-client \
maxroach \
--certs-dir=certs \
--ca-key=my-safe-directory/ca.key

$ ls -l certs

total 40
-rw-r--r--  1 maxroach  maxroach  1.1K Jul 10 14:12 ca.crt
-rw-r--r--  1 maxroach  maxroach  1.1K Jul 10 14:13 client.maxroach.crt
-rw-------  1 maxroach  maxroach  1.6K Jul 10 14:13 client.maxroach.key
-rw-r--r--  1 maxroach  maxroach  1.2K Jul 10 14:17 node.crt
-rw-------  1 maxroach  maxroach  1.6K Jul 10 14:17 node.key

List certificates and keys

$ cockroach cert list \
--certs-dir=certs

Certificate directory: certs
+-----------------------+---------------------+---------------------+------------+--------------------------------------------------------+-------+
|         Usage         |  Certificate File   |      Key File       |  Expires   |                         Notes                          | Error |
+-----------------------+---------------------+---------------------+------------+--------------------------------------------------------+-------+
| Certificate Authority | ca.crt              |                     | 2027/07/18 | num certs: 1                                           |       |
| Node                  | node.crt            | node.key            | 2022/07/14 | addresses: node2.example.com,node2.another-example.com |       |
| Client                | client.maxroach.crt | client.maxroach.key | 2022/07/14 | user: maxroach                                         |       |
+-----------------------+---------------------+---------------------+------------+--------------------------------------------------------+-------+
(3 rows)

See Also

• Manual Deployment: Walkthrough starting a multi-node secure cluster and accessing it from a client.
• Start a Node: Learn more about the flags you pass when adding a node to a secure cluster.
• Other Cockroach Commands

Was this helpful?