Project: SPIRE (Provisioning / Key Management)
File: plugin_server_keymanager_aws_kms.md

The `aws_kms` key manager plugin leverages the AWS Key Management Service (KMS) to create, maintain and rotate key pairs (as , or CMKs), and sign SVIDs as needed, with the private key never leaving KMS. The plugin accepts the following configuration options: | Key | Type | Required | Description | Default | |-|--||--|| | accesskeyid | string | see | The Access Key Id used to authenticate to KMS | Value of the AWSACCESSKEY_ID environment variable | | secretaccesskey | string | see | The Secret Access Key used to authenticate to KMS | Value of the AWSSECRETACCESS_KEY environment variable | | region | string | yes | The region where the keys will be stored | | | keymetadatafile | string | no | A file path location where information about generated keys will be persisted (deprecated, use keyidentifierfile instead) | | | keyidentifierfile | string | Required if keyidentifiervalue is not set | A file path location where information about generated keys will be persisted | | | keyidentifiervalue | string | Required if keyidentifierfile is not set | A static identifier for the SPIRE server instance (used instead of `keymetadatafile`) | | | keypolicyfile | string | no | A file path location to a custom key policy in JSON format | "" | The plugin assigns to the Customer Master Keys that manages. The aliases are used to identify and name keys that are managed by the plugin. Aliases managed by the plugin have the following form: `alias/SPIRESERVER/{TRUSTDOMAIN}/{SERVERID}/{KEYID}`. The `{SERVERID}` is an auto-generated ID unique to the server and is persisted in the Key Metadata File (see the `keymetadatafile` configurable). This ID allows multiple servers in the same trust domain (e.g. servers in HA deployments) to manage keys with identical `{KEYID}`'s without collision. The `{KEY_ID}` in the alias name is encoded to use a . If the Key Metadata File is not found on server startup, the file is recreated, with a new auto-generated server ID. Consequently, if the file is lost, the plugin will not be able to identify keys that it has previously managed and will recreate new keys on

The plugin attempts to detect and prune stale aliases. To facilitate stale alias detection, the plugin actively updates the `LastUpdatedDate` field on all aliases every 6 hours. The plugin periodically scans aliases. Any alias encountered with a `LastUpdatedDate` older than two weeks is removed, along with its associated key. The plugin also attempts to detect and prune stale keys. All keys managed by the plugin are assigned a `Description` of the form `SPIRESERVER/{TRUSTDOMAIN}`. The plugin periodically scans the keys. Any key with a `Description` matching the proper form, that is both unassociated with any alias and has a `CreationDate` older than 48 hours, is removed. Access to AWS KMS can be given by either setting the `accesskeyid` and `secretaccesskey`, or by ensuring that the plugin runs on an EC2 instance with a given IAM role that has a specific set of permissions. The IAM role must have an attached policy with the following permissions: `kms:CreateAlias` `kms:CreateKey` `kms:DescribeKey` `kms:GetPublicKey` `kms:ListKeys` `kms:ListAliases` `kms:ScheduleKeyDeletion` `kms:Sign` `kms:UpdateAlias` `kms:DeleteAlias` The plugin can generate keys using a default key policy or it can load and use a user defined policy. The default key policy relies on the SPIRE Server's assumed role. Therefore, it is mandatory for SPIRE server to assume a role in order to use the default policy. ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "Allow full access to the SPIRE Server role", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/example-assumed-role-name" }, "Action": "kms:*", "Resource": "*" }, { "Sid": "Allow KMS console to display the key and policy", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:root" }, "Action": [ "kms:Describe*", "kms:List*", "kms:Get*" ], "Resource": "*" } ] } ``` The first statement of the policy gives the current SPIRE server assumed role full access to the CMK. The second statement allows the keys and policy to be displayed in the KMS console. It is also possible for the user to define a custom key policy. If the configurable `keypolicyfile` is set, the plugin uses the policy defined in the file instead of the default policy. ```hcl KeyManager "aws_kms" { plugin_data { region = "us-east-2" keymetadatafile = "./key_metadata" } } ``` The plugin supports all the key types supported by SPIRE: `rsa-2048`, `rsa-4096`, `ec-p256`, and `ec-p384`.