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