Working with Customer Master Keys (CMKs) using the AWS KMS API

Home » AWS Cheat Sheets » AWS Security & Identity Services » Security Related Notes » Working with Customer Master Keys (CMKs) using the AWS KMS API

Working with Customer Master Keys (CMKs) using the AWS KMS API

What is AWS Key Management Service?

AWS Key Management Service (or KMS for short) is the service you use to securely store your encryption keys in AWS. If you need data encryption on your AWS resources, such as EBS volumes or RDS databases, you can use AWS KMS to simplify the process for you. You start using the service by requesting the creation of a customer master key or CMK. By default, AWS KMS creates the key material for your CMK. You also have the option of importing your own keys to AWS if you wish to. Note that during key rotation, if you imported your own key, you will have to manage the rotation yourself.

Users and developers who manage security can interact with AWS KMS programmatically via the CLI or SDK. These utilize the AWS KMS API for all of the transactions. You also do not use your standard username and password when interacting with the KMS API, so be sure to enter your access keys and secret access keys instead. Once you have configured your AWS profile in your local machine, you can start executing API calls. If you encounter any errors during API calls, check if your IAM User has been granted the necessary permissions to perform that action.

List of Commonly Used AWS KMS APIs

Below are some of the KMS API commands that you should know of:

  • Create, describe, list, enable, and disable CMK keys

To create a customer master key (CMK), run the CreateKey operation. By default, this command creates a symmetric CMK for you. Also, if the key is created via API, only the root user of the AWS account who owns this key has full access.

aws kms create-key


You can also create an asymmetric CMK if that is what you need. Here, you must specify the CustomerMasterKeySpec parameter, which determines the encryption algorithm that KMS will use. Also, you must specify a KeyUsage value of ENCRYPT_DECRYPT or SIGN_VERIFY. You cannot change these properties after the CMK is created.

awz kms create-key --customer-master-key-spec RSA_4096 --key-usage ENCRYPT_DECRYPT
aws kms create-key --customer-master-key-spec ECC_NIST_P521 --key-usage SIGN_VERIFY



You can also specify some additional parameters during key creation

    • BypassPolicyLockoutSafetyCheck (bool) – Indicates whether to bypass the key policy lockout safety check.
    • CustomKeyStoreId (string) – Creates the CMK in the specified custom key store and the key material in its associated AWS CloudHSM cluster.
    • Description (string)
    • Origin (string) – The source of the key material for the CMK. You cannot change the origin after you create the CMK. The default is AWS_KMS.
    • Policy (string) – The key policy to attach to the CMK.
    • Tags (dict)
Tutorials dojo strip

To list all the CMKs under your account, run the ListKeys operation.

aws kms list-keys


To see the metadata and other details of a specific key, run the DescribeKey operation and enter the key id of interest.

aws kms describe-key --key-id 1234abcd-12ab-34cd-56ef-1234567890ab


If you want to set which keys should and should not be used, run the EnableKey and DisableKey operations and enter the key id of interest.

aws kms enable-key --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
aws kms disable-key --key-id 1234abcd-12ab-34cd-56ef-1234567890ab


  • Encrypt, decrypt, and re-encrypt content

To encrypt plaintext into ciphertext using your CMK, run Encrypt command. Enter the key id you’d like to use and the data you’d like to encrypt. After running it, the API will return your ciphertext in blob format, the key id used and the encryption algorithm used.

aws kms encrypt --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --plaintext fileb://ExamplePlaintextFile


You can specify additional parameters during encryption

    • EncryptionAlgorithm (SYMMETRIC_DEFAULT | RSAES_OAEP_SHA_1 | RSAES_OAEP_SHA_256)
    • EncryptionContext (dict)

To decrypt your ciphertext, run the Decrypt command and enter your ciphertext blob. If you used an asymmetric CMK to encrypt this text, then you need to specify a key id parameter. You should also specify the encryption algorithm and encryption context if the defaults were not used. After running it, the API will return your plaintext, key id used for decryption, and the encryption algorithm used.

