Manage KMS using the CLI

Using the CLI, you can:

Configure the KMS

Command: weka security kms set

To integrate the Key Management Service (KMS) with the WEKA system, use the provided command line for adding or updating the KMS configuration. Ensure that the KMS is preconfigured, and both the key and a valid token are readily available.

Run the following command to establish a connection between the WEKA system and the configured Vault KMS.

weka security kms set <type> <address> <key-identifier> [--token token] [--namespace namespace] [--client-cert client-cert] [--client-key client-key] [--ca-cert ca-cert] [--role-id role-id] [--secret-id secret-id] [--convert-to-cluster-key-on-fs]

Parameters

Name

Value

Considerations

Obtain role-id and secret-id from HashiCorp Vault

In environments using HashiCorp Vault for secure credential management, the Vault administrator would provide the role-id and secret-id needed for access.

Disclaimer: The following example is provided as a courtesy to illustrate possible integration with HashiCorp Vault and is not part of our product.

Set up roles for cluster access

Enable AppRole authentication

Role for cluster

Retrieve the role-id:

Role for Key1

Retrieve the role-id and generate a secret-id:

Examples:

Setting the WEKA system with a HashiCorp Vault KMS for cluster-wide encryption:

Setting the WEKA system with a HashiCorp Vault KMS for per-filesystem encryption:

Setting the WEKA system with a KMIP complaint KMS (SmartKey example):

View the KMS configuration

Command: weka security kms

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

Remove the KMS configuration

Command: weka security kms unset

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

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.

Rewrap filesystem keys

Command: weka security kms rewrap

If the KMS key is compromised or requires rotation, the KMS administrator 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 cluster key.

weka security kms rewrap [--new-key-uid new-key-uid] [--all] [--convert-to-cluster-key-on-fs]

Parameters

WEKA does not automatically re-encrypt existing filesystem keys with the new KMS key for snapshots that were previously uploaded with the old encrypted keys.

Unlike HashiCorp Vault KMS, re-wrapping a KMIP-based KMS necessitates generating a new key within the KMS rather than rotating the existing one. Therefore, it is essential to retain the old key in the KMS to ensure the decryption of older Snap-to-Object snapshots.

Set up vault configuration

Enable 'Transit' secret engine in vault

Set up a master key for the WEKA system

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

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

Related information:

Create a policy for master key permissions

Create a weka_policy.hcl file with the following content:

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:

Obtain an API token from the vault

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

To enable the token authentication method use the following command:

Log into the KMS system using any of the identity methods Vault supports. The identity must have permission to use the previously set master key.
Create a token role for the identity using the following command:

The period is the designated timeframe for a renewal request. If a renewal is not requested within this period, the token is revoked, necessitating the retrieval of a new token from the Vault and its configuration in the WEKA system.

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

Obtain a certificate for a KMIP-based KMS

Each KMS employs a unique process for obtaining a client certificate and key and configuring it through the KMS. The certificate is generated using OpenSSL and utilizes a UID obtained from the KMS.

Example:

Refer to the specific KMS documentation to create a certificate and associate it with the WEKA cluster within the KMS, ensuring it has the necessary privileges for encryption and decryption.