boundary/website/content/docs/configuration/kms/awskms.mdx

---
layout: docs
page_title: AWS KMS Configuration
description: >-
  Learn about using the AWS KMS for key management, configuring parameters and authentication, and best practices for key rotation. View an example configuration.
---

# `awskms`

The AWS KMS configures Boundary to use AWS KMS for key management.

## `awskms` example

This example shows configuring AWS KMS through the Boundary configuration file
by providing all the required values:

```hcl
kms "awskms" {
  purpose    = "root"
  region     = "us-east-1"
  access_key = "AKIAIOSFODNN7EXAMPLE"
  secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
  key_id     = "global_worker-auth"
}
```

## `awskms` parameters

These parameters apply to the `kms` stanza in the Boundary configuration file:

- `purpose` - Purpose of this KMS, acceptable values are: `worker-auth`, `worker-auth-storage`,
   `root`, `previous-root`, `recovery`, `bsr`, or `config`.

   To [enable session recording](/boundary/docs/session-recording/configuration/enable-session-recording), you must configure the `bsr` value for the `purpose`.

- `region` `(string: "us-east-1")`: The AWS region where the encryption key
  lives. If not provided, may be populated from the `AWS_REGION` or
  `AWS_DEFAULT_REGION` environment variables, from your `~/.aws/config` file,
  or from instance metadata.

- `kms_key_id` `(string: <required>)`: The AWS KMS key ID to use for encryption
  and decryption. May also be specified by the `AWSKMS_WRAPPER_KEY_ID`
  environment variable.

- `access_key` `(string: "")`: The AWS access key ID to use. May also be
  specified by the `AWS_ACCESS_KEY_ID` environment variable or as part of the
  AWS profile from the AWS CLI or instance profile.

- `session_token` `(string: "")`: Specifies the AWS session token. This can
  also be provided via the environment variable `AWS_SESSION_TOKEN`.

- `secret_key` `(string: "")`: The AWS secret access key to use. May
  also be specified by the `AWS_SECRET_ACCESS_KEY` environment variable or as
  part of the AWS profile from the AWS CLI or instance profile.

- `shared_creds_filename` `(string: "")`: If set, the file
  name to read as a shared credentials file.

- `shared_creds_profile` `(string: "")`: If set, the
  profile to use from the shared credentials file. If not set, will use the
  `AWS_PROFILE` env var, or if that is not set, `"default"`.

- `role_arn` `(string: "")`: If this and
  `web_identity_token_file` are set, the role ARN to use when using a web
  identity role provider with STS.

- `web_identity_token_file` `(string: "")`: If this and
  `role_arn` are set, the token file to use when using a web identity role
  provider with STS.

- `role_session_name` `(string: "")`: If using the web
  identity role provider, the role session to use.

- `endpoint` `(string: "")`: The KMS API endpoint to be used to make AWS KMS
  requests. May also be specified by the `AWS_KMS_ENDPOINT` environment
  variable. This is useful, for example, when connecting to KMS over a [VPC
  Endpoint](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html).
  If not set, Boundary will use the default API endpoint for your region.

- `key_id` - The unique name of this key.
It is used to identify the key when you perform a root key migration.
You can use the `key_id` field with all KMS stanzas.

## Authentication

Authentication-related values must be provided, either as environment
variables or as configuration parameters.

~> **Note:** Although the configuration file allows you to pass in
`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` as part of the KMS's parameters, it
is _strongly_ recommended to set these values via environment variables.

AWS authentication values:

- `AWS_REGION` or `AWS_DEFAULT_REGION`
- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`

Note: The client uses the official AWS SDK and will use the specified
credentials, environment credentials, shared file credentials, or IAM role/ECS
task credentials in that order, if the above AWS specific values are not
provided.

Boundary needs the following permissions on the KMS key:

- `kms:Encrypt`
- `kms:Decrypt`
- `kms:DescribeKey`

These can be granted via IAM permissions on the principal that Boundary uses, on
the KMS key policy for the KMS key, or via KMS Grants on the key.

## Key rotation

This KMS supports rotating the master keys defined in AWS KMS
[doc](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html). Both automatic
rotation and manual rotation is supported for KMS since the key information is stored with the
encrypted data. Old keys must not be disabled or deleted and are used to decrypt older data.
Any new or updated data will be encrypted with the current key defined in the KMS configuration
or set to current under a key alias.