awslabs / aws-encryption-sdk-specification

AWS Encryption SDK Specification
Other
30 stars 27 forks source link

doc: add change doc to specify max plaintext length input on encrypt #138

Closed lavaleri closed 4 years ago

lavaleri commented 4 years ago

Issue #, if available: Related to #102 and #71

Description of changes: Add change document to describe spec update for specifying the input on Encrypt that puts a bound on the length of the input plaintext.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

lavaleri commented 4 years ago

After discussion with @seebees offline, we determined that it either makes sense to interpret max plaintext size on both Encrypt and GetEncryptionMaterials as the same control, and the control on Encrypt representing a passthrough that must also be available to known-length plaintexts (and thus we should pass the user intent to the CMM)

OR

This is a control that MUST only be considered for unknown-length plaintexts, in which case, how an implementation handles funneling user intent into that valid set of inputs for Encrypt depends on the language. We shouldn't thus say that all implementations MUST fail if given a known-length plaintext with a plaintext length bound less than the real length. Instead, we describe the only use case in which using plaintext length bound is valid within the context of Encrypt.

I have gone for the latter and updated the language in this doc to reflect that change, and scope the discussion to the Encrypt operation.

Additionally, for this discussion the Guide v. Reference level discussion was confusing given that it is mostly talking about changing the spec. Since i didn't find discussing the changes on these two levels useful, I'm considering the Reference level discussion casual enough to be the Guide level discussion. If you think there are better ways to go about this, let me know.

mattsb42-aws commented 4 years ago

I like the intention of this change. I still find it confusing that we have two similar but subtly different controls with two similar but subtly different names, but I won't block on that.