Encrypt Boundary configuration values

Boundary encrypts sensitive values in its configuration file using a config key management service (KMS) block, so you can commit the file to version control without exposing cloud API keys, database credentials, or other secrets. You mark values with {{encrypt()}}, run boundary config encrypt, and Boundary decrypts them automatically at startup.

Refer to the config KMS key for more information about how the key works.

Requirements

To encrypt configuration values, you need the following:

A Boundary configuration file that contains sensitive values, such as cloud API keys for KMS providers or database credentials.
A KMS that both you and the Boundary server can access. Boundary must be able to reach the same KMS at startup to decrypt the values.
Access to the boundary CLI.

You can configure config KMS keys for self-managed Enterprise deployments.

Encrypt a configuration file

Complete the following steps to encrypt sensitive values and start Boundary with the encrypted file.

Add a kms block with purpose = "config" to your configuration file. Boundary uses this block to encrypt and decrypt the marked values, and it is separate from the KMS blocks that protect Boundary's runtime data.
config.hcl
```
kms "aead" {
  purpose   = "config"
  aead_type = "aes-gcm"
  key       = "7xtkEoS5EXPbgynwd+dDLHopaCqK8cq0Rpep4eooaTs="
}
```
The example writes the key into the same file, which provides no protection on its own. Use it for local testing only. In production, use a cloud KMS provider or store the config block in a separate file. Refer to KMS configuration for the supported providers.
Wrap each sensitive value in an {{encrypt()}} marker.
config.hcl
```
kms "aead" {
  purpose   = "root"
  aead_type = "aes-gcm"
  key       = "{{encrypt(eb78KqCwowELYnkOOko/XYz01q1ax3g76J1vCAvt5dQ=)}}"
}
```
When you define the config KMS block inline in the same file, you can only encrypt quoted string values, and the marker must sit inside the quotation marks that delimit the string. To encrypt values that are not quoted strings, define the config KMS block in a separate file and pass it using -config-kms.
Run boundary config encrypt and pass the configuration file using the -config flag. Without -overwrite, the command prints the result to stdout so that you can inspect it first.
```
$ boundary config encrypt -config config.hcl
```
To write the result back to the same file, add -overwrite:
```
$ boundary config encrypt -config config.hcl -overwrite
```
To use a separate file for the config KMS block, add -config-kms:
```
$ boundary config encrypt -config config.hcl -config-kms kms-config.hcl -overwrite
```
Refer to boundary config encrypt for all command options.
Confirm that the command replaced each marked value with its encrypted form inside a {{decrypt()}} marker.
config.hcl
```
kms "aead" {
  purpose   = "root"
  aead_type = "aes-gcm"
  key       = "{{decrypt(bXktZW5jcnlwdGVkLXZhbHVl)}}"
}
```
The {{decrypt()}} marker tells Boundary which values to decrypt at startup. Do not remove it. If you run the command with -strip, Boundary removes the markers along with the encrypted value's delimiters.
Start the server.
```
$ boundary server -config config.hcl
```
Boundary checks for a config KMS block at startup. When it finds one, it uses the block to decrypt any encrypted values before it applies the configuration.

Decrypt a configuration file

To return a configuration file to plaintext, for troubleshooting, or to rotate a value, run boundary config decrypt against the values marked with {{decrypt()}}:

$ boundary config decrypt -config config.hcl -overwrite

The command restores each value and returns it to an {{encrypt()}} marker, so that you can edit the value and encrypt the file again. Refer to boundary config decrypt for all command options.

Troubleshooting

Missing required parameter -config

The config encrypt and config decrypt commands require the -config flag. Passing the file name on its own is not enough:

$ boundary config encrypt -overwrite config.hcl
Missing required parameter -config

Pass the file using -config instead:

$ boundary config encrypt -config config.hcl -overwrite

No wrapper with "config" purpose found

Boundary could not find a kms block with purpose = "config". Confirm that the block exists in the file you passed to -config, or pass the file that contains it using -config-kms.

Boundary does not start after you encrypt the file

Boundary decrypts the marked values at startup, so it must reach the same KMS you encrypted with. If it cannot reach the KMS, it cannot decrypt the values and does not start. Confirm that the server can reach the KMS provider and that its credentials are still valid.

Next steps

Refer to the following topics for related information:

The config KMS key explains how the key relates to Boundary's other KMS keys.
Migrate a KMS provider describes how to move to a different KMS.