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:

IT Certification Category (English)728x90
  • 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)

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

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.

 

Sources:
https://docs.aws.amazon.com/kms/latest/developerguide/programming-keys.html
https://docs.aws.amazon.com/kms/latest/APIReference/API_Operations.html
https://docs.aws.amazon.com/cli/latest/reference/kms/

***

AWS Certifications are consistently among the top paying IT certifications in the world, considering that Amazon Web Services is the leading cloud services platform with almost 50% market share! Earn over $150,000 per year with an AWS certification!

Subscribe to our newsletter and notifications for more helpful AWS cheat sheets and study guides like this and answer as many AWS practice exams as you can.🙂

Pass your AWS Certifications on your First Try with the Tutorials Dojo Portal

Tutorials Dojo portal

Our Bestselling AWS Certified Solutions Architect Associate Practice Exams

AWS Certified Solutions Architect Associate Practice Exams

Enroll Now – Our AWS Practice Exams with 95% Passing Rate

AWS Practice Exams Tutorials Dojo

Tutorials Dojo Study Guide and Cheat Sheets eBooks

Tutorials Dojo Study Guide and Cheat Sheets-2

FREE AWS eBook for Beginners

AWS eBook Tutorials Dojo

FREE AWS Practice Test Samplers

Browse Other Courses

Generic Category (English)300x250

Recent Posts