1---
2layout: docs
3page_title: AWS KMS - Seals - Configuration
4description: |-
5  The AWS KMS seal configures Vault to use AWS KMS as the seal wrapping
6  mechanism.
7---
8
9# `awskms` Seal
10
11The AWS KMS seal configures Vault to use AWS KMS as the seal wrapping mechanism.
12The AWS KMS seal is activated by one of the following:
13
14- The presence of a `seal "awskms"` block in Vault's configuration file
15- The presence of the environment variable `VAULT_SEAL_TYPE` set to `awskms`. If
16  enabling via environment variable, all other required values specific to AWS
17  KMS (i.e. `VAULT_AWSKMS_SEAL_KEY_ID`) must be also supplied, as well as all
18  other AWS-related environment variables that lends to successful
19  authentication (i.e. `AWS_ACCESS_KEY_ID`, etc.).
20
21## `awskms` Example
22
23This example shows configuring AWS KMS seal through the Vault configuration file
24by providing all the required values:
25
26```hcl
27seal "awskms" {
28  region     = "us-east-1"
29  access_key = "AKIAIOSFODNN7EXAMPLE"
30  secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
31  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey"
32  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
33}
34```
35
36## `awskms` Parameters
37
38These parameters apply to the `seal` stanza in the Vault configuration file:
39
40- `region` `(string: "us-east-1")`: The AWS region where the encryption key
41  lives. If not provided, may be populated from the `AWS_REGION` or
42  `AWS_DEFAULT_REGION` environment variables, from your `~/.aws/config` file,
43  or from instance metadata.
44
45- `access_key` `(string: <required>)`: The AWS access key ID to use. May also be
46  specified by the `AWS_ACCESS_KEY_ID` environment variable or as part of the
47  AWS profile from the AWS CLI or instance profile.
48
49- `session_token` `(string: "")`: Specifies the AWS session token. This can
50  also be provided via the environment variable `AWS_SESSION_TOKEN`.
51
52- `secret_key` `(string: <required>)`: The AWS secret access key to use. May
53  also be specified by the `AWS_SECRET_ACCESS_KEY` environment variable or as
54  part of the AWS profile from the AWS CLI or instance profile.
55
56- `kms_key_id` `(string: <required>)`: The AWS KMS key ID to use for encryption
57  and decryption. May also be specified by the `VAULT_AWSKMS_SEAL_KEY_ID`
58  environment variable.
59
60- `endpoint` `(string: "")`: The KMS API endpoint to be used to make AWS KMS
61  requests. May also be specified by the `AWS_KMS_ENDPOINT` environment
62  variable. This is useful, for example, when connecting to KMS over a [VPC
63  Endpoint](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html).
64  If not set, Vault will use the default API endpoint for your region.
65
66## Authentication
67
68Authentication-related values must be provided, either as environment
69variables or as configuration parameters.
70
71~> **Note:** Although the configuration file allows you to pass in
72`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` as part of the seal's parameters, it
73is _strongly_ recommended to set these values via environment variables.
74
75AWS authentication values:
76
77- `AWS_REGION` or `AWS_DEFAULT_REGION`
78- `AWS_ACCESS_KEY_ID`
79- `AWS_SECRET_ACCESS_KEY`
80
81Note: The client uses the official AWS SDK and will use the specified
82credentials, environment credentials, shared file credentials, or IAM role/ECS
83task credentials in that order, if the above AWS specific values are not
84provided.
85
86Vault needs the following permissions on the KMS key:
87
88- `kms:Encrypt`
89- `kms:Decrypt`
90- `kms:DescribeKey`
91
92These can be granted via IAM permissions on the principal that Vault uses, on
93the KMS key policy for the KMS key, or via KMS Grants on the key.
94
95## `awskms` Environment Variables
96
97Alternatively, the AWS KMS seal can be activated by providing the following
98environment variables.
99
100Vault Seal specific values:
101
102- `VAULT_SEAL_TYPE`
103- `VAULT_AWSKMS_SEAL_KEY_ID`
104
105## Key Rotation
106
107This seal supports rotating the master keys defined in AWS KMS
108[doc](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html). Both automatic
109rotation and manual rotation is supported for KMS since the key information is stored with the
110encrypted data. Old keys must not be disabled or deleted and are used to decrypt older data.
111Any new or updated data will be encrypted with the current key defined in the seal configuration
112or set to current under a key alias.
113
114## AWS Instance Metadata Timeout
115
116@include 'aws-imds-timeout.mdx'
117
118## Learn
119
120Refer to the [Auto-unseal using AWS KMS](https://learn.hashicorp.com/vault/operations/ops-autounseal-aws-kms)
121guide for a step-by-step tutorial.
122