> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Encryption for CockroachDB Self-Hosted

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

This page outlines several procedures necessary for managing encryption in CockroachDB CockroachDB clusters.

## Generating store key files

Cockroach determines which encryption algorithm to use based on the size of the key file. The key file must contain random data making up the key ID (32 bytes) and the actual key (16, 24, or 32 bytes depending on the encryption algorithm).

| Algorithm | Key size            | Key file size |
| --------- | ------------------- | ------------- |
| AES-128   | 128 bits (16 bytes) | 48 bytes      |
| AES-192   | 192 bits (24 bytes) | 56 bytes      |
| AES-256   | 256 bits (32 bytes) | 64 bytes      |

Generating a key file can be done using the `cockroach` CLI:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach gen encryption-key -s 128 /path/to/my/aes-128.key
```

Or the equivalent [openssl](https://www.openssl.org/docs/man1.1.1/man1/openssl.html) CLI command:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ openssl rand -out /path/to/my/aes-128.key 48
```

## Starting a node with encryption

Encryption at Rest is configured at node start time using the `--enterprise-encryption` command line flag. The flag specifies the encryption options for one of the stores on the node. If multiple stores exist, the flag must be specified for each store.

The flag takes the form: `--enterprise-encryption=path=<store path,key=<key file,old-key=<old key file,rotation-period=<period`.

The allowed components in the flag are:

| Component         | Requirement | Description                                                                |
| ----------------- | ----------- | -------------------------------------------------------------------------- |
| `path`            | Required    | Path of the store to apply encryption to.                                  |
| `key`             | Required    | Path to the key file to encrypt data with, or `plain` for plaintext.       |
| `old-key`         | Required    | Path to the key file the data is encrypted with, or `plain` for plaintext. |
| `rotation-period` | Optional    | How often data keys should be automatically rotated. Default: one week.    |

The `key` and `old-key` components must **always** be specified. They allow for transitions between encryption algorithms, and between plaintext and encrypted.

Starting a node for the first time using AES-128 encryption can be done using:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach start --store=cockroach-data --enterprise-encryption=path=cockroach-data,key=/path/to/my/aes-128.key,old-key=plain
```

<Danger>
  Once specified for a given store, the `--enterprise-encryption` flag must always be present.
</Danger>

## Checking encryption status

Encryption status can be seen on the node's stores report, reachable through: `http(s)://nodeaddress:8080/#/reports/stores/local` (or replace `local` with the node ID). For example, if you are running a <InternalLink path="secure-a-cluster">local cluster</InternalLink>, you can see the node's stores report at `https://localhost:8080/#/reports/stores/local`.

The report shows encryption status for all stores on the selected node, including:

* Encryption algorithm.
* Active store key information.
* Active data key information.
* The fraction of files/bytes encrypted using the active data key.

CockroachDB relies on <InternalLink path="architecture/storage-layer#compaction">storage layer compactions</InternalLink> to write new files using the latest encryption key. It may take several days for all files to be replaced. Some files are only rewritten at startup, and some keep older copies around, requiring multiple restarts. You can force storage compaction with the `cockroach debug compact` command (the node must first be <InternalLink path="node-shutdown#perform-node-shutdown">stopped</InternalLink>).

The fraction of files/bytes encrypted on the store may be less than 100% for the following reasons:

* The percentage shown is the percentage encrypted with the **current** data key, which rotates at the configured [`rotation-period`](#starting-a-node-with-encryption). When a data key rotates, the percentage will drop down to zero and slowly climb up as data is compacted.
* In some cases, it may never reach 100%. This can happen because from the point in time at which encryption is enabled, CockroachDB only encrypts **new** data written to the filesystem. Because it relies entirely on storage layer compactions, there's no mechanism by which dormant on-disk data is encrypted.

Information about keys is written to <InternalLink path="logging-overview">the logs</InternalLink>, including:

* Active/old key information at startup.
* New key information after data key rotation.

Alternatively, you can use the <InternalLink path="cockroach-debug-encryption-active-key">`cockroach debug encryption-active-key`</InternalLink> command to view information about a store's encryption algorithm and store key.

## Changing encryption algorithm or keys

Encryption type and keys can be changed at any time by restarting the node. To change keys or encryption type, the `key` component of the `--enterprise-encryption` flag is set to the new key, while the key previously used must be specified in the `old-key` component.

For example, we can switch from AES-128 to AES-256 using:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach start --store=cockroach-data --enterprise-encryption=path=cockroach-data,key=/path/to/my/aes-256.key,old-key=/path/to/my/aes-128.key
```

Upon starting, the node will read the existing data keys using the old encryption key (`aes-128.key`), then rewrite the data keys using the new key (`aes-256.key`). A new data key will be generated to match the desired AES-256 algorithm.

To check that the new key is active, use the stores report page in the DB Console to [check the encryption status](#checking-encryption-status).

To disable encryption, specify `key=plain`. The data keys will be stored in plaintext and new data will not be encrypted.

To rotate keys, specify `key=/path/to/my/new-aes-128.key` and `old-key=/path/to/my/old-aes-128.key`. The data keys will be decrypted using the old key and then encrypted using the new key. A new data key will also be generated.