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)
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
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.
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/