From df2c34bce41be470e172fc8d25a0e6f1f4f5735d Mon Sep 17 00:00:00 2001 From: lizayugabyte <77016159+lizayugabyte@users.noreply.github.com> Date: Tue, 12 Jul 2022 16:30:37 -0400 Subject: [PATCH 1/2] Modified content --- .../preview/secure/encryption-at-rest.md | 167 ++++++++---------- .../preview/secure/security-checklist.md | 14 +- 2 files changed, 83 insertions(+), 98 deletions(-) diff --git a/docs/content/preview/secure/encryption-at-rest.md b/docs/content/preview/secure/encryption-at-rest.md index 670dd94dc1be..b41320195fda 100644 --- a/docs/content/preview/secure/encryption-at-rest.md +++ b/docs/content/preview/secure/encryption-at-rest.md @@ -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 @@ -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). -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 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 \ - /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 `` 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 / + ``` -### 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 . +3. Enable cluster-wide encryption. Before rotating the key, ensure that the masters know about ``: -```sh -yb-admin -master_addresses $MASTER_ADDRESSES all_masters_have_universe_key_in_memory -``` + ```sh + yb-admin -master_addresses $MASTER_ADDRESSES all_masters_have_universe_key_in_memory + ``` -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 -``` + ```sh + yb-admin -master_addresses $MASTER_ADDRESSES rotate_universe_key_in_memory + ``` -{{< 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 -``` + ```output + Encryption status: ENABLED with 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 + /path_to_universe_key_2 + ``` -```sh -$ yb-admin -master_addresses $MASTER_ADDRESSES add_universe_keys_to_all_masters - /path/to/universe_key_2 -``` + `` must be different from any previous keys. -{{< note title="Note" >}} -Make sure the 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 + ``` -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 -``` +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 + ``` -### 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 -``` - -`` should be different from the previous ``. + `` must be different from the previous ``. ## 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 + ``` diff --git a/docs/content/preview/secure/security-checklist.md b/docs/content/preview/secure/security-checklist.md index 432d33e17590..2d517485225d 100644 --- a/docs/content/preview/secure/security-checklist.md +++ b/docs/content/preview/secure/security-checklist.md @@ -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 @@ -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/). From c3fa3dcb8055129b3b4de19104955b2efcc713a5 Mon Sep 17 00:00:00 2001 From: lizayugabyte <77016159+lizayugabyte@users.noreply.github.com> Date: Mon, 18 Jul 2022 13:51:52 -0400 Subject: [PATCH 2/2] implemented review comments --- docs/content/preview/secure/encryption-at-rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/preview/secure/encryption-at-rest.md b/docs/content/preview/secure/encryption-at-rest.md index b41320195fda..6cb99e91bf20 100644 --- a/docs/content/preview/secure/encryption-at-rest.md +++ b/docs/content/preview/secure/encryption-at-rest.md @@ -20,7 +20,7 @@ You can enable and disable encryption at rest in a YugabyteDB cluster with a sel Note that encryption can be applied at the following levels: - 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). +- At the file system level, in which case it is the responsibility of the operations teams 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). ## Enable encryption