Create a KMS configuration

Encryption at rest uses a master key to encrypt and decrypt universe keys. The master key details are stored in YugabyteDB Anywhere in key management service (KMS) configurations. You enable encryption at rest for a universe by assigning the universe a KMS configuration. The master key designated in the configuration is then used for generating the universe keys used for encrypting the universe data.

Encryption at rest in YugabyteDB Anywhere supports the use of HashiCorp Vault as a KMS.

Configure HashiCorp Vault

Before you can start configuring HashiCorp Vault, install it on a virtual machine, as per instructions provided in Install Vault. The vault can be set up as a multi-node cluster. Ensure that your vault installation meets the following requirements:

Has transit secret engine enabled.
Its seal and unseal mechanism is secure and repeatable.
Its token creation mechanism is repeatable.

You need to configure HashiCorp Vault in order to use it with YugabyteDB Anywhere, as follows:

Create a vault configuration file that references your nodes and specifies the address, as follows:

storage "raft" {
path  = "./vault/data/"
node_id = "node1"
}

listener "tcp" {
address   = "127.0.0.1:8200"
tls_disable = "true"
}

api_addr = "http://127.0.0.1:8200"
cluster_addr = "https://127.0.0.1:8201"
ui = true
disable_mlock = true
default_lease_ttl = "768h"
max_lease_ttl = "8760h"

Replace 127.0.0.1 with the vault web address.

For additional configuration options, see Parameters.

Initialize the vault server by following instructions provided in Operator init.
Allow access to the vault by following instructions provided in Unsealing.
Enable the secret engine by executing the following command:
```
vault secrets enable transit
```
For more information, see Transit Secrets Engine and Setup.

Create the vault policy, as per the following sample:

path "transit/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

path "auth/token/lookup-self" {
        capabilities = ["read"]
}

path "sys/capabilities-self" {
        capabilities = ["read", "update"]
}

path "auth/token/renew-self" {
        capabilities = ["update"]
}

path "sys/*" {
        capabilities = ["read"]
}

If you want to use a token for authentication, generate a token with appropriate permissions (as per the referenced policy) by executing the following command:
```
vault token create -no-default-policy -policy=trx
```
You may also specify the following for your token:
- ttl — Time to live (TTL). If not specified, the default TTL of 32 days is used, which means that the generated token will expire after 32 days.
- period — If specified, the token can be infinitely renewed.
If you want to use AppRole for authentication, do the following:
- Obtain AppRole credentials by enabling the auth method in the vault using the following command:
```
vault auth enable approle
```
  Refer to Enable AppRole auth method.
- Generate a role with appropriate permissions (as per the referenced policy) by executing the following command:
```
vault write auth/approle/role/ybahcv token_policies="trx"
```
  You may also specify the following for your token generated from the AppRole:
  - ttl — Time to live (TTL). If not specified, the default TTL of 32 days is used, which means that the generated token will expire after 32 days.
  - period — If specified, the token can be infinitely renewed.
- Obtain the RoleID and SecretID using the following commands:
```
vault read auth/approle/role/ybahcv/role-id
vault write -force auth/approle/role/ybahcv/secret-id
```
  Refer to Generate RoleID and SecretID.

Create a KMS configuration

You can create a new KMS configuration that uses HashiCorp Vault as follows:

Using the YugabyteDB Anywhere UI, navigate to Configs > Security > Encryption At Rest to open a list of existing configurations.
Click Create New Config.
Provide the following configuration details:
- Configuration Name — Enter a meaningful name for your configuration.
- KMS Provider — Select Hashicorp Vault.
- Vault Address — Enter the web address of your vault. For example, http://127.0.0.1:8200
- Authentication Type — Choose the authentication method to use, Token or AppRole.
  
  For Token, enter the token you obtained from the vault.
  
  For AppRole, enter the role ID and corresponding secret ID obtained from the vault. If the vault is configured with namespaces, also enter the namespace used to generate the credentials.
- Key Name - Enter the name of the Master Key in the vault. If you don't provide a key name, the configuration uses the default name key_yugabyte. If a key with that name exists in the vault, the configuration will use it, otherwise a key with that name is created.
- Secret Engine — This is a read-only field with its value set to transit. It identifies the secret engine.
- Mount Path — Specify the path to the secret engine in the vault. The default value is transit/.
Click Save. Your new configuration should appear in the list of configurations.
Optionally, to confirm that the information is correct, click Show details. Note that sensitive configuration values are displayed partially masked.

Modify a KMS configuration

You can modify an existing KMS configuration as follows:

Using the YugabyteDB Anywhere UI, navigate to Configs > Security > Encryption At Rest to open a list of existing configurations.
Find the configuration you want to modify and click its corresponding Actions > Edit Configuration.
Provide new values for the Vault Address and Secret Token fields.
Click Save.
Optionally, to confirm that the information is correct, click Show details or Actions > Details.

Delete a KMS configuration

To delete a KMS configuration, click its corresponding Actions > Delete Configuration.

Note that a saved KMS configuration can only be deleted if it is not in use by any existing universes.