awslabs / awslabs/aws-encryption-sdk-specification

Generalize "Encrypted Data Key" term

Open
#158 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
37
Forks
27
PR merge metrics
No merged PRs in 30d

Description

The message header format defines the primary artifact that OnEncrypt produced as "Encrypted Data Keys". Not all encryption schemes will need to literally create only multiple encrypted copies of the plaintext data key, however. The binary format does not actually use these terms directly, so we have the opportunity to adjust these names without breaking backwards compatibility; we only have to update our documentation to refer to these existing fields with new names.

I would propose renaming "Encrypted Data Keys" to "Encryption Artifacts", but open to other suggestions.

The specification itself currently allows that the current naming is overly prescriptive:

"Note: "Encrypted" is a misnomer here, as the process by which a key provider may obtain the plaintext data key from the ciphertext and vice versa does not have to be an encryption and decryption cipher. This specification uses the terms "encrypt" and "decrypt" for simplicity, but the actual process by which a key provider obtains the plaintext data key from the ciphertext and vice versa MAY be any reversible operation, though we expect that most will use encryption."

(https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/structures.md#structure)

We should consider generalizing this language a bit further to allow the possibility of recovering the plaintext through operations that require multiple encryption artifacts, as in Shamir's Secret Sharing scheme for example: https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing.

Note that the specification labels the actual binary data inside an Encrypted Data Key as "Ciphertext", whereas the developer guide confusingly uses "Encryption Data Key" for this as well. The latter should probably be changed to "Ciphertext" as well, independently of whether we rename the enclosing concept.

Contributor guide

Open the contributing guide

Research direction

Read the Structure section in structures.md and the developer guide references to "Encrypted Data Keys" and "Encryption Data Key". Resolve the terminology for reversible operations and multiple artifacts, then update the specification and guide consistently; done means the enclosing concept and its binary contents use distinct, agreed names.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, security
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.