From d314f5c0db015c4007de016a69bd9e8b21893e64 Mon Sep 17 00:00:00 2001 From: "Michael G. Khmelnitsky, Ph.D" Date: Wed, 27 Sep 2023 11:34:56 -0700 Subject: [PATCH] [6.2.2][DOCS-1736] Staging Branch (#267) --- .github/workflows/pages.yml | 3 +- .../managing-encryption-at-rest.md | 155 ++++++++++++++++-- .../upgrading-qumulo-core/feature-log.md | 7 + .../upgrading-qumulo-core/mode-reference.md | 4 + docker/build/replace-tags.py | 0 docker/build/run.sh | 23 ++- 6 files changed, 165 insertions(+), 27 deletions(-) mode change 100644 => 100755 docker/build/replace-tags.py diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index a4ad5bdd..06e406ff 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -43,7 +43,8 @@ jobs: uses: actions/configure-pages@v2 - name: Build with Jekyll # Outputs to the './_site' directory by default - run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" + #run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" + run: docker/build/run.sh --baseurl "${{ steps.pages.outputs.base_path }}" env: JEKYLL_ENV: production - name: Upload artifact diff --git a/administrator-guide/encryption-data-security/managing-encryption-at-rest.md b/administrator-guide/encryption-data-security/managing-encryption-at-rest.md index 63836fc0..7a51a25f 100644 --- a/administrator-guide/encryption-data-security/managing-encryption-at-rest.md +++ b/administrator-guide/encryption-data-security/managing-encryption-at-rest.md @@ -1,49 +1,170 @@ --- title: "Managing Encryption at Rest in Qumulo Core" -summary: "This section explains how encryption at rest works in Qumulo Core, how to rotate master keys, and how to ensure that the master keys across your cluster are secured correctly." +summary: "This section explains how encryption at rest works in Qumulo Core, how to rotate master keys, how to configure a Key Management Server (KMS), and how to ensure that the master keys across your cluster are secured correctly by using the qq CLI." permalink: /administrator-guide/encryption-data-security/managing-encryption-at-rest.html redirect_from: - /administrator-guide/data-security/managing-encryption-at-rest.html - /administrator-guide/protecting-data/managing-encryption-at-rest.html + - /administrator-guide/encryption-data-security/configuring-remote-key-management-server.html sidebar: administrator_guide_sidebar -keywords: encryption, at_rest, encryption_at_rest, data_key, master_key, rotate_keys +keywords: encryption, at_rest, encryption_at_rest, data_key, master_key, rotate_keys, kms, key_management_server, key_management_system, key_management_service +varLocalKey: The following is example JSON output for a locally stored master key. +varKmsKey: The following is example JSON output for a master key stored in a KMS. +varExampleKeyID: abcd-1234-efgh-5678 +varExampleHostname: kms-server.example.com --- -## How Master Keys and Data Keys Work in Qumulo Core -In addition to encrypting data _in transit_ (for example, to clients that use SMBv.3.1), in Qumulo Core 3.1.5 (and higher) software-based encryption secures data _at rest_ for on-premises clusters. Qumulo Core encrypts all data and metadata in the file system. Removing or reinserting drives and replication doesn't affect encryption at rest. For more information, see [Encryption Limitations](#encryption-limitations). +{{site.data.alerts.important}} + +{{site.data.alerts.end}} + +## How Encryption at Rest and Master Keys Work in Qumulo Core +In Qumulo Core 3.1.5 (and higher), in addition to encrypting data _in transit_ (for example, to clients that use SMBv.3.1), software-based encryption also secures data _at rest_ for on-premises clusters. Qumulo Core encrypts all data and metadata in the file system. Removing or reinserting drives and replication doesn't affect encryption at rest. For more information, see [Encryption Limitations](#encryption-limitations). + +Qumulo Core uses a _master key_ to protect the _data key_ that encrypts the data on the cluster. The master key is stored either locally—on the boot drive of every node, in a file that only the `root` user can access—or on an external Key Management Server (KMS)—from where the system retrieves the master key upon startup. Both approaches help protect your data from potential threats such as a malicious actor's access to stolen or decommissioned disks. + + +## Retrieving Information about a Qumulo Cluster's Encryption Configuration +This section explains how to retrieve the status or detailed information about an active encryption configuration for a Qumulo cluster and gives examples for a system that uses a locally stored master key and a system that uses a Key Management Server (KMS). + +{% include note.html content="The `qq` CLI commands `encryption_get_key_store` and `encryption_get_status` require the `PRIVILEGE_ENCRYPTION_READ` privilege." %} + + +### To View the Status of an Active Encryption Configuration +Use the `qq encryption_get_status` command. + +{{page.varLocalKey}} + +```json +{ + "last_key_rotation_time": "2022-11-20T12:15:25.683207795Z", + "status": "Encrypted", + "type": "Local" +} +``` + +{{page.varKmsKey}} + +```json +{ + "ca_cert_expiry": "2027-04-18T19:55:17Z", + "client_cert_expiry": "2027-04-18T19:55:17Z", + "last_key_rotation_time": "2023-09-05T20:15:40.06864014Z", + "last_status_update_time": "2023-09-05T20:28:58.108120131Z", + "status": "KMS Available", + "type": "KMS" +} +``` + + +### To View Detailed Information for an Active Encryption Configuration +Use the `qq encryption_get_key_store` command. + +{{page.varLocalKey}} + +```json +{ + "config_details": { + "status": "Encrypted" + }, + "config_type": "Local" +} +``` + +{{page.varKmsKey}} + +```json +{ + "config_details": { + "config_creation_time": "2024-02-28T20:01:25.683207795Z", + "hostname": "{{page.varExampleHostname}}", + "key_id": "{{page.varExampleKeyID}}", + "port": 5696 + }, + "config_type": "KMS" +} +``` + -To encrypt data and data keys, Qumulo Core uses _master keys_ that it stores on the boot drive of every node in the cluster, in a file that only the `root` user can access. The _master key_ protects the _data key_ that encrypts the data on the cluster. This lets Qumulo Core protect your data from potential threats such as a malicious actors' access to stolen or decommissioned disks. +## Configuring Qumulo Core to Use a Master Key Stored Locally or in a Key Management Server (KMS) +This section explains how to configure Qumulo Core to use a master key stored locally or in a Key Management Server (KMS) by using the `qq` CLI. +{{site.data.alerts.note}} + +{{site.data.alerts.end}} + +### To Configure Qumulo Core to Use a Master Key Stored Locally {{site.data.alerts.important}} {{site.data.alerts.end}} -While encryption at rest is available by default on all clusters that you create by using Qumulo Core 3.1.5 (and higher), upgrading from a version of Qumulo Core lower than 3.1.5 doesn't provide encryption capability. You must rebuild your cluster to take advantage of this feature. When you [create a new cluster](https://care.qumulo.com/hc/en-us/articles/115014525587), Qumulo Core enables encryption at rest automatically and distributes the master key to all nodes in the cluster. +1. To configure the system to use a local key store, use the `qq encryption_set_key_store local` command. + +1. To confirm that the system is configured correctly, [use the `qq encryption_get_status` command](#encryption-get-status). + + In the output, ensure that the `type` field is set to `Local`. + +### To Configure Qumulo Core to Use a Master Key Stored in a Key Management Server (KMS) +{{site.data.alerts.caution}} + +{{site.data.alerts.end}} + +1. To configure the system to use a KMS, use `qq encryption_set_key_store kms` command and specify the path to the client certificate, private key, the server CA certificate, the key ID, and the KMS server hostname. For example: + + ``` bash + qq encryption_set_key_store kms \ + --client-cert path/to/client_cert.pem \ + --client-private-key path/to/client_pk.pem \ + --server-ca-cert /path/to/server_cert.pem \ + --key-id {{page.varExampleKeyID}} \ + --host-name {{page.varExampleHostname}} + ``` + +1. To confirm that the system is configured correctly, [use the `qq encryption_get_key_store` command](#encryption-get-key-store). + + In the output, ensure that the `type` field is set to `KMS`. -For replication, Qumulo Core maintains the encryption type after a transfer. Although source and target clusters don't require encryption for replication, we strongly recommend encrypting both source and target clusters. ## Rotating the Master Key -This section explains how to rotate the master key and check the encryption status for your cluster by using the `qq` CLI and Web UI. +This section explains how to rotate the master key and check the encryption status for your cluster by using the `qq` CLI and how to check the encryption status by using the Web UI. + +{% include caution.html content="[Qumulo Care](https://docs.qumulo.com/contacting-qumulo-care-team.html) team members can help you [rotate your master keys](#rotate-master-key). However, they don't have access to your encryption keys and can't retrieve them for you." %} -### To Rotate the Master Key by Using the qq CLI +### To Rotate Master Keys Stored Locally 1. Use the `qq rotate_encryption_keys` command. - When the command completes, it shows the following message. + When the process is complete, the command shows the `Key rotation complete` message. - ``` - Key rotation complete - ``` +1. To view your cluster's encryption status and the last key rotation time, [use the `qq encryption_get_status` command](#encryption-get-status). -1. To check your cluster's encryption status and the last key rotation time, use the `qq encryption_status` command. +### To Rotate Master Keys Stored in a Key Management Server (KMS) +1. Use the `qq rotate_encryption_keys` command and specify the key ID. For example: + + ```bash + qq rotate_encryption_keys --key-id {{page.varExampleKeyID}} + ``` + + {% include tip.html content="The key ID might be different from the key name." %} + +1. To ensure that the system is using the new key, [use the `qq encryption_get_key_store` command](#encryption-get-key-store). + In the output, ensure that the `key_id` field lists the new key ID. -### To Check Your Cluster's Encryption Status by Using the Web UI +### To Check the Encryption Status of a Qumulo Cluster by Using the Web UI 1. Log in to Qumulo Core. 1. On the **Dashboard** page, in the **Cluster Overview** section, click **More details**. @@ -57,6 +178,6 @@ This section explains how to rotate the master key and check the encryption stat * Qumulo Core doesn't support removing encryption from encrypted clusters. -* Single-stream write throughput and latency might experience up to 10-10% degradation and reads might experience up to 5% degradation. +* On encrypted systems, single-stream throughput and latency might experience up to 5-10% degradation for writes and up to 5% for reads. * Qumulo Cloud clusters don't support encryption at rest and should use cloud-native solutions for this functionality. diff --git a/administrator-guide/upgrading-qumulo-core/feature-log.md b/administrator-guide/upgrading-qumulo-core/feature-log.md index 5cdefeb2..73b7f104 100644 --- a/administrator-guide/upgrading-qumulo-core/feature-log.md +++ b/administrator-guide/upgrading-qumulo-core/feature-log.md @@ -12,6 +12,13 @@ For information about upgrade types for each release, see