Manage KMS using the CLI

This page describes how to manage the Key Management System (KMS) using the CLI.

Using the CLI, you can:

• Add or update the KMS

• View the KMS

• Remove the KMS

• Set up vault configuration

• Obtain a certificate for a KMIP-based KMS

Add or update the KMS

Command: weka security kms set

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

weka security kms set <type> <address> <key-identifier> [--token token] [--client-cert client-cert] [--client-key client-key] [--ca-cert ca-cert]

Parameters

Name	Type	Value	Limitations	Mandatory	Default
type	String	Type of the KMS	Either vault or kmip	Yes
address	String	KMS server address	URL for Vault, hostname:port for KMIP	Yes
key-identifier	String	Key to be used for encryption-as-a-service in the KMS	Key name (for Vault) or a key UID (for KMIP)	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	Must be supplied for vault and must not be supplied for kmip
client-cert	String	Path to the client certificate PEM file	Must permit encrypt and decrypt permissions	Must be supplied for kmip and must not be supplied for vault
client-key	String	Path to the client key PEM file		Must be supplied for kmip and must not be supplied for vault
ca-cert	String	Path to the CA certificate PEM file		Optional for kmip and must not be supplied for vault

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

Example:

Setting the Weka system with a Vault KMS:

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

Setting the Weka system with a KMIP complaint KMS (e.g., SmartKey):

weka security kms set kmip amer.smartkey.io:5696 b2f81234-c0f6-4d63-b5b3-84a82e231234 --client-cert smartkey_cert.pem --client-key smartkey_key.pem

View the KMS

Command: weka security kms

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

Remove the KMS

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.

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-wrap filesystem keys

Command: weka security 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.

weka security kms rewrap [--new-key-uid new-key-uid]

Parameters

Name	Type	Value	Limitations	Mandatory	Default
new-key-uid	String	Unique identifier for the new key to be used to wrap filesystem keys		Must be supplied for kmip and must not be supplied for vault

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

Note: Unlike in Vault KMS, re-wrapping a KMIP-based KMS requires generating a new key in the KMS, rather than rotating the same key. Hence, the old key should be preserved in the KMS in order to be able to decrypt old Snap2Obj 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.

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

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

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.

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

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

For more information, refer to 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

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

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 Weka system.

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

$ 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.

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

The method for obtaining a client certificate and key and set it via the KMS is different for each KMS. The certificate itself is generated using OpenSSL, with 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'

See the specific KMS documentation to create a certificate and link it to the Weka cluster in the KMS with sufficient privileges (encrypt/decrypt).

For example, for SmartKey KMS, follow similar instructions as suggested here to create a client certificate and key, and assign a certificate for Weka within SmartKey.