In this blog post, we will talk about the AWS key management service or KMS and how to use aws kms cli.
What is the KMS?
KMS is the essential service in AWS; if you need to do any encryption, let’s look.
KMS is a regional managed service that makes it straightforward to produce and manage the encryption keys to encrypt your data.
KMS manages what is named customer master keys or CMKs.
We can interpret the CMK as a logical representation of a key.
Let’s make an analogy where the CMK could be a pointer or reference to some underlying cryptographic element.
The CMKs you create live in the AWS region and never move out from KMS or that region.
KMS is perfect for encrypting objects, like database passwords or API keys, stored in the systems manager parameter store.
Also, CMKs can encrypt and decrypt data up to 4 kb in size, and also KMS is combined and used with most AWS services.
How much costs the KMS?
To use KMS, you pay per API call.
So, it means that for API calls like encrypting data, decrypting, listing your keys, or encrypting data or files, you’ll pay each time you call to do those operations.
KMS and CloudTrail
KMS works with audit capability employing CloudTrail. The CloudTrail logs use the S3 to store the audit logs. The logs help make it simpler to meet your compliance obligations.
Now it’s crucial to know that KMS is a FIPs 140-2 level two service FIPS is a U.S. government computer security standard applied to validate cryptographic modules.
Level two means you have to give proof of tampering.
There is a level three, which CloudHSM uses. Check our previous post about CloudHSM. Also, understand the differences between KMS and CloudHSM.
Level three has even more robust security tools than level two.
The CMK types
There are three types of CMKs. Let’s see each of them.
The first is an AWS-managed CMK, and these CMKs are available for free.
These are generated automatically when you first generate an encrypted resource in an AWS service. You can follow the usage of an AWS-managed CMK. However, the lifecycle and permissions of the key are managed on your side by KMS.
Subsequently, we have customer-managed CMKs. These are the ones that only you can generate.
Customer-managed CMKs give you complete control across the lifecycle and permissions that define who can handle the key and under which circumstances.
Cryptographic most suitable practices discourage the comprehensive reuse of encryption keys, so key rotation is essential, and subsequently, we have AWS-owned CMKs.
These are collections of CMKs that an AWS service controls and manages for utilization in multiple AWS accounts. These are not within your AWS account, and only an AWS service can use its
AWS-owned CMK guards the resources in your account, but you can’t see, use, track, or audit any of these.
Types of Encryption for AWS KMS
Does AWS KMS support asymmetric keys? Yes.
Now, there are two types of encryption for CMKs, symmetric and asymmetric, and I’ll go through the distinctions between both.
Symmetric Key
When you generate a customer master key in KMS, by default, you receive a symmetric CMK.
You can use the same key, symmetric CMK, for encryption and decryption.
That encryption algorithm is based on the AES-256 standard, and with a symmetric CMK, your data never moves AWS out unencrypted.
You have to request the KMS APIs to utilize the CMKs. All the AWS services combined with KMS utilize symmetric CMKs, and you’ll use a symmetric CMK to encrypt, decrypt, and re-encrypt data.
You can also use these symmetric CMKs to create keys, key pairs, and arbitrary byte strings. More further, I’ll show you how to use symmetric CMKs at the command line. You could also employ symmetric CMKs to import your own key.
AWS Asymmetric keys
An asymmetric CMK denotes a mathematically correlated public key and private key pair. Thus, you can provide the public key to anyone, despite not being trusted, although you must keep the private key secret.
It’s worth remembering that is how SSL certificates work.
RSA and elliptic curve cryptography ECC is the algorithms where the Asymmetric CMKs are based.
The ECC algorithm is brand-new and is frequently recognized as safer than the more traditional RSA algorithm.
With asymmetric CMKs, the private key never goes AWS out unencrypted. Instead, you must call the KMS APIs to use the private key.
Additionally, you could download the public key and use it outside of AWS, and these are most frequently used outside of AWS by users who can’t request KMS APIs.
How to use AWS Asymmetric keys
Those AWS services that are used with KMS do not support asymmetric CMKs. So you have to use the symmetric ones, and these asymmetric CMKs are commonly used to endorse messages and check signatures.
So when you build a CMK programmatically calling the KMS API, including over the AWS SDKs and command-line tools, you have the alternative of presenting the key policy for the new CMK. If you don’t give one, KMS generates one for you.
AWS KMS Policy Example
Below is an example of one policy you can add to a KMS key policy in a statement. We’re allowing a role called encryption. We also assume this role to permit the actions noted in the policy statement, which are the cryptographic activities for encrypting and decrypting data with a CMK.
{
"Version": "2012-10-17",
"Id": "key-default-1",
"Statement": [
{
"Sid": "Enable IAM User Permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789010:root"
},
"Action": "kms:*",
"Resource": "*"
}
]
}
It’ll look like the one from the policy above, and this default key policy has one policy statement that provides the AWS account,
the root user that holds the CMK complete access to the CMK and
allows IAM policies in the AWS account to enable access to the CMK.
Critical information regarding the key policies attached to your keys:
Suppose you unintentionally remove this statement or modify its permissions,
the account. In that case, the actual user can’t access the key, so it means you’ll have to communicate with AWS support to recover access. So be extremely cautious.
What are AWS Managed Keys
From the screenshot above, we have AWS-managed keys.
When you communicate with an AWS service that uses KMS and uses that encryption, you’ll notice an alias generator for that service. Remember, these are handled by AWS, and you don’t have control over them.
Following, we have our customer-managed keys. So let’s use the command line and start generating customer-managed keys.
AWS KMS S3 Encryption
It’s worth remembering that KMS is a regional service, so the notion of regional is essential. For example, suppose we have an object in S3 Bucket that’s encrypted with a CMK in one region, and we need to transfer that object to a different region. In that case, we need to decrypt the object, move it to the other region, and later re-encrypt it with a different CMK, a CMK in another region.
Let’s learn how to use KMS using the command line.
So our initial command is to create an AWS KMS key, and then we want to give that key a description.
aws kms create-key --description "Bitslovers CMK Demo"
Later, after executing the command above, it returns several values.
The most relevant to note is the keyId.
Take notes from your keyId, and we will use it in our following command.
{
"KeyMetadata": {
"AWSAccountId": "123031469431",
"KeyId": "52f511eb-30df-404d-99fe-de718419c485",
"Arn": "arn:aws:kms:us-east-1:XXXXXXXX:key/52f511eb-30df-404d-99fe-de718419c485",
"CreationDate": "2021-10-06T05:53:22.667000-05:00",
"Enabled": true,
"Description": "Bitslovers CMK Demo",
"KeyUsage": "ENCRYPT_DECRYPT",
"KeyState": "Enabled",
"Origin": "AWS_KMS",
"KeyManager": "CUSTOMER",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"MultiRegion": false
}
}
Creating an Alias for CMK Keys
An alias looks like a shortcut to a key and can designate different keys using the identical name, which helps key rotation or swapping keys out without changing your application. To do this, we’ll perform an API call to AWS KMS and create an alias, so let’s do it:
aws kms create-alias --target-key-id 52f511eb-30df-404d-99fe-de718419c485 --alias-name "alias/bitslovers"
To check if AWS API created your keys successfully, you can call the API again to list all keys.
aws kms list-keys
Rotation Policy for KMS Key
You can further specify a rotation policy.
If you select the check-box from the screenshot above will automatically rotate the CMK each year. For AWS-managed keys are rotated by AWS every three years.
AWS KMS CLI: How to use KMS Key on command-line
AWS KMS CLI: How to use KMS to encrypt a local file
Let’s create a text file for our example:
echo "Bitslovers.com secrect text" > /tmp/secrect.txt
aws kms encrypt --key-id "alias/bitslovers" --plaintext file:///tmp/secrect.txt --output text --query CiphertextBlob
if you got an error message like this:
Invalid base64: "secrect.txt"
Try another approach:
aws kms encrypt --key-id "alias/bitslovers" --cli-binary-format raw-in-base64-out --plaintext file:///tmp/secrect.txt --output text --query CiphertextBlob
You should see an output like the one below:
AQICAHhQz9Nugb8llpXYCZrgdbOP6MRy8gS0iQ/m5WzvMrhCWgGUG/XR2HGW7KWgi9lwU+M0AAAAejB4BgkqhkiG9w0BBwagazBpAgEAMGQGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMeLTF9ZQdESTzY3xyAgEQgDeqXVJVAXxlrdanpvRgzXPOjin5mv6s2vAegcbPeLHOvU54TMfUU4gd5VzqU0mM8+wUlnpwYXyJ
To execute this API, we used the alias, but we can also use the KeyId.
Also, we specified the –plaintext as our local file to encrypt its content.
The output is a ciphertext blob in a base 64 encoded pattern. Remember, when you use the KMS at the command line like the example above, you’re essentially always working with base 64 encoded.
Our next step is to get this encrypted blob base 64, decode it, and save that raw encrypted binary data to a local file.
aws kms encrypt --key-id "alias/bitslovers" --cli-binary-format raw-in-base64-out --plaintext file:///tmp/secrect.txt --output text --query CiphertextBlob --region us-east-1 | base64 --decode > /tmp/secrect.txt.encrypted
if you see the /tmp/secrect.txt.encrypted content, it looks like this:
The command looks like the previous command, but we’re piping the output to the base 64 decode and, at the same time, writing the result to secret.txt.encrypted.
AWS KMS CLI: How to use KMS to decrypt a local file
Our encrypted file is not base 64 encoded. So in this scenario, to decrypt this file, it’s required to specify different parameters for our command line:
aws kms decrypt --ciphertext-blob fileb:///tmp/secrect.txt.encrypted --output text --query Plaintext | base64 --decode
Notice that now we used “fileb” because the encrypted data is in binary form, so not based 64 encoded ASCII.
So like I stated before, anytime we operate with KMS at the command line, we’re almost constantly working with base 64 encoded data.
So we always need to decode the output. By using a pipe, we can translate the data and later get our decrypted data.
One good news about decrypting our data is that we don’t need to specify the CMK, and the reason for that is because every time you use a CMK to encrypt a file, there’s a reference back to the CMK that is encrypted inside the data.
AWS MSK Limitations
I already mentioned before that CMKs are used to encrypt and decrypt data up to 4 kb in size. But, what can we do if you want to encrypt the data file larger?
To accomplish that, we can utilize something named a data encryption key or DEK.
Let’s learn how to generate a DEK.
aws kms generate-data-key --key-id "alias/bitslovers" --key-spec AES_256
So this command above returns the plain text data key and is encrypted with the specified CMK version of the data key. The encrypted data is referred to as a ciphertext blob.
First, you need to save the return ciphertext blob. You’ll need that later.
The ciphertext blob has metadata that describes KMS, which you used CMK to create; also, you can apply the plain text data key to encrypt any amount of data.
So you’re not limited by that four-kilobyte limitation. However, it would be best if you threw away the plain text data key. Instead, be sure to save the ciphertext blob along with your encrypted data.
Throw away the plain text data key guarantees that the encrypted data won’t be compromised as long as the plain text data key is destroyed after any encryption or decryption process.
Someone can take to the ciphertext blob, but unless they can request KMS to decrypt it, they cannot decrypt the encrypted data with only the ciphertext blob.
This concept is what’s introduced as envelope encryption.
So while KMS does support transferring data up to 4 kb to be encrypted right by the KMS envelope, encryption can give notable performance advantages.
When you encrypt data directly with KMS, it has to be moved across the network. For massive data files, this can be ineffective.
Envelope encryption decreases the network load since only the request, and transfer of the much shorter data key go over the network.
The data key is applied locally in your application or encrypting AWS service, bypassing the requirement to send the whole block of data to KMS and experiencing network latency.
Conclusion
The KMS is the perfect service to encrypt and decrypt data without worrying about storing the key. And it’s straightforward to use AWS KMS CLI, or even we can use the SDK available for several languages on our application. Check out also the official documentation.
I hope that you have learned all you need to get started and use KMS.
Please leave a comment, and join us on social media.
Thanks
Other Posts Related to AWS
Understand the difference between the KMS and CloudHSM.
