Manage KMS using CLI

Explore commands for managing Key Management System (KMS) integration with the WEKA system using the CLI.

Using the CLI, you can:

Configure the KMS

Command: weka security kms set

Use this command to add or update the KMS configuration. For HashiCorp Vault, you can configure a single cluster-wide encryption key or enable per-filesystem encryption keys.

Per-filesystem encryption requires using Vault's AppRole authentication method, which you configure using the --role-id and --secret-id parameters.

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

type*

Type of the KMS. Values: vault or kmip

address*

KMS server address. Values: URL for vault

hostname:port for kmip

key-identifier*

Key name for vault

UID for kmip to secure filesystem keys.

token

The API token for authenticating with a HashiCorp Vault KMS.

This parameter applies only to Vault and is used for cluster-wide encryption. It cannot be used with the role-id or secret-id parameters, which are used for AppRole authentication.

The access token must have the following permissions in Vault:

  • Read access to

    transit/keys/<master-key-name>

  • Write access to

    transit/encrypt/<master-key-name> and transit/decrypt/<master-key-name>

  • Permissions for

    /transit/rewrap and auth/token/lookup

namespace

The namespace name in HashiCorp Vault. Namespace names must not end with "/", avoid spaces, and refrain from using reserved names like root, sys, audit, auth, cubbyhole, and identity.

client-cert

Path to the client certificate PEM file. Must permit encrypt and decrypt permissions. Mandatory for kmip .

Prohibited for vault.

client-key

Path to the client key PEM file. Mandatory for kmip .

Prohibited for vault.

ca-cert

Path to the CA certificate PEM file. Optional for kmip.

Prohibited for vault.

role-id

Role ID for HashiCorp Vault's AppRole authentication method, which is provided by the Vault administrator. This parameter must be used with secret-id and cannot be used with token.

secret-id

Secret ID for HashiCorp Vault's AppRole authentication, which is provided by the Vault administrator. This parameter must be used with role-id. Alternatively, you can set this value using the

WEKA_KMS_SECRET_ID environment variable.

convert-to-cluster-key-on-fs

Convert all encrypted filesystems to use cluster key.

Obtain role-id and secret-id from HashiCorp Vault

Use this procedure when configuring HashiCorp Vault with AppRole authentication. This method is required for per-filesystem encryption and is an option for cluster-wide encryption. The Vault administrator provides the role-id and secret-id needed for access.

Recommendation: use batch tokens for per-filesystem encryption

For per-filesystem encryption, it is recommended to configure the AppRole with batch tokens to ensure optimal performance and scalability in your HashiCorp Vault environment.

Unlike standard service tokens, which generate a new lease for each authentication request, batch tokens are designed for high-volume, automated workflows. They do not create new leases upon use, which is critical for maintaining efficiency in environments with many filesystems.

While batch tokens can be used multiple times, their lifetime is limited by a Time-to-Live (TTL). It is recommended to set a short TTL (for example, 20 minutes) to align with security best practices.

Batch tokens are not single-use but are limited by their TTL, and they do not create new leases upon use, which prevents this scalability problem. To implement this, create your AppRole with the token_type set to batch.

For more information, refer to the official HashiCorp Vault documentation.

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:

$ vault auth enable approle

Role for cluster:

$ vault write -f auth/approle/role/weka-role-cluster
Success! Data written to: auth/approle/role/weka-role-cluster

$ vault write -f auth/approle/role/weka-role-cluster token_policies="weka_cluster_role_key_policy"
Success! Data written to: auth/approle/role/weka-role-cluster

Retrieve the role-id:

$ vault read auth/approle/role/weka-role-cluster/role-id

Role for Key1:

$ vault write -f auth/approle/role/weka-role-1
Success! Data written to: auth/approle/role/weka-role-1

$ vault write -f auth/approle/role/weka-role-1 token_policies="weka_fs_role_key1_policy"
Success! Data written to: auth/approle/role/weka-role-1

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

$ vault read auth/approle/role/weka-role-1/role-id
Key        Value
---        -----
role_id    5a574437-72b8-17b0-dbce-f36731d77663

$ vault write -f auth/approle/role/weka-role-1/secret-id
Key                   Value
---                   -----
secret_id             69c26538-27cb-bcce-1ac2-27d4de590d5b
secret_id_accessor    a3b885ff-ba25-560d-cc56-58df99962b2d
secret_id_num_uses    0
secret_id_ttl         0s

Examples

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

weka security kms set vault https://vault-dns:8200 weka_cluster_key --token s.nRucA9Gtb3yNVmLUK221234

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

weka security kms set  vault  https://vault-dns:8200 weka_cluster_key --role-id 26e2576f-cb9d-b48a-057d-e37d8956b00c --secret-id 44797329-e729-6j80-m9d4-b1825037cha6

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

weka security kms set kmip amer.smartkey.io:5996 b2f81634-c0f6-4y63-b5b3-84a82e231634 --client-cert smartkey_cert.pem --client-key smartkey_key.pem

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

Name
Value

new-key-uid*

Unique identifier for the new key to be used to wrap filesystem keys. Mandatory for kmip only. Do not specify any value for vault.

all

Rewrap all the filesystem encryption keys. Applicable when using HashiCorp Vault for per-filesystem encryption keys. Without the --all option, the command re-encrypts only the keys of filesystems that use the cluster key for encryption.

convert-to-cluster-key-on-fs

Convert all encrypted filesystems to use the KMS cluster key.

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

The WEKA 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 with this command:

vault secrets enable transit

The expected output is:

Success! Enabled the transit secrets engine at: transit/

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 with this command:

vault write -f transit/keys/weka-key

The expected output is:

Success! Data written to: transit/keys/weka-key

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

Related information:

Vault transit secret-engine documentation

Create a policy for master key permissions

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

path "transit/+/weka-key" {
  capabilities = ["read", "create", "update"]
}
path "transit/keys/weka-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 weka weka_policy.hcl

Obtain an API token from the vault

Authentication from the WEKA system to Vault relies on an API token. Since the WEKA 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

The expected output is:

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 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:

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

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:

vault token create -role=weka

The expected output is:

vault token create -role=weka

Key                  Value
---                  -----
token                s.nRucA9Gtb3yNVmLUK221234
token_accessor       4Nm9BvIVS4HWCgLATc3r1234
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.

The WEKA 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.

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:

openssl req -x509 -newkey rsa:4096 -keyout client-key.pem -out client-cert.pem -days 365 -nodes -subj '/CN=f283c99b-f173-4371-babc-572961161234'

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.

PreviousManage KMS using GUINextManage TLS certificates

Last updated