aws kms decrypt --ciphertext-blob fileb://ExampleCiphertextFile


You can specify the following additional parameters during decryption

    • EncryptionAlgorithm (SYMMETRIC_DEFAULT | RSAES_OAEP_SHA_1 | RSAES_OAEP_SHA_256)
    • EncryptionContext (dict)

If you will be rotating keys or changing encryption algorithms, run the ReEncrypt command to re-encrypt your data to a new CMK or algorithm. If you used an asymmetric key to encrypt your plaintext, you must specify the source key id used during encryption. If you used a non-default encryption algorithm and an encryption context, be sure to indicate them in the API call.

aws kms re-encrypt --ciphertext-blob fileb://ExampleCiphertextFile --destination-key-id 1234abcd-12ab-34cd-56ef-1234567890ac


You can specify the following additional parameters during re-encryption

    • DestinationEncryptionAlgorithm (SYMMETRIC_DEFAULT | RSAES_OAEP_SHA_1 | RSAES_OAEP_SHA_256)
    • DestinationEncryptionContext (dict)
    • SourceEncryptionAlgorithm (SYMMETRIC_DEFAULT | RSAES_OAEP_SHA_1 | RSAES_OAEP_SHA_256)
    • SourceEncryptionContext (dict)
    • SourceKeyId (string)


  • Set, list, and retrieve key policies

Key policies are the primary way to control access to CMKs in AWS KMS. To add a key policy to a CMK, run the PutKeyPolicy command. This API requires you to specify the key id to which the policy will be applied to, a policy name with “default” as the value and the KMS policy itself.

aws kms put-key-policy --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --policy-name default --policy file://key_policy.json


Example key_policy.json

Working with Customer Master Keys

AWS Exam Readiness Courses

To list down all the key policies attached to a CMK, run the ListKeyPolicies command. You must supply the key id of the CMK in the API call. The returned value will be a list of policy names.

aws kms list-key-policies --key-id 1234abcd-12ab-34cd-56ef-1234567890ab


To view the contents of a policy, run the GetKeyPolicy command. You must supply the key id of the CMK and the policy name in the API call. 

aws kms get-key-policy --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --policy-name default


Final thoughts

CMKs enable you to have control over your encryption needs in AWS. If you have applications that use AWS KMS, be sure to check the AWS SDK documentation for the appropriate syntax for your application’s programming language. And thus, it is a good practice to always encrypt any valuable data you have at rest and in transit, and AWS KMS helps you in doing just that.

Note: If you are studying for the AWS Certified Security Specialty exam, we highly recommend that you take our AWS Certified Security – Specialty Practice Exams and read our Security Specialty exam study guide.

AWS Certified Security - Specialty Exam Study Path


Tutorials Dojo portal

Enroll Now – Our AWS Certification Exam Reviewers

AWS Practice Exams Tutorials Dojo

FREE AWS Exam Readiness Digital Courses

Enroll Now – Our Azure Certification Exam Reviewers

azure reviewers tutorials dojo

Enroll Now – Our Google Cloud Certification Exam Reviewers

Tutorials Dojo Exam Study Guide eBooks

tutorials dojo study guide eBook

Subscribe to our YouTube Channel

Tutorials Dojo YouTube Channel

FREE Intro to Cloud Computing for Beginners

FREE AWS, Azure, GCP Practice Test Samplers

Recent Posts

AWS, Azure, and GCP Certifications are consistently among the top-paying IT certifications in the world, considering that most companies have now shifted to the cloud. Earn over $150,000 per year with an AWS, Azure, or GCP certification!

Follow us on LinkedIn, YouTube, Facebook, or join our Slack study group. More importantly, answer as many practice exams as you can to help increase your chances of passing your certification exams on your first try!

View Our AWS, Azure, and GCP Exam Reviewers Check out our FREE courses

Our Community

passing rate
Around 95-98% of our students pass the AWS Certification exams after training with our courses.
Over 200k enrollees choose Tutorials Dojo in preparing for their AWS Certification exams.
Our courses are highly rated by our enrollees from all over the world.

What our students say about us?