Browse the Repo

file-type-icon.circleci
file-type-icon_ci
file-type-icon_docs
file-type-iconexamples
file-type-iconmodules
file-type-icon_deprecated
file-type-iconauto-update
file-type-iconaws-auth
file-type-iconaws-config
file-type-iconaws-organizations-config-rules
file-type-iconaws-organizations
file-type-iconcloudtrail
file-type-iconcross-account-iam-roles
file-type-iconcustom-iam-entity
file-type-iconfail2ban
file-type-iconguardduty-multi-region
file-type-iconguardduty-single-region
file-type-iconiam-groups
file-type-iconiam-policies
file-type-iconiam-user-password-policy
file-type-iconiam-users
file-type-iconip-lockdown
file-type-iconkms-master-key
file-type-iconREADME.md
file-type-iconmain.tf
file-type-iconoutputs.tf
file-type-iconvars.tf
file-type-iconntp
file-type-iconos-hardening
file-type-iconsaml-iam-roles
file-type-iconssh-grunt-selinux-policy
file-type-iconssh-grunt
file-type-iconssh-iam
file-type-iconssm-healthchecks-iam-permissions
file-type-icontls-cert-private
file-type-icontest
file-type-icon.editorconfig
file-type-icon.gitignore
file-type-iconCODEOWNERS
file-type-iconLICENSE.txt
file-type-iconREADME.adoc

Browse the Repo

file-type-icon.circleci
file-type-icon_ci
file-type-icon_docs
file-type-iconexamples
file-type-iconmodules
file-type-icon_deprecated
file-type-iconauto-update
file-type-iconaws-auth
file-type-iconaws-config
file-type-iconaws-organizations-config-rules
file-type-iconaws-organizations
file-type-iconcloudtrail
file-type-iconcross-account-iam-roles
file-type-iconcustom-iam-entity
file-type-iconfail2ban
file-type-iconguardduty-multi-region
file-type-iconguardduty-single-region
file-type-iconiam-groups
file-type-iconiam-policies
file-type-iconiam-user-password-policy
file-type-iconiam-users
file-type-iconip-lockdown
file-type-iconkms-master-key
file-type-iconREADME.md
file-type-iconmain.tf
file-type-iconoutputs.tf
file-type-iconvars.tf
file-type-iconntp
file-type-iconos-hardening
file-type-iconsaml-iam-roles
file-type-iconssh-grunt-selinux-policy
file-type-iconssh-grunt
file-type-iconssh-iam
file-type-iconssm-healthchecks-iam-permissions
file-type-icontls-cert-private
file-type-icontest
file-type-icon.editorconfig
file-type-icon.gitignore
file-type-iconCODEOWNERS
file-type-iconLICENSE.txt
file-type-iconREADME.adoc
KMS

KMS

Encrypt and decrypt secrets using Amazon's Key Management Service (KMS).

Preview the Code

mobile file icon

README.md

down

KMS Master Key Module

This Terraform Module creates a new Customer Master Key (CMK) in Amazon's Key Management Service (KMS) as well as a Key Policy that controls who has access to the CMK.

A CMK is a key managed by AWS that you never see (and can therefore never compromise). You use use a CMK via the AWS API to encrypt and decrypt small amounts of data and to generate Data Keys that can be used to encrypt and decrypt larger amounts of data.

Using the AWS API with KMS can be clumsy. For a more streamlined experience, try gruntkms.

How do you use this module?

Note: This module creates a Master Key in KMS. Each Master Key costs $1/month, even if you delete it immediately after. So please be aware that using this module will cost you money!

CMK Administrators vs. CMK Users

This CMK Key Policy declares three levels of access to the CMK:

  1. Key Administrators: Administrators can manage the CMK, including updating the Key Policy, revoking the CMK, and getting additional info about the CMK. Administrators get no permissions to actually use the CMK, for example, with encrypt or decrypt operations.

  2. Key Users: Users can use the CMK for encrypt and decrypt operations but cannot manage it.

  3. External Key Users: Users from external AWS accounts can use the CMK for encrypt and decrypt operations but cannot manage it.

You must have at least one IAM ARN for Key Administrators and Key Users user types. External Key Users are optional. Note that this ARN can be an IAM User, IAM Group, or IAM Role.

Background

What is KMS?

Amazon's Key Management Service (KMS) is a managed service that makes it easy for you to create and control the encryption keys used to encrypt your data, and uses Hardware Security Modules (HSMs) to protect the security of your keys.

What is a Customer Master Key?

A Customer Master Key (CMK) is a secret key that KMS stores and manages for you. You can use the CMK to encrypt small amounts of data using the AWS APIs or a tool like gruntkms. It is a "master" key in the sense that you can also use a CMK to generate a "Data Key" that you can use in your own encryption algorithms to encrypt and decrypt large amounts of data.

When you use a Data Key, you typically store it, encrypted via the CMK, in version control or co-located with your data itself, and decrypt it via the AWS API or gruntkms whenever you need to use it to decrypt or encrypt data.

Amazon never grants you access to the CMK itself, only to operations that use the key.

Managing a Key's Permissions with the Key Policy vs. IAM Policies

When you want to grant a permission on most AWS resources, you attach an IAM Policy to an IAM User, IAM Group, or IAM Role. This works well for most resources, but when it comes to CMK's, it means that any admin-level IAM User has full access to all CMK's.

But maybe this isn't what you want. For example, suppose your DevOps team has admin-level access to your AWS account, but they still shouldn't have access to a prod CMK used to encrypt production data. Fortunately, AWS gives us a solution for such situations: the CMK Key Policy.

By default, only the permissions granted in a CMK Key Policy are honored. For example, the CMK Key Policy might grant IAM User jane.doe the kms:encrypt and kms:decrypt permissions. But if john.doe has an IAM Policy that grants him those same permissions on the CMK, that IAM Policy will actually have no effect.

If you do want to honor IAM Policies for a particular CMK, you can include a setting in the CMK Key Policy that grants this permission to IAM. In this case, jane.doe will retain her rights granted from the CMK Key Policy, but now john.doe will have access, too.

In general, we recommend using only the CMK Key Policy if possible. This has the benefit of explicitly declaring who has access to the CMK, versus allowing any possible number of IAM Policy configurations to determine access. But the biggest downside is that it's now possible to lock yourself out of the CMK, so if you're not confident about your ability to manage the CMK, you may wish to use IAM policies. In addition, IAM is a central place for managing all permissions, whereas using just the CMK Key Policy means you now need to update the Key Policy any time the perissions change, which may be more onerous.

TODO

  • Explicitly test that granting another AWS resource such as an S3 Bucket privileges on the KMS Key works as expected for key users.

Questions? Ask away.

We're here to talk about our services, answer any questions, give advice, or just to chat.

Ready to hand off the Gruntwork?