Example code for generateDataKey

[monscamus]

Hi, I've been using the SDK and I can encrypt and decrypt in javascript but now I'd like to generateDataKey(s) for each of my departments - there doesn't seem to be an example and following the same style doesn't seem to work. I've tried following some of the code I found in one of the Mocha tests but it appears to use a helper? Any chance of adding an example or extending the current encrypt-browser example?

The code below is an example of what I think should work but throws "generateDataKey is not a function".

       const { encrypt, generateDataKey } = buildClient(
            CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
        );
        let clientProvider = getClient(KMS, { credentials: this.creds });

        let params = {
            "KeyId": this.generatorKeyId,
            "EncryptionContext": {"department": "test"},
            "NumberOfBytes": 256,
            "KeySpec": AES_256,
            "Client": clientProvider
        }

        let dek = await generateDataKey(params);

[monscamus]

Ok, a little more research and reading the Typescript code has raised a few questions:

I can generate data keys server side through the API or cli.

aws kms generate-data-key --key-id arn:aws:kms:eu-west-2:889888777888:alias/Test --key-spec AES_256

which will give me the plaintext (which I can skip) and cyphertextblob. I'm guessing that the step from here is for me to store the cyphertext blob and return those to the user whenever they need to decrypt/encrypt. However the decrypt
--ciphertext-blob functionality doesn't appear to be in the javascript SDK, nor can I see how to say "here's another key that you need to decrypt against the KMS CMK". Is it that the SDK doesn't currently support that?

[monscamus]

In this TS test case I can see an EncryptedKey being generated out of a custom KeyRing and the ciphertext, is this possible from outside the package?

[https://github.com/aws/aws-encryption-sdk-javascript/blob/748be9e1799d999a350e9cafbf902d43aeab0aa5/modules/kms-keyring/test/kms_keyring.ondecrypt.test.ts]

[seebees]

I'm sorry, I'm not clear about what you are trying to do yet.

The AWS Encryption SDK(ESDK) uses keyrings to handle envelop encryption for you.
When you use the ESDKs encrypt it will call the the provided keyring/CMM for a data key.
Since it appears you want to work with AWS KMS,
the ESDK would call AWS KMS for you.
It would then use this data key to encrypt your plaintext.

Data key reuse is something to avoid :).
This is why the ESDK does not take a data key on encrypt or decrypt
but rather handle that negotiation for you with the keyrings and CMMs.

Perhaps if you flush out more what your larger goal is?

[monscamus]

Thanks seebees, I'll try and explain what I'm trying to achieve.

I want departments of a customer (e.g. Finance or HR) to be able to encrypt documents or data but never be able to decrypt the other departments data. Creating a CMK for each department is out of the question as we have lots of clients with lots of departments. I understand from https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys and other guides that the data encryption keys for these groups (DEKs) will be managed outside KMS (in our case within DynamoDb).

Google gives its best practise of key encrypted keys here (KEKs) https://cloud.google.com/kms/docs/envelope-encryption.

How do I add DEKs/KEKs to the AWS ESDK keyring?

[seebees]

Ah, I think I see.
The short answer is: You don't add DEKs/KEKs to the current AWS KMS keyring.
To accomplish something like this
you could use the RAW AES keyrings
and implement a key hierarchy.
This is probably more complicated than than you need,
but you are the best judge of your requirements :)
I do not suggest going down this road.

This is because you are securing
this separation of access through policy.
You only let each department have access
to the specific top level key stored in DDB
through some kind of policy control on the CMK.

Instead I would suggest that
you use policy conditions in AWS KMS
https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.html#conditions-kms

For your use case I think you could use encryption context
https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.html#conditions-kms-encryption-context
and then define policies for
"kms:EncryptionContext:department": "Finance" vs "kms:EncryptionContext:department": "HR".

This pushes the policy control down to the item level.
This gets you out of having to manage the keys in DDB.
It also lets you more easily change your access,
and you can apply even or granular controls
than by department...

[monscamus]

Thanks so much for the pointers - I've wangled a way to do the Raw AES Keyring (having generated DEKs server side for departments) but you're right there's a lot of inherent complexity to that approach.

I'll take a dive into Policy and EncryptionContext - could save me a LOT of work.

[seebees]

I hope it does.

Key hierarchies are complicated because they touch on key distribution, cryptographic limits, and key rotation.
If you must, you can use AWS KMS to help.
GenerateDataKeyPairWithoutPlaintext can help you generate the department keys that you are proposing storing in DDB (I think).
Also remember that anyone who can decrypt this key
will have access to everything encrypted under the department.

Last plug for the AWS KMS policy solution: Audit.
This gives you the ability to see who and when
each element of you encrypted data is being touched.
It is an oft overlooked element of rolling your own key hierarchy.