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.

• AWS KMS
• Google KMS
• Azure Key Vault
• HashiCorp Vault

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:

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

2. Initialize the vault server by following instructions provided in Operator init.

3. Allow access to the vault by following instructions provided in Unsealing.

4. Enable the secret engine by executing the following command:

   vault secrets enable transit
   

   For more information, see Transit Secrets Engine and Setup.

5. 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"]
   }
   

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

   YugabyteDB Anywhere automatically tries to renew the token every 12 hours after it has passed 70% of its expiry window; as a result, you should set the TTL or period to be greater than 12 hours.

   For more information, refer to Tokens in the Hashicorp documentation.

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

1. Navigate to Integrations > Security > Encryption At Rest to open a list of existing configurations.

2. Click Create New Config.

3. 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/.

   

4. Click Save. Your new configuration should appear in the list of configurations.

5. Optionally, to confirm that the information is correct, click Show details. Note that sensitive configuration values are displayed partially masked.

Replace an expiring token

If a KMS configuration uses a token for authentication, and that token cannot be infinitely renewed, you should replace the token before it expires (that is, reaches its TTL). You can also create a new policy, or switch to using an AppRole.

To replace a token, you create a new token for the existing policy in Vault, and add it to your KMS configuration in YugabyteDB Anywhere as follows:

1. In Hashicorp Vault, create a token for your existing policy. For example:

   vault token create -no-default-policy -policy=trx
   

   If you want to change the policy, see the steps in Configure Hashicorp Vault.

2. In YugabyteDB Anywhere, navigate to Integrations > Security > Encryption At Rest to open a list of existing configurations.

3. Find the KMS configuration you want to modify and click its corresponding Actions > Edit Configuration.

4. Set Authentication Type to Token and enter the token you obtained from the vault.

   To switch to using an AppRole, set Authentication Type to AppRole and enter the credentials as appropriate.

5. Click Save.

To confirm that the information is correct, click Show details or Actions > Details.

Delete a KMS configuration

To delete a KMS configuration, navigate to Integrations > Security > Encryption At Rest to open a list of existing configurations and click its corresponding Actions > Delete Configuration.