Document behavior for conflicting contexts

[benkehoe]

Messages encrypted with version <4* include the encryption context in the header, and messages encrypted with version 4 omit it**, expecting the context to be provided again on decrypt. The old messages can be decrypted by version 4, but I do not see documentation about what happens if context is provided at decryption (like for a new message) but an old message is given and the two contexts do or don't match. I'd like to see those details included in the SDK documentation.

* Version 4 of the Python SDK. Version 3 of the Java SDK? The AWS docs about the language SDK versions is not very helpful in understanding compatibility for this new change (and many other pages in the developer guide do not mention it, for example the best practices page talks about the context being included in the message).

** In the changelog, the omission of the context seems to be linked to the MPL, but that is an optional dependency. My guess is that maybe if I use the MasterKeyProvider, maybe it's still included? But I cannot find documentation of this. The developer guide page on keyrings describes their involvement with keys but does not mention context.

[lucasmcdonald3]

Hi @benkehoe,

Messages encrypted with version <4* include the encryption context in the header, and messages encrypted with version 4 omit it**

This statement is inaccurate. Encryption context may only be omitted if you are using the required encryption context CMM.
Messages encrypted with v4 will only omit specified configured encryption context pairs if encrypting with the required encryption context CMM.
Messages encrypted with v4 and the default CMM will continue to include the full encryption context in the message header, as in versions <4.
See the 4.0.0 release notes for more information.

The old messages can be decrypted by version 4, but I do not see documentation about what happens if context is provided at decryption (like for a new message) but an old message is given and the two contexts do or don't match. I'd like to see those details included in the SDK documentation.

You can find more information on the behavior of the required encryption context CMM in our documentation.

Version 4 of the Python SDK. Version 3 of the Java SDK? The AWS docs about the language SDK versions is not very helpful in understanding compatibility for this new change (and many other pages in the developer guide do not mention it, for example the best practices page talks about the context being included in the message).

You can find the version compatibility information here. Again, encryption context may only be omitted only if you're using the required encryption context CMM.

In the changelog, the omission of the context seems to be linked to the MPL, but that is an optional dependency. My guess is that maybe if I use the MasterKeyProvider, maybe it's still included? But I cannot find documentation of this. The developer guide page on keyrings describes their involvement with keys but does not mention context.

Encryption context will be included in the message with both MasterKeyProviders and Keyrings if used with the default CMM. It may only be omitted from the message if you're using the required encryption context CMM.

For more information, check out these code examples:

• https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/default_cryptographic_materials_manager_example.py
• https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/required_encryption_context_cmm.py

[benkehoe]

This is my point. The language in the release notes "will omit specific configured context pairs", when I read it originally, did not make me realize it's only the required keys that are omitted. The dev guide's language "Only the key-value pairs that are not required keys are serialized..." was much clearer. The brevity in the release notes was the source of my confusion about this being an SDK behavior versus an opt-in behavior when using a specific CMM, and it doesn't link to any further explanation in the dev guide (while there's a page on keyrings, there's no page on materials managers). The version compatibility information you refer to is halfway down the "configuring the SDK" page, not in the "versions of the SDK" page, why would I know to look there for it? Information in the release notes is great for understanding what's changed between releases, but shouldn't have to be read to understand the current state. The readme on this repo states "The latest full documentation can be found at Read the Docs." but all of the detailed information you referenced is on the developer guide and not in or referenced on the Read the Docs site. The "best practices" page in the dev guide still says "When decrypting, the AWS Encryption SDK uses the encryption context in the header of the encrypted message that the AWS Encryption SDK returns." I acknowledge that much of the information exists somewhere in the documentation but finding it (and not being led astray by information that has not been updated to reflect this new option) is a real headache.

My original question stands about required contexts. The information in the "configuring the SDK" states:

On decrypt, you must provide an encryption context that contains all of the key-value pairs that represent the required keys. The AWS Encryption SDK uses this encryption context and the key-value pairs stored in the encrypted message’s header to reconstruct the original encryption context that you specified in the encrypt operation. If the AWS Encryption SDK cannot reconstruct the original encryption context, then the decrypt operation fails. If you provide a key-value pair that contains the required key with an incorrect value, the encrypted message cannot be decrypted. You must provide the same key-value pair that was specified on encrypt.

I believe the meaning here is that even if the required keys are in the header, you still have to provide them separately on decrypt, but I'm not 100% sure. What it doesn't say is, what happens if I provide key-value pairs (required or not) on decrypt that are already in the header? Is it an upfront error if they don't match, or does one silently override the other?

[lucasmcdonald3]

Hi @benkehoe -- sorry for the confusion. We'll update the changelog notes for v4.0.0 to link to the AWS documentation for the required EC CMM.

I believe the meaning here is that even if the required keys are in the header, you still have to provide them separately on decrypt, but I'm not 100% sure. What it doesn't say is, what happens if I provide key-value pairs (required or not) on decrypt that are already in the header? Is it an upfront error if they don't match, or does one silently override the other?

Any key-value pairs you provide on decrypt must match what you provided on encrypt.
You must provide any required keys when decrypting. You don't need to provide non-required keys.