Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[doc] PR for Why use YB encryption at rest over filesystem level encryption #13267

Merged
merged 2 commits into from
Jul 18, 2022
Merged

[doc] PR for Why use YB encryption at rest over filesystem level encryption #13267

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
df2c34b
Modified content
lizayugabyte Jul 12, 2022
c3fa3dc
implemented review comments
lizayugabyte Jul 18, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
167 changes: 77 additions & 90 deletions docs/content/preview/secure/encryption-at-rest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Enable encryption at rest in YugabyteDB clusters
headerTitle: Encryption at rest
linkTitle: Encryption at rest
description: Enable encryption at rest in a YugabyteDB cluster with a user-generated key.
headcontent: Enable encryption at rest with a user-generated key
headcontent:
image: /images/section_icons/secure/prepare-nodes.png
aliases:
- /secure/encryption-at-rest
Expand All @@ -15,133 +15,120 @@ menu:
type: docs
---

This page describes how to enable and disable encryption at rest in a YugabyteDB cluster with a user-generated key.
You can enable and disable encryption at rest in a YugabyteDB cluster with a self-generated key.

## Enabling encryption
Note that encryption can be applied at the following levels:

### Step 1. Create encryption key
- At the database layer, in which case the encryption process and its associated capabilities, such as key rotation, are cluster-wide.
- At the file system level, in which case it is the responsibility of the operations team's to manage the process manually on every node. It is important to note that the degree to which file systems or external encryption mechanisms support online operations can vary (for example, when the database processes are still running).
lizayugabyte marked this conversation as resolved.
Show resolved Hide resolved

First, you will generate the universe key data. This data can have length 32, 40, or 48. Larger keys are more secure with slightly worse performance. Run the following on your local filesystem.
## Enable encryption

```sh
$ openssl rand -out /path/to/universe_key [ 32 | 40 | 48 ]
You enable encryption as follows:

```
1. Generate the universe key data of length 32, 40, or 48 by executing the following command on your local file system:

### Step 2. Copy key to master nodes
```sh
openssl rand -out /path/to/universe_key [ 32 | 40 | 48 ]
```

In this example, assume a 3 node RF=3 cluster with `MASTER_ADDRESSES=ip1:7100,ip2:7100,ip3:7100`. Choose any string <key_id> for this key and use yb-admin to copy the key to each of the masters.
Note that larger keys are more secure with slightly worse performance.

```sh
$ yb-admin -master_addresses $MASTER_ADDRESSES add_universe_keys_to_all_masters \
<key_id> /path/to/universe_key
```
2. Copy the key to master nodes. In the following example, assume a 3-node RF=3 cluster with `MASTER_ADDRESSES=ip1:7100,ip2:7100,ip3:7100`. Choose any string `<key_id>` for this key and use yb-admin to copy the key to each of the masters:

{{< note title="Note" >}}
This operation doesn't actually perform the key rotation, but rather seeds each master's in-memory state. The key only lives in-memory, and the plaintext key will never be persisted to disk.
{{< /note >}}
```sh
yb-admin -master_addresses $MASTER_ADDRESSES add_universe_keys_to_all_masters <key_id> /<path_to_universe_key>
```

### Step 3. Enable cluster-wide encryption
The preceding operation does not perform the key rotation, but rather seeds each master's in-memory state. The key only lives in memory, and the plaintext key is never persisted to the disk.

Before rotating the key, make sure the masters know about <key_id>.
3. Enable cluster-wide encryption. Before rotating the key, ensure that the masters know about `<key_id>`:

```sh
yb-admin -master_addresses $MASTER_ADDRESSES all_masters_have_universe_key_in_memory <key_id>
```
```sh
yb-admin -master_addresses $MASTER_ADDRESSES all_masters_have_universe_key_in_memory <key_id>
```

If this fails, re-run step 2. Once this succeeds, tell the cluster to start using new universe key.
If the preceding command fails, rerun step 2. Once this succeeds, instruct the cluster to start using the new universe key, as follows:

```sh
$ yb-admin -master_addresses $MASTER_ADDRESSES rotate_universe_key_in_memory <key_id>
```
```sh
yb-admin -master_addresses $MASTER_ADDRESSES rotate_universe_key_in_memory <key_id>
```

{{< note title="Note" >}}
Because data is encrypted in the background as part of flushes to disk and compactions, only new data will be encrypted. Therefore, the call should return quickly.
{{< /note >}}
Because data is encrypted in the background as part of flushes to disk and compactions, only new data is encrypted. Therefore, the call should return quickly.

### Step 4. Verify encryption enabled
4. Verify that encryption has been enabled. To do this, check the encryption status of the cluster by executing the following yb-admin command:

To check the encryption status of the cluster, run the following yb-admin command.
```sh
yb-admin -master_addresses $MASTER_ADDRESSES is_encryption_enabled
```

```sh
$ yb-admin -master_addresses $MASTER_ADDRESSES is_encryption_enabled
```
Expect the following output:

```output
Encryption status: ENABLED with key id <key_id>
```
```output
Encryption status: ENABLED with key id <key_id>
```

## Rotating a new key
## Rotate new key

### Step 1. Creating a new key
You can rotate the new key as follows:

First, create the key to be rotated.
1. Create the key to be rotated by executing the following command:

```sh
$ openssl rand -out /path/to/universe_key_2 [ 32 | 40 | 48 ]
```
```sh
openssl rand -out /path_to_universe_key_2 [ 32 | 40 | 48 ]
```

{{< note title="Note" >}}
Make sure to use a different key path to avoid overwriting the previous key file.
{{< /note >}}
Make sure to use a different key path to avoid overwriting the previous key file.

### Step 2. Copy new key to master nodes
2. Copy the new key to master nodes, informing the master nodes about the new key, as follows:

As with enabling, tell the master nodes about the new key.
```sh
yb-admin -master_addresses $MASTER_ADDRESSES add_universe_keys_to_all_masters
<key_id_2> /path_to_universe_key_2
```

```sh
$ yb-admin -master_addresses $MASTER_ADDRESSES add_universe_keys_to_all_masters
<key_id_2> /path/to/universe_key_2
```
`<key_id>` must be different from any previous keys.

{{< note title="Note" >}}
Make sure the <key_id> is different from any previous keys.
{{< /note >}}
3. Ensure that the masters know about the key, and then perform the rotation, as follows:

### Step 3. Rotate key
```sh
yb-admin -master_addresses $MASTER_ADDRESSES rotate_universe_key_in_memory <key_id_2>
```

Do the same validation as enabling that the masters know about the key and then perform the rotation.
Since this key is only used for new data and can only eventually encrypt older data through compactions, it is best to ensure old keys remain secure.

```sh
$ yb-admin -master_addresses $MASTER_ADDRESSES rotate_universe_key_in_memory <key_id_2>
```
4. Verify the new key. To do this, check that the new key is encrypting the cluster, as follows:

{{< note title="Note" >}}
Since this key will only be used for new data and will only eventually encrypt older data through compactions, it is best to ensure old keys remain secure.
{{< /note >}}
```sh
yb-admin -master_addresses $MASTER_ADDRESSES is_encryption_enabled
```

Expect the following output:

```output
Encryption status: ENABLED with key id <key_id_2>
```

### Step 4. Verify new key

Check that the new key is encrypting the cluster.

```sh
$ yb-admin -master_addresses $MASTER_ADDRESSES is_encryption_enabled
```

```output
Encryption status: ENABLED with key id <key_id_2>
```

`<key_id_2>` should be different from the previous `<key_id>`.
`<key_id_2>` must be different from the previous `<key_id>`.

## Disable encryption

### Step 1. Disable cluster-wide encryption

Use yb-admin to disable encryption.
You can disable cluster-wide encryption as follows:

```sh
$ yb-admin -master_addresses $MASTER_ADDRESSES disable_encryption
```
1. Disable encryption by executing the following yb-admin command:

### Step 2. Verify encryption disabled
```sh
yb-admin -master_addresses $MASTER_ADDRESSES disable_encryption
```

Check that encryption is disabled.
2. Verify that the encryption has been disabled by executing the following command:

```sh
$ yb-admin -master_addresses $MASTER_ADDRESSES is_encryption_enabled
```
```sh
yb-admin -master_addresses $MASTER_ADDRESSES is_encryption_enabled
```

Expect the following output:

```output
Encryption status: DISABLED
```
```output
Encryption status: DISABLED
```
14 changes: 6 additions & 8 deletions docs/content/preview/secure/security-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,19 +13,19 @@ menu:
type: docs
---

Below are a list of security measures that can be implemented to protect your YugabyteDB installation.
There is a number of security measures that you can implement to protect your YugabyteDB installation.

## Enable authentication

Authentication requires that all clients provide valid credentials before they can connect to a YugabyteDB cluster. YugabyteDB stores authentication credentials internally in the YB-Master system tables. The authentication mechanisms available to clients depend on what is supported and exposed by the YSQL, YCQL, and YEDIS APIs.

Read more about [how to enable authentication in YugabyteDB](../authentication/).
For more information, see [Authentication in YugabyteDB](../authentication/).

## Configure role-based access control

Roles can be modified to grant users or applications only the essential privileges based on the operations they need to perform against the database. Typically, an administrator role is created first. The administrator then creates additional roles for users.

Refer to [Role-based access control](../authorization/) to enable role-based access control in YugabyteDB.
For more information, see [Role-based access control in YugabyteDB](../authorization/).

## Run as a dedicated user

Expand Down Expand Up @@ -57,12 +57,10 @@ Limit the interfaces on which YugabyteDB instances listen for incoming connectio

[TLS encryption](https://en.wikipedia.org/wiki/Transport_Layer_Security) ensures that network communication between servers is secure. You can configure YugabyteDB to use TLS to encrypt intra-cluster and client to server network communication. Yugabyte recommends enabling encryption in transit in YugabyteDB clusters and clients to ensure privacy and integrity of data transferred over the network.

Read more about enabling [Encryption in transit](../tls-encryption/) in YugabyteDB.
For more information, see [Encryption in transit in YugabyteDB](../tls-encryption/).

## Enable encryption at rest

[Encryption at rest](https://en.wikipedia.org/wiki/Data_at_rest#Encryption) ensures that data
at rest, stored on disk, is protected. You can configure YugabyteDB with a user generated symmetric key to
perform cluster-wide encryption.
[Encryption at rest](https://en.wikipedia.org/wiki/Data_at_rest#Encryption) ensures that data at rest, stored on disk, is protected. You can configure YugabyteDB with a self-generated symmetric key to perform cluster-wide encryption.

Read more about enabling [Encryption at rest](../encryption-at-rest/) in YugabyteDB.
For more information, see [Encryption at rest in YugabyteDB](../encryption-at-rest/).