KMS Management

This page describes the management of a Key Management System (KMS) within the WekaIO system.

Overview

When creating an encrypted filesystem, a KMS must be used to properly secure the encryption keys.

The WekaIO system uses the KMS to encrypt filesystem keys. When the WekaIO system comes up, it uses the KMS to decrypt the filesystem keys and use its in-memory capabilities for data encrypting/decrypting operations.

When a snapshot is taken using the Snap-To-Object feature, the encrypted filesystem key is saved along with the encrypted data. In the event of rehydrating this snapshot to a different filesystem (or when recovering from a disaster to the same filesystem in the WekaIO cluster), the KMS is used to decrypt the filesystem key. Consequently, the same KMS data must be present when performing such operations.

For increased security, the WekaIO system does not save any information that can reconstruct the KMS encryption keys, which is performed by the KMS configuration alone. Therefore, the following should be considered:

  1. If the KMS configuration is lost, the encrypted data may also be lost. Therefore, a proper DR strategy should be set when deploying the KMS in a production environment.

  2. The KMS should be available when the WekaIO system comes up, when a new filesystem is created, and from time to time when key rotations must be performed. Therefore, it is recommended that the KMS be highly available.

For more information, refer to KMS Best Practices.

At present, the KMS supported by the WekaIO system is HashiCorp Vault (version 1.1.5 and up). For setting up Vault to work with the WekaIO system, refer to Setting Up Vault Configuration.

For additional information on KMS support, contact the WekaIO Sales or Support Teams.

Managing KMS Using the GUI

Adding a KMS

To add a KMS to the WekaIO system, go to KMS Configuration screen on the left sidebar and click Configure KMS.

The Configure KMS dialog box will be displayed.

Configure KMS Dialog Box

Enter the URL, key name and API token, and click Update to configure the KMS.

Viewing the KMS

To view the configured KMS, go to the main KMS configuration screen.

KMS Configuration Screen

Updating the KMS Configuration

To update the KMS configuration, click Update KMS. The Configure KMS dialog box will be displayed.

Configure KMS Dialog Box

Update the URL, master key or API token, and click Update.

Removing the KMS

To remove a KMS configuration (an operation that is only possible if no encrypted filesystems exist), click the Reset KMS button on the main KMS Configuration screen. The KMS Reset dialog box will be displayed.

KMS Reset Dialog Box

Click Yes to remove the KMS configuration.

Managing KMS using the CLI

Adding/Updating a KMS

Command: weka fs kms set-vault

Use the following command line to add or update the Vault KMS configuration in the WekaIO system:

weka fs kms set-vault <base-url> <master-key-name> <token>

Parameters in Command Line

Name

Type

Value

Limitations

Mandatory

Default

base-url

String

URL for Vault KMS

Must be a valid URL

Yes

master-key-name

String

Master key name to be used for encryption-as-a-service in Vault KMS

Must be a valid key name in Vault

Yes

token

String

API token to access Vault KMS

Must have:

  • read permissions to transit/keys/<master-key-name>

  • write permissions to transit/encrypt/<master-key-name> and transit/decrypt/<masterkeyname>

  • permissions to /transit/rewrap and auth/token/lookup

Yes

Note: For the add/update command to succeed, the KMS should be preconfigured and available with the key and a valid token.

Viewing the KMS

Command: weka fs kms

Use this command to show the details of the configured KMS.

Removing the KMS

Command: weka fs kms unset

Use this command to remove the KMS from the WekaIO system. It is only possible to remove a KMS configuration if no encrypted filesystems exist.

Note: To force remove a KMS even if encrypted filesystems exist, use the --allow-downgrade attribute. In such cases, the encrypted filesystem keys are re-encrypted with local encryption and may be compromised.

Re-wrapping Filesystem Keys

Command: weka fs kms rewrap

If the KMS key is compromised or requires rotation, the KMS admin can rotate the key in the KMS. In such cases, this command is used to re-encrypt the encrypted filesystem keys with the new KMS master key.

Note: Existing filesystem keys that are part of the Snap-To-Object feature will not be automatically re-encrypted with the new KMS key.

KMS Best Practices

The KMS is the only source holding the key to decrypt WekaIO system filesystem keys. For non-disruptive operation, it is highly recommended to follow these guidelines:

  • Set-up DR for the KMS (backup/replication) to avoid any chance of data loss.

  • Ensure that the KMS is highly available (note that the KMS is represented by a single URL in the WekaIO system).

  • Provide access to the KMS from the WekaIO system backend hosts.

  • Verify the methods used by the KMS being implemented (each KMS has different methods for securing/unsealing keys and for reconstructing lost keys, e.g., Vault unsealing methods, which enable the configuration of auto unsealing using a trusted service).

  • Refer to Production Hardening for additional best practices suggested by HashiCorp when using Vault.

Note: Taking a Snap-To-Object ensures that the (encrypted) filesystems keys are backed up to the object store, which is important if total corruption of the WekaIO system configuration occurs.

Setting-Up Vault Configuration

Enabling 'Transit' Secret Engine in Vault

As described above, the WekaIO system uses encryption-as-a-service capabilities of the KMS to encrypt/decrypt the filesystem keys. This requires the configuration of Vault with the transit secret engine.

$ vault secrets enable transit
Success! Enabled the transit secrets engine at: transit/

For more information, refer to Vault transit secret-engine documentation.

Setting-Up a Master Key for the WekaIO System

Once the transit secret engine is set up, a master key for use with the WekaIO system must be created.

$ vault write -f transit/keys/wekaio-key
Success! Data written to: transit/keys/wekaio-key

Note: It is possible to either create a different key for each WekaIO cluster or to share the key between different WekaIO clusters.

For more information, refer to Vault transit secret-engine documentation.

Creating a Policy for Master Key Permissions

  • Create a wekaio_policy.hcl file with the following content:

path "transit/+/wekaio-key" {
capabilities = ["read", "create", "update"]
}
path "transit/keys/wekaio-key" {
capabilities = ["read"]
}

This limits the capabilities so there is no permission to destroy the key, using this policy. This protection is important when creating an API token.

  • Create the policy using the following command:

$ vault policy write wekaio wekaio_policy.hcl

Obtaining an API Token from Vault

Authentication from the WekaIO system to Vault relies on an API token. Since the WekaIO system must always be able to communicate with the KMS, a periodic service token must be used.

  • Verify that thetoken authentication method in Vault is enabled. This can be performed using the following command:

$ vault auth list
Path Type Description
---- ---- -----------
token/ token token based credentials
  • To enable the token authentication method use the following command:

$ vault auth enable token
  • Log into the KMS system using any of the identity methods supported by Vault. The identity should have permissions to use the previously-set master key.

  • Create a token role for the identity using the following command:

$ vault write auth/token/roles/wekaio allowed_policies="wekaio" period="768h"

Note: The period is the time set for a renewal request. If no renewal is requested during this time period, the token will be revoked and a new token must be retrieved from Vault and set in the WekaIO system.

  • Generate a token for the logged-in identity using the following command:

$ vault token create -role=wekaio
Key Value
--- -----
token s.nRucA9Gtb3yNVmLUK22yzVKA
token_accessor 4Nm9BvIVS4HWCgLATc3rIoiW
token_duration 768h
token_renewable true
token_policies ["default"]
identity_policies []
policies ["default"]

For more information on obtaining an API token, refer to Vault Tokens documentation.

Note: The WekaIO system does not automatically renew the API token lease. It can be renewed using the Vault CLI/API. It is also possible to define a higher maximum token value (max_lease_ttl)by changing the Vault Configuration file.