Create Security Certificates

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

Certificate Directory

To create node and client certificates using the OpenSSL commands, you need access to a local copy of the CA certificate and key. We recommend creating all certificates (node, client, and CA certificates), and node and client keys in one place and then distributing them appropriately. Store the CA key somewhere safe and keep a backup; if you lose it, you will not be able to add new nodes or clients to your cluster.

Use the openssl genrsa and openssl req subcommands to create all certificates, and node and client keys in a single directory, with the files named as follows:

The CA key should not be uploaded to the nodes and clients, so it should be created in a separate directory.

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.

Examples

Create the CA key and certificate pair

Create two directories:

copy

icon/buttons/copy

$ mkdir certs

copy

icon/buttons/copy

$ mkdir my-safe-directory

certs: Create your CA certificate and all node and client certificates and keys in this directory and then upload the relevant files to the nodes and clients.

my-safe-directory: Create your CA key in this directory and then reference the key when generating node and client certificates. After that, keep the key safe and secret; do not upload it to your nodes or clients.

Create the ca.cnf file and copy the following configuration into it.

You can set the CA certificate expiration period using the default_days parameter. We recommend using the CockroachDB default value of the CA certificate expiration period, which is 3660 days.

The keyUsage and extendedkeyUsage parameters are vital for CockroachDB functions. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the keyUsage and extendedkeyUsage parameters.

The commonName and subjectAltName parameters are vital for CockroachDB functions. It is also important that commonName be set to node. You can modify or omit other parameters as per your preferred OpenSSL configuration, but do not omit the commonName and subjectAltName parameters.

Sign the client CSR to create the client certificate for the first client using the openssl ca command. You can set the client certificate expiration period using the days flag. We recommend using the CockroachDB default value of the client certificate expiration period, which is 1830 days.