Support for other algorithms (other than AES/GCM/NoPadding) when using JceMasterKey about aws-encryption-sdk-java

[mattsb42-aws]

AES/GCM/NoPadding is the only symmetric encryption mode that JceMasterKey supports. Let me explain.

We have a much more detailed write up of the AWS Encryption SDK approach here[1]. I'll summarize the high points briefly here, but if you're interested in the details I would highly recommend going through the more detailed docs.

The AWS Encryption SDK is an approach to envelope encryption: your actual plaintext is encrypted by a data key and that data key is protected by a master key. Using the cryptographic materials managers, master key providers, and master keys that we provide, the standard behavior is that every plaintext message has a unique data key (generated by a master key). That data key is then encrypted by each master key that you configure.

In other words: the only thing that the JceMasterKey ever encrypts is data keys: 32 bytes per plaintext message.

Internally to the AWS Encryption SDK, we then use that data key to protect the plaintext. If you are using a KDF algorithm suite[2] (the default), we additionally use HKDF to derive a unique encryption key from the data key. Because of this, even if you do reuse data keys across messages[3], the actual key that we use to encrypt your plaintext is unique per message. This is why the provided data key caching resources do not allow data key reuse when using non-KDF algorithm suites. We do not recommend using the non-KDF algorithm suites: they are provided for legacy compatibility.

When we encrypt the message, we encrypt the plaintext in frames[4] and use a unique IV and GCM AAD for each frame.

You are correct that there are limits to the amount of data that can safely be encrypted using a single key with AES GCM. However, this limit is actually based on the combination of a unique key and IV pair. To protect against the key-IV pair ever being reused, we use deterministic IVs[5] when encrypting the frames. The same encryption key is used to encrypt all frames in a message, but using deterministic IVs guarantees that no two frames in a single message will have the same key-IV pair.

You can encrypt up to 2GiB per frame (frame size is configurable by the caller) and you can include up to ~4 billion (2^32 - 1) frames per message. This allows you to safely encrypt up to ~8EiB of data per message.

We recommend only using a single master key material for up to about a billion encryption operations. In the context of a master key, that translates to one encryption operation per message. If you are using JceMasterKey, you will need to manage that master key and any rotation yourself. In most cases you would probably want to rotate your master key material more frequently than every billion operations in order to reduce the blast radius of any single master key material.

[1] https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html
[2] https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/algorithms-reference.html
[3] https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/data-key-caching.html
[4] https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/message-format.html#body-framing
[5] https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/IV-reference.html

[ngbalk]

Wow, thanks you @mattsb42-aws this is a great explanation. Closing this issue.