2021-03-23 21:14:25 +00:00
|
|
|
---
|
|
|
|
|
layout: docs
|
|
|
|
|
page_title: AWS KMS - Key Management - Secrets Engines
|
|
|
|
|
description: AWS KMS is a supported KMS provider of the Key Management secrets engine.
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# AWS KMS
|
|
|
|
|
|
2022-03-17 17:31:32 +00:00
|
|
|
-> **Note**: This secret engine requires [Vault Enterprise](https://www.hashicorp.com/products/vault/)
|
|
|
|
|
with the Advanced Data Protection Module.
|
|
|
|
|
|
2021-03-23 21:14:25 +00:00
|
|
|
The Key Management secrets engine supports lifecycle management of keys in [AWS KMS](https://aws.amazon.com/kms/)
|
|
|
|
|
regions. This is accomplished by configuring a KMS provider resource with the `awskms` provider and
|
|
|
|
|
other provider-specific parameter values.
|
|
|
|
|
|
|
|
|
|
The following sections describe how to properly configure the secrets engine to enable
|
|
|
|
|
the functionality.
|
|
|
|
|
|
|
|
|
|
## Authentication
|
|
|
|
|
|
|
|
|
|
The Key Management secrets engine must be configured with credentials that have sufficient
|
|
|
|
|
permissions to manage keys in an AWS KMS region. The authentication parameters are described
|
|
|
|
|
in the [credentials](/api/secret/key-management/awskms#credentials) section of the API
|
|
|
|
|
documentation. The authentication parameters will be set with the following order of
|
|
|
|
|
precedence:
|
|
|
|
|
|
|
|
|
|
1. [KMS provider credentials](/api/secret/key-management/awskms#credentials)
|
|
|
|
|
2. Environment variables
|
|
|
|
|
3. Shared credentials file
|
|
|
|
|
4. IAM role for AWS EC2 or ECS task
|
|
|
|
|
|
|
|
|
|
The IAM principal associated with the provided credentials must have the following minimum
|
|
|
|
|
[AWS KMS permissions](https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html):
|
|
|
|
|
|
|
|
|
|
- `kms:CreateKey`
|
|
|
|
|
- `kms:GetParametersForImport`
|
|
|
|
|
- `kms:ImportKeyMaterial`
|
|
|
|
|
- `kms:EnableKey`
|
|
|
|
|
- `kms:DisableKey`
|
|
|
|
|
- `kms:ScheduleKeyDeletion`
|
|
|
|
|
- `kms:CreateAlias`
|
|
|
|
|
- `kms:UpdateAlias`
|
|
|
|
|
- `kms:DeleteAlias`
|
|
|
|
|
- `kms:ListAliases`
|
|
|
|
|
- `kms:TagResource`
|
|
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
|
|
|
|
The following is an example of how to configure the KMS provider resource using the Vault CLI:
|
|
|
|
|
|
2021-04-06 17:49:04 +00:00
|
|
|
```text
|
|
|
|
|
$ vault write keymgmt/kms/example-kms \
|
|
|
|
|
provider="awskms" \
|
|
|
|
|
key_collection="us-west-1" \
|
|
|
|
|
credentials=access_key="ASIADJO3WTX6WPLJM42V" \
|
|
|
|
|
credentials=secret_key="bCiYmNroLxLmPNQ47VIvjlm8mQu5oktZcQdq195w"
|
|
|
|
|
```
|
2021-03-23 21:14:25 +00:00
|
|
|
|
|
|
|
|
Refer to the AWS KMS [API documentation](/api/secret/key-management/awskms)
|
|
|
|
|
for a detailed description of individual configuration parameters.
|
|
|
|
|
|
|
|
|
|
## Key Transfer Specification
|
|
|
|
|
|
|
|
|
|
Keys are securely transferred from the secrets engine to AWS KMS regions in accordance
|
|
|
|
|
with the AWS KMS [Bring Your Own Key](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html)
|
|
|
|
|
specification.
|
2021-06-29 17:31:25 +00:00
|
|
|
|
|
|
|
|
## Key Rotation
|
|
|
|
|
|
2022-01-13 18:41:05 +00:00
|
|
|
AWS KMS keys with imported key material are not eligible for
|
2021-06-29 17:31:25 +00:00
|
|
|
[automatic key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)
|
|
|
|
|
within AWS KMS. As such, key rotations performed by the secrets engine use the
|
|
|
|
|
[manual key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotate-keys-manually)
|
|
|
|
|
process. Applications should refer to the [alias](https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html)
|
|
|
|
|
associated with imported keys. Aliases will always have the form: `hashicorp/<key_name>-<unix_timestamp>`.
|
2021-11-16 19:27:08 +00:00
|
|
|
|
|
|
|
|
## Key Purpose Compatability
|
|
|
|
|
|
|
|
|
|
The following table defines which key [purposes](/api-docs/secret/key-management#purpose) can be used
|
|
|
|
|
for each key type supported by AWS KMS.
|
|
|
|
|
|
|
|
|
|
| Key Type | Purpose |
|
|
|
|
|
| -------------- | ----------------------- |
|
|
|
|
|
| `aes256-gcm96` | `encrypt` and `decrypt` |
|
