What is the purpose of kms:GenerateDataKey in AWS?

Question

I'm writing a serverless function on AWS Lambda.

On certain instances I need to use kms:GenerateDataKey* permissions.

What exactly is the purpose of this. I checked the AWS documentation but it is too cryptic. Can someone give a practical example of where this is used?

Answer 1

A Lambda function that requires kms:GenerateDataKey permission is most likely encrypting large amounts of data using a symmetric data key.

kms:GenerateDataKey is used to implement envelope encryption, which is the process of encrypting a key with another key. Symmetric key algorithms are faster and produce smaller ciphertexts than public key algorithms, whereas public key algorithms provide inherent separation of roles and easier key management. Envelope encryption combines the strengths of each strategy.

Envelope Encryption in AWS

1. Create a Customer Master Key in KMS. Even though a CMK can be used to encrypt data up to 4K in size, it is primarily used to encrypt/decrypt data encryption keys.

2. Generate a Data Encryption Key - Used to encrypt data by using symmetric encryption algorithms.

3. Encrypt the data key by using the CMK.

4. Store encrypted data and encrypted data key together.

When a user calls kms:GenerateDataKey, KMS generates a data key, encrypts it with the CMK and finally returns plaintext and encrypted data key pair back (steps 2 & 3 above).

The user is responsible for managing these keys. Plaintext data key is usually discarded immediately after encrypting data, whereas encrypted data key is stored together with encrypted data. Data encryption key must be decrypted by using kms:decrypt before decrypting data.

Answer 2

I'm not familiar with permission itself, but I found this in the documentation:

From Using Key Policies in AWS KMS - AWS Key Management Service:

kms:GenerateDataKey* – Allows key users to successfully request data encryption keys (data keys) to use for client-side encryption. Key users can choose to receive two copies of the data key—one in plaintext form and one that is encrypted with this CMK—or to receive only the encrypted form of the data key.

Answer 3

Why do we need it?

AWS KMS keys can be used to encrypt data only up to a size of 4 KB (4096 bytes). In order to encrypt data of size greater than 4 kb in size, a method called, Envelope Encryption is used, which is not specific to AWS.

Should I encrypt application data up to 4 KB in size with AWS KMS keys?

No, you should not. Even though application data up to 4 KB in size can be encrypted with AWS KMS keys, it is not designed to encrypt application data. You can check Encrypting and decrypting data keys for more details.

How does envelope encryption/decryption work?

You request AWS to generate data keys (encrypted and plain text) by providing your KMS key ID e.g. the following CLI command

aws kms generate-data-key --key-id your_kms_key_id_here --key-spec AES_256

will return something like

{
"CiphertextBlob":
"RkIBAHgMxXGERpLXTIIM54OPUp/dXeRYW2ALjX6EVz3skLXeBwG6AEIFFTyHrw6EXSuZxf7gAAAAfjB8Bgkqhk
iG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeDglghkgBZQMEAS4wEQQMqsMiCfXkoxHsHbxfAgEQgDunMIdAh
gNqLaI6QtKnw5UrqQhrPezpLSE0fvkUD4yVpkJp1594C8DV6wBohptgrmSVA8B16xU9VK+cWA==",

"Plaintext": "p7hbvvuIm0Bg2ZMNpXPWqZq5cKjv1bPj23HYA4d/syM=",

"KeyId":
"arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}

Now, you use the Plaintext value to encrypt your data and store your encrypted data along with the CiphertextBlob value. Subsequently, you delete the Plaintext value.

To decrypt the data: You request AWS to return a Plaintext value by providing it with your KMS key ID and the CiphertextBlob value that you have stored with the encrypted data. You use the returned Plaintext value to decrypt your encrypted data.

Notes:

1. Encryption and decryption are done with a Plaintext value, not with a CiphertextBlob value.
2. A general practice is to use an alias of a key instead of the key itself i.e. you should replace your_kms_key_id_here with an alias. Check this to learn more about alias.
3. Check this to learn more about a data key.