Install a FIPS-ready CockroachDB Runtime

On this page

Overview of FIPS-ready CockroachDB

Federal Information Processing Standards (FIPS) 140-2 is a mandatory standard that is used to approve cryptographic models. The goal of FIPS 140-2 is to provide measurable security guidelines for handling and accessing sensitive but unclassified (SBU) information. The FIPS 140-2 standard is applicable to all federal agencies that use cryptographic-based security systems to protect sensitive information in computer and telecommunication systems (including voice systems) as defined in Section 5131 of the Information Technology Management Reform Act of 1996, Public Law 104-106; and the Federal Information Security Management Act of 2002, Public Law 107-347. U.S. and Canadian governments, as well as organizations working with them, may be subject to FIPS 140-2 requirements.

The Cryptographic Module Validation Program (CMVP) validates cryptographic modules to FIPS 140-2 and other cryptography-based standards. When a cryptographic module or library has a FIPS 140-2 certificate, it has been tested and formally validated under the CMVP as meeting the requirements for FIPS 140-2.

FIPS-ready CockroachDB binaries and Docker images are available for CockroachDB v23.1.0 and later. FIPS-ready CockroachDB runtimes run only on Intel 64-bit Linux systems.

FIPS-ready CockroachDB binaries are built using Red Hat's Go FIPS with OpenSSL toolchain, which contains the necessary modifications for the Go crypto library to use an external cryptographic library in a manner compatible with FIPS 140-2. FIPS-ready CockroachDB delegates cryptographic operations to the host operating system's OpenSSL libraries and commands, rather than Go's cryptographic libraries. When the installed OpenSSL has a FIPS 140-2 certificate and FIPS mode is enabled in the Linux kernel, the CockroachDB runtime is suitable for workloads that are subject to FIPS 140-2 requirements.

For details about cryptographic algorithms and key lengths used by CockroachDB. refer to Details About Cryptographic Algorithms.

FIPS-ready features

When you use a FIPS-ready CockroachDB runtime and each cluster node's OpenSSL is FIPS-validated and configured correctly, Cockroach Labs has verified that cryptographic operations in the following contexts meet the requirements of FIPS 140-2:

• Encryption At Rest
• Encrypted Backups
• Change Data Capture to Kafka over TLS
• Certificate-based Node-to-Node and Client-to-Node Authentication
• SASL SCRAM-SHA-256 Password Authentication
• SQL Cryptographic Built-in Functions

This page shows how to configure a FIPS-ready CockroachDB self-hosted runtime using Red Hat's FIPS-validated OpenSSL package. The FIPS-ready Docker image for CockroachDB comes with Red Hat's OpenSSL libraries pre-installed and configured.

Performance considerations

When comparing performance of the same workload in a FIPS-ready CockroachDB runtime to a standard CockroachDB runtime, some performance degradation is expected, due to the use of the system's installed FIPS-validated OpenSSL libraries. The amount of performance impact depends upon the workload, cluster configuration, query load, and other factors.

Upgrading to a FIPS-ready CockroachDB runtime

Upgrading an existing CockroachDB cluster's binaries in-place to be FIPS-ready is not supported.

Enable FIPS mode in the Linux kernel

The following section provides several ways to help ensure that the FIPS object module is loaded in your system's kernel and is used by your system's OpenSSL libraries. The FIPS object module helps to prevent the use of weak cryptographic algorithms and functions which are incompatible with FIPS 140-2.

The FIPS-ready CockroachDB Docker images are based on Red Hat's Universal Base Image 8 Docker image, which comes with FIPS-validated OpenSSL libraries pre-installed with settings to comply with FIPS 140-2. To use the FIPS-ready CockroachDB Docker image, skip directly to that section of this page.

A system must have FIPS mode enabled in the kernel before it can run the FIPS-ready CockroachDB binary or the FIPS-ready CockroachDB Docker image. Enabling FIPS mode loads the FIPS kernel module so that the kernel itself enforces compliance with FIPS 140-2. To enable FIPS mode on Red Hat Enterprise Linux or its derivatives, refer to Enable FIPS mode in Red Hat's documentation. To verify that FIPS mode is enabled, refer to Verify that the kernel enforces FIPS mode.

Extend Red Hat's Universal Base Image 8 Docker image

If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on Red Hat's Universal Base Image 8 Docker image:

• You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB.
• Your Dockerfile must install OpenSSL before it starts the cockroach binary.
• You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to Enable FIPS mode in Red Hat's documentation. To verify that FIPS mode is enabled, refer to Verify that the kernel enforces FIPS mode.

Install on Red Hat Enterprise Linux

When you install Red Hat Enterprise Linux (RHEL) on a host, or after installation has completed, you can enable FIPS mode. Red Hat recommends installing RHEL with FIPS mode enabled, as opposed to enabling FIPS mode later, to help ensure that the system generates all keys with FIPS-approved algorithms and continuous monitoring tests in place.

Once FIPS mode is enabled, install OpenSSL so that the FIPS-validated OpenSSL libraries are installed.

To install OpenSSL on RHEL:

microdnf -y install openssl crypto-policies-scripts
fips-mode-setup --enable

Next, verify that the kernel enforces FIPS mode.

Verify that the kernel enforces FIPS mode

If FIPS mode is not enabled in the Linux kernel, or if OpenSSL is not configured correctly, the Linux kernel does not enforce FIPS 140-2 by default even if the FIPS module is present. Take these steps to verify that the Linux kernel is enforcing FIPS 140-2:

1. You can list the FIPS-validated ciphers using the openssl ciphers command. If FIPS mode is disabled, a no cipher match error occurs.

   openssl ciphers FIPS -v
   

2. When FIPS mode is enabled, the sysctl variable fips_enabled is set to 1:

   sysctl crypto.fips_enabled
   

   1
   

   Note:

   The preceding command does not work from within a Docker container. A Docker container runs with FIPS mode enabled if the Docker host has FIPS mode enabled. Run this command from the Docker host rather than from the Docker container.

3. The MD5 hashing algorithm is not compatible with FIPS 140-2. If the following command fails, FIPS mode is enabled:

   echo "test" | openssl md5
   

After verifying that the kernel enforces FIPS mode, you can download and install the FIPS-ready CockroachDB binary. If the tests indicate that FIPS mode is not enforced, refer to your operating system's documentation about enabling FIPS mode to resolve the issue before continuing.

Download FIPS-ready runtimes

To download FIPS-ready CockroachDB runtimes, use the following links.

Production releases

Testing releases

Install the FIPS-ready CockroachDB runtime

After you download a FIPS-ready CockroachDB binary, install it in the same way as the standard binary. Refer to Install CockroachDB on Linux.

Verify that CockroachDB is FIPS-ready

If the CockroachDB binary is FIPS-ready, the string fips is appended to the Go version in the cockroach version command:

cockroach version |grep fips

go1.19.5fips

This indicates that CockroachDB was built using Red Hat's Go FIPS with OpenSSL toolchain.

Use the FIPS-ready CockroachDB Docker image

1. If necessary, enable FIPS mode on the Docker host. The FIPS-ready CockroachDB Docker image must run on a Docker host with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to Enable FIPS mode in Red Hat's documentation. To verify that FIPS mode is enabled, refer to Verify that the kernel enforces FIPS mode.
2. Go to Download FIPS-ready Runtimes and copy the name of a FIPS-ready Docker image tag.

3. Pull the Docker image locally, create a new container that uses it, run the container, and attach to it. The following example gives the running container the name cockroachdb-fips-container. Replace {image_tag} with the name of the Docker image tag you copied.

   docker run {image_tag} --name="cockroachdb-fips-container" -i
   

4. In the Docker host, verify that the kernel enforces FIPS mode.

   Note:

   Do not attempt to run the sysctl test from within the running container. Run the command from the Docker host rather than from the Docker container.

5. In the running container, verify that CockroachDB is FIPS-ready.

6. To stop the container, use CTRL-C. To detach from the container but keep it running in the background, use the sequence CTRL+P+CTRL+Q.

Details about cryptographic algorithms

This section provides more information about the cryptographic algorithms and key lengths used by FIPS-ready CockroachDB.

Authentication

Inter-node and node identity

Algorithm: TLS 1.3 (RFC 8446).

Refer to Using Digital Certificates with CockroachDB.

Client identity

Password authentication

Algorithm: bcrypt or scram-sha-256.

Refer to SASL/SCRAM-SHA-256 Secure Password-based Authentication.

Client certificates

Algorithm: TLS 1.3 (RFC 8446).

Refer to Using Digital Certificates with CockroachDB.

GSSAPI / Kerberos

Not supported for FIPS-ready deployments.

SASL / SCRAM password authentication

Algorithm: scram-sha-256.

Refer to SASL/SCRAM-SHA-256 Secure Password-based Authentication.

JSON Web Tokens (JWTs)

Algorithms: Specified by the server.jwt_authentication.jwks cluster setting.

Refer to Cluster Single Sign-on (SSO) using a JSON web token (JWT).

DB Console Authentication via OIDC

Algorithm: Specified by the identity provider (IdP) as part of the OIDC handshake process.

Refer to Single Sign-on (SSO) for DB Console.

HTTP API access via login tokens

Algorithm: sha256 (RFC 6234).

Encryption

In flight

Algorithm: TLS 1.3 (RFC 8446).

Key sizes: Depends upon the cipher suite in use:

• TLS 1.2:

  • tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • If the COCKROACH_TLS_ENABLE_OLD_CIPHER_SUITES environment variable is set:
  • tls.TLS_RSA_WITH_AES_128_GCM_SHA256
  • tls.TLS_RSA_WITH_AES_256_GCM_SHA384

• TLS 1.3:

  • TLS_AES_128_GCM_SHA256
  • TLS_AES_256_GCM_SHA384

At rest

Customer-managed backups

AWS

Default encryption provided by the AWS Encryption SDK.

GCP

Default encryption provided by Google Cloud.

Data Encryption at Rest (EAR)

Algorithm: Advanced Encryption Standard (AES) encryption, in counter (CTR) mode.

Key sizes: The store key is specified by the user, and can be of length 16, 24, or 32 bytes (corresponding to AES-128, AES-192, or AES-256). Data keys are the same length as the store key.

See also

• Install CockroachDB
• Releases

Was this helpful?