2017-11-14 11:13:11 +00:00
|
|
|
---
|
|
|
|
layout: "docs"
|
|
|
|
page_title: "AWS KMS - Seals - Configuration"
|
|
|
|
sidebar_current: "docs-configuration-seal-awskms"
|
|
|
|
description: |-
|
|
|
|
The AWS KMS seal configures Vault to use AWS KMS as the seal wrapping
|
|
|
|
mechanism.
|
|
|
|
---
|
|
|
|
|
|
|
|
# `awskms` Seal
|
|
|
|
|
|
|
|
The AWS KMS seal configures Vault to use AWS KMS as the seal wrapping mechanism.
|
|
|
|
Vault Enterprise's 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.).
|
|
|
|
|
2017-11-14 18:12:35 +00:00
|
|
|
## `awskms` Example
|
2017-11-14 11:13:11 +00:00
|
|
|
|
2017-11-14 18:12:35 +00:00
|
|
|
This example shows configuring AWS KMS seal through the Vault configuration file
|
|
|
|
by providing all the required values:
|
2017-11-14 11:13:11 +00:00
|
|
|
|
2017-11-14 18:12:35 +00:00
|
|
|
```hcl
|
|
|
|
seal "awskms" {
|
2018-01-31 18:41:31 +00:00
|
|
|
region = "us-east-1"
|
2017-11-14 18:12:35 +00:00
|
|
|
access_key = "AKIAIOSFODNN7EXAMPLE"
|
|
|
|
secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
|
|
|
|
kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey"
|
|
|
|
}
|
2017-11-14 11:13:11 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
## `awskms` Parameters
|
|
|
|
|
|
|
|
These parameters apply to the `seal` stanza in the Vault configuration file:
|
|
|
|
|
2017-11-14 18:12:35 +00:00
|
|
|
- `region` `(string: "us-east-1")`: The AWS region where the encryption key
|
2017-11-14 11:13:11 +00:00
|
|
|
lives. May also be specified by the `AWS_REGION` or `AWS_DEFAULT_REGION`
|
|
|
|
environment variable or as part of the AWS profile from the AWS CLI or
|
|
|
|
instance profile.
|
2017-11-14 18:12:35 +00:00
|
|
|
|
|
|
|
- `access_key` `(string: <required>)`: The AWS access key ID to use. May also be
|
2017-11-14 11:13:11 +00:00
|
|
|
specified by the `AWS_ACCESS_KEY_ID` environment variable or as part of the
|
|
|
|
AWS profile from the AWS CLI or instance profile.
|
2017-11-14 18:12:35 +00:00
|
|
|
|
|
|
|
- `secret_key` `(string: <required>)`: The AWS secret access key to use. May
|
2017-11-14 11:13:11 +00:00
|
|
|
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.
|
2017-11-14 18:12:35 +00:00
|
|
|
|
|
|
|
- `kms_key_id` `(string: <required>)`: The AWS KMS key ID to use for encryption
|
2017-11-14 11:13:11 +00:00
|
|
|
and decryption. May also be specified by the `VAULT_AWSKMS_SEAL_KEY_ID`
|
|
|
|
environment variable.
|
|
|
|
|
2017-11-14 18:12:35 +00:00
|
|
|
## Authentication
|
|
|
|
|
|
|
|
Authentication-related values must be provided, either as environment
|
|
|
|
variables or as configuration parameters.
|
|
|
|
|
2017-11-14 11:13:11 +00:00
|
|
|
~> **Note:** Although the configuration file allows you to pass in
|
|
|
|
`AWS_ACCESS_KEY_ID` and `AWS_ACCESS_KEY_ID` as part of the seal's parameters, it
|
2017-11-14 18:12:35 +00:00
|
|
|
is *strongly* recommended to set these values via environment variables.
|
|
|
|
|
|
|
|
```text
|
|
|
|
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.
|
2017-11-14 11:13:11 +00:00
|
|
|
|
|
|
|
## `awskms` Environment Variables
|
|
|
|
|
|
|
|
Alternatively, the AWS KMS seal can be activated by providing the following
|
|
|
|
environment variables:
|
|
|
|
|
|
|
|
```text
|
|
|
|
Vault Seal specific values:
|
|
|
|
|
|
|
|
* `VAULT_SEAL_TYPE`
|
|
|
|
* `VAULT_AWSKMS_SEAL_KEY_ID`
|
|
|
|
```
|
2018-04-25 13:59:06 +00:00
|
|
|
|
|
|
|
## Key Rotation
|
|
|
|
|
|
|
|
This seal 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 seal configuration
|
|
|
|
or set to current under a key alias.
|