What is the difference between generatorKeyId and keyIds?

[MrsBookik]

Security issue notifications

no.

Problem:

Given official example code there are two different key concepts given that I am confused about:

const keyring = new KmsKeyringNode({ generatorKeyId, keyIds });

const { encrypt, decrypt } = buildClient(CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT);
const { result } = await encrypt(keyring, cleartext, { encryptionContext: context });
const { plaintext, messageHeader } = await decrypt(keyring, result);

In order to make encrypt and even decrypt work using KMS, I had to provide a generatorKeyId and second key that I have put into keyIds.
Without the second Key, no decryption will happen and it will raise exception stating

unencryptedDataKey has not been set

Solution:

What is the purpose of each on both keys and why do we need both together?

Out of scope:

.

[alex-chew]

Hi @MrsBookik, thanks for reaching out.

When encrypting, the AWS Encryption SDK first generates a data key
which is used to actually encrypt the plaintext.
The data key is then wrapped by one or more wrapping keys.

The "generator key" is the AWS KMS key that is used to generate the data key,
and it is also used as the first wrapping key.
If you specify additional keys (as keyIds),
then they are used as wrapping keys too.

See the Developer Guide for details: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/how-it-works.html

---

Keyrings used for encryption have different constraints than those used for decryption.
So you must take care to satisfy both constraints if you use one keyring for both types of operations.

1. Which keys are required?
   When encrypting using an AWS KMS keyring,
   the generatorKeyId is required, and additional keyIds are optional.
   When decrypting using an AWS KMS keyring,
   both generatorKeyId and keyIds are optional,
   so long as there is at least one specified key among them.
   So you can specify a generatorKeyId by itself,
   or you can specify one or more keyIds by itself,
   or you can specify both a generatorKeyId and any number of keyIds.

2. What kind of KMS key identifiers to use?
   When encrypting using an AWS KMS keyring,
   you can specify keys using any KMS key identifier:
   they can be key ARNs or key aliases.
   On the other hand, when decrypting using an AWS KMS keyring,
   you can only specify keys using key ARNs.

In summary, if you want to use a single keyring for both encryption and decryption,
then you should:

• set the generatorKeyId to the desired KMS key's ARN
• if setting additional keyIds, then specify the KMS keys by their ARNs

[alex-chew]

I'm going to go ahead and close this out, but please feel free to re-open it or open a new issue if you have any further questions or concerns.