Browse the Repo
Browse the Repo
Encrypt and decrypt secrets using Amazon's Key Management Service (KMS).
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.
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!
This CMK Key Policy declares three levels of access to the CMK:
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.
Key Users: Users can use the CMK for encrypt and decrypt operations but cannot manage it.
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.
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.
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.
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
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.
We're here to talk about our services, answer any questions, give advice, or just to chat.