HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Vault
Vault Home

AWS KMS seal configuration

Seal wrapping requires Vault Enterprise

All Vault versions support auto-unseal for AWS, but seal wrapping requires Vault Enterprise.

Vault Enterprise enables seal wrapping by default, which means the KMS service must be available at runtime and not just during the unseal process. Refer to the Seal wrap overview for more information.

The AWS KMS seal configures Vault to use AWS KMS as the seal wrapping mechanism. The AWS KMS seal is activated by one of the following:

  • The presence of a seal "awskms" block in Vault's configuration file
  • The presence of the environment variable VAULT_SEAL_TYPE set to awskms. If enabling via environment variable, all other required values specific to AWS KMS (i.e. VAULT_AWSKMS_SEAL_KEY_ID) must be also supplied, as well as all other AWS-related environment variables that lends to successful authentication (i.e. AWS_ACCESS_KEY_ID, etc.).

awskms example

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

seal "awskms" {
  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"
}

awskms parameters

These parameters apply to the seal stanza in the Vault configuration file:

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

  • access_key (string: <required>): 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: <required>): 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.

  • kms_key_id (string: <required>): The AWS KMS key ID or ARN to use for encryption and decryption. May also be specified by the VAULT_AWSKMS_SEAL_KEY_ID environment variable. An alias in the format alias/key-alias-name may also be used here.

  • disabled (string: ""): Set this to true if Vault is migrating from an auto seal configuration. Otherwise, set to false.

  • 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. If not set, Vault will use the default API endpoint for your region.

Refer to the Seal Migration documentation for more information about the seal migration process.

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 seal's parameters, it is strongly recommended to set these values via environment variables.

AWS authentication values:

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.

Vault needs the following permissions on the KMS key:

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

awskms environment variables

Alternatively, the AWS KMS seal can be activated by providing the following environment variables.

Vault Seal specific values:

Key rotation

This seal supports rotating the root keys defined in AWS KMS doc. 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 seal configuration or set to current under a key alias.

AWS instance metadata timeout

Affects Vault 1.4 and later

Anytime Vault uses the instance metadata service on an EC2 instance, such as for getting credentials from the instance profile, there may be a delay with the introduction of v2 of the instance metadata service (IMDSv2). The AWS SDK used by Vault first attempts to connect to IMDSv2, and if that times out, it falls back to v1. In Vault 1.4, this timeout can take up to 2 minutes. In Vault 1.5.5 and later, it can take up to 2 seconds with this fix: #10133.

The timeout occurs in situations where there is a proxy between Vault and IMDSv2, and the instance hop limit is set to less than the number of "hops" between Vault and IMDSv2. For example, if Vault is running in docker on an EC2 instance with the instance hop limit set to 1, the AWS SDK client will attempt to connect to IMDSv2, timeout, and fall back to IMDSv1 because of the extra network hop between docker and IMDS.

To avoid the timeout behavior, the hop limit may be adjusted on the underlying EC2 instances. With the docker example, setting the hop limit to 2 will allow the AWS SDK in Vault to connect to IMDSv2 without delay.

Tutorial

Refer to the Auto-unseal using AWS KMS tutorial to learn how to auto-unseal Vault using AWS KMS.

Edit this page on GitHub