CockroachDB - HashiCorp Vault Integration

This pages reviews the supported integrations between CockroachDB and HashiCorp's Vault.

Vault is an identity-based secrets and encryption management service, which can either be self-hosted or accessed as a software as a service (SaaS) product through HashiCorp Cloud Platform (HCP). Vault's tooling can complement CockroachDB's data security capabilities to significantly bolster your organizational security posture.

Cockroach Labs supports the following integrations between Vault and CockroachDB:

• Using Vault's Key Management Secrets (KMS) Engine to manage & distribute encryption keys to AWS or GCP KMS for CockroachDB Dedicated's customer-managed encryption key (CMEK) functionality.
• Public Key Infrastructure (PKI):
  • Using Vault's PKI Secrets Engine to manage a CockroachDB Dedicated cluster's certificate authority (CA) and client certificates
  • Using Vault's PKI Secrets Engine to manage a CockroachDB Self-Hosted cluster's certificate authority (CA), server, and client certificates
• Using Vault's PostgreSQL Database Secrets Engine to manage CockroachDB SQL user credentials.
• Using Vault's Transit Secrets Engine to generate the store key for Enterprise Encryption At Rest for a CockroachDB Self-Hosted cluster.

Use Vault's KMS secrets engine to manage a CockroachDB Dedicated cluster's customer-managed encryption key

CockroachDB Dedicated supports the use of customer-managed encrypted keys (CMEK) for the encryption of data at rest.

Vault's Key Management secrets engine allows customers to manage encryption keys on external key management services (KMS) such as those offered by Google Cloud Platform (GCP) or Amazon Web Services (AWS).

CockroachDB customers can integrate these services, using Vault's KMS secrets engine to handle the full lifecycle of the encryption keys that CockroachDB Dedicated uses to protect their data.

Resources:

• CMEK overview
• Manage Customer-Managed Encryption Keys (CMEK) for CockroachDB Dedicated
• Provisioning GCP KMS Keys and Service Accounts for CMEK
• Provisioning AWS KMS Keys and IAM Roles for CMEK

Use Vault's PKI Secrets Engine to manage a CockroachDB Dedicated cluster's certificate authority (CA) and client certificates.

CockroachDB Dedicated customers can use Vault's public key infrastructure (PKI) secrets engine to manage PKI certificates for client authentication to the cluster. Vault's PKI Secrets Engine greatly eases the security-critical work involved in maintaining a certificate authority (CA), generating, signing and distributing PKI certificates.

By using Vault to manage certificates, you can use only certificates with short validity durations, an important component of PKI security.

Refer to Transport Layer Security (TLS) and Public Key Infrastructure (PKI) for an overview.

Refer to Certificate Authentication for SQL Clients in CockroachDB Dedicated Clusters for procedures in involved in administering PKI for a CockroachDB Dedicated cluster.

Use Vault's PKI Secrets Engine to manage a CockroachDB Self-Hosted cluster's certificate authority (CA), server, and client certificates

CockroachDB Self-Hosted customers can use Vault's public key infrastructure (PKI) secrets engine to manage PKI certificates for internode as well as client-cluster authentication. Vault's PKI Secrets Engine greatly eases the security-critical work involved in securely maintaining a certificate authority (CA), generating, signing and distributing PKI certificates.

By using Vault to manage certificates, you can use only certificates with short validity durations, an important component of PKI security.

Refer to Transport Layer Security (TLS) and Public Key Infrastructure (PKI) for an overview.

Refer to Manage PKI certificates for a CockroachDB deployment with HashiCorp Vault for procedures in involved in administering PKI for a CockroachDB Self-Hosted cluster.

Use Vault's PostgreSQL Database Secrets Engine to manage CockroachDB SQL users and their credentials

CockroachDB users can use Vault's PostgreSQL Database Secrets Engine to handle the full lifecycle of SQL user credentials (creation, password rotation, deletion). Vault is capable of managing SQL user credentials in two ways:

• As Static Roles, meaning that a single SQL user/role is mapped to a Vault role.

• As Dynamic Secrets, meaning that credentials are generated and issued on demand from pre-configured templates, rather than created and persisted. Credentials are issued for specific clients and for short validity durations, further minimizing both the likelihood of a credential compromise, and the possible impact of any compromise that might occur.

Try the tutorial: Using HashiCorp Vault's Dynamic Secrets for Enhanced Database Credential Security in CockroachDB

How to speed up user/role management

User/role management operations (such as GRANT and REVOKE) are schema changes. As such, they inherit the limitations of schema changes.

For example, schema changes wait for concurrent transactions using the same resources as the schema changes to complete. In the case of role memberships being modified inside a transaction, most transactions need access to the set of role memberships. Using the default settings, role modifications require schema leases to expire, which can take up to 5 minutes.

This means that long-running transactions elsewhere in the system can cause user/role management operations inside transactions to take several minutes to complete. This can have a cascading effect. When a user/role management operation inside a transaction takes a long time to complete, it can in turn block all user-initiated transactions being run by your application, since the user/role management operation in the transaction has to commit before any other transactions that access role memberships (i.e., most transactions) can make progress.

If you want user/role management operations to finish more quickly, and do not care whether concurrent transactions will immediately see the side effects of those operations, set the session variable allow_role_memberships_to_change_during_transaction to true.

When this session variable is enabled, any user/role management operations issued in the current session will only need to wait for the completion of statements in other sessions where allow_role_memberships_to_change_during_transaction is not enabled.

To accelerate user/role management operations across your entire application, you have the following options:

1. Set the session variable in all sessions by passing it in the client connection string.

2. Apply the allow_role_memberships_to_change_during_transaction setting globally to an entire cluster using the ALTER ROLE ALL statement:

   ALTER ROLE ALL SET allow_role_memberships_to_change_during_transaction = true;
   

Use Vault's Transit Secrets Engine to manage a CockroachDB Self-Hosted cluster's Enterprise Encryption At Rest store key

When deploying Enterprise, customers can provide their own externally managed encryption keys for use as the store key for CockroachDB's Enterprise Encryption At Rest.

Vault's Transit Secrets Engine can be used to generate suitable encryption keys for use as your cluster's store key.

See also

• CMEK overview
• Manage Customer-Managed Encryption Keys (CMEK) for CockroachDB Dedicated
• Provisioning GCP KMS Keys and Service Accounts for CMEK
• Provisioning AWS KMS Keys and IAM Roles for CMEK
• Transport Layer Security (TLS) and Public Key Infrastructure (PKI)
• Certificate Authentication for SQL Clients in Dedicated Clusters
• Manage PKI certificates for a CockroachDB deployment with HashiCorp Vault
• Using HashiCorp Vault's Dynamic Secrets for Enhanced Database Credential Security in CockroachDB
• Roles
• Online Schema Changes
• GRANT
• REVOKE