define how keyring trace manifests in the ESDK client interface and how users should interact with it

[mattsb42-aws]

We have broadly defined what the keyring trace is and what it can contain[1], and that it is included in encryption materials and decryption materials[2], but we have not defined how it is presented to the caller other than stating that it MAY be included in the encrypt[3] output (though we appear to have missed mentioning it in the decrypt output). We expose the trace in C[4][5], Java[6], and Python[7], but we do not appear to have exposed it in Javascript.

We also have not defined a consistent behavior for how keyrings should add entries. For example, if a keyring both generates a data key and encrypts it, should that result in a single entry or two?

Even where we have exposed it, however, we have not defined how we intend callers to interact with it. The trace is a list of entries; if I have received this from a client, what should I do with it in order to audit the trace entries? How to I connect a trace entry to a keyring or to a specific wrapping key?

[1] https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/structures.md#keyring-trace-2
[2] https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/structures.md#keyring-trace
[3] https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/client-apis/encrypt.md#keyring-trace
[4] https://github.com/aws/aws-encryption-sdk-c/blob/749c84feddce147fb62e2ece7de34d733ef165c2/source/session_encrypt.c#L82
[5] https://github.com/aws/aws-encryption-sdk-c/blob/749c84feddce147fb62e2ece7de34d733ef165c2/source/session_decrypt.c#L118
[6] https://github.com/aws/aws-encryption-sdk-java/blob/997e80b97a33351d693f49d35b1d1e8b24da17d7/src/main/java/com/amazonaws/encryptionsdk/AwsCryptoResult.java#L60-L67
[7] https://github.com/aws/aws-encryption-sdk-python/blob/6ffc135dbecd5c63277e13d1702a7c44ca2bb3c0/src/aws_encryption_sdk/structures.py#L203

[mattsb42-aws]

related to #78

[mattsb42-aws]

Additional thought that might need to break off into a separate issue:

Should the key namespace and name in the trace be the configured values or the serialized values?

ex:

• The raw AES keyring adds data to the key name before serializing it.
• The AWS KMS keyring serializes the CMK ARN in the response from KMS, not the key ID that it was configured with (and that was sent to KMS in the request).

I would argue that the trace value should be the configured value, not the serialized value, so that the user can reference the trace entries vs the keyrings that they used.

[seebees]

Counterpoint, if it is the configured ID and not the KMS ID, then it will not match what is serialized and will not match what is in the trace on Decrypt.

[mattsb42-aws]

Counterpoint, if it is the configured ID and not the KMS ID, then it will not match what is serialized and will not match what is in the trace on Decrypt.

True. Maybe we need to have both? My thinking is mainly: what do we intend people to actually do with the trace? I can look at the EDKs and see the CMK ARNs; we I can't necessarily tell from that is which ID that I configured caused that to happen. If I'm referencing the CMKs by, say, aliases, and I want to check that the CMK I intended was used to generate the data key, then I need to be able to check against the value I I'm referencing (the alias).

[WesleyRosenblum]

Recording an earlier suggestion from @mattsb42-aws here: "if we could add an optional “additional information” field to each trace entry and put the provider info as the main identifier and the configured key name in additional information, that would probably be ideal"