feat(branch-keys): add hv-2 spec #297
Conversation
framework/branch-key-store.md
Outdated
| - `DestinationEncryptionContext` MUST be the [encryption context](#encryption-context) of the EncryptedHierarchicalKey to be authenticated | ||
| - `DestinationEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above | ||
|
|
||
| #### Authenticating a Keystore item for item with `hierarchy-version` v2 |
There was a problem hiding this comment.
Nit: Branch Key Store item.
There are many Key Stores in the world.
Ours is the Branch Key Store.
There was a problem hiding this comment.
Updated it as Authenticating a Branch Keystore item for item with hierarchy-version v(1/2)
|
|
||
| If the `hierarchy-version` is v1, Beacon Encryption Context is same as [Beacon Key Branch Key Context](#beacon-key-branch-key-context) | ||
|
|
||
| ### Custom Encryption Context |
There was a problem hiding this comment.
Nit: I am not sure we need "Custom Encryption Context".
There was a problem hiding this comment.
This is mentioned in many places. There should be a variation of EC that we can point at saying this is the key value pair what customer has send for which we added the prefix.
There was a problem hiding this comment.
But, I removed "Custom branch key context"
framework/branch-key-store.md
Outdated
| The operation MUST call [AWS KMS API Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) | ||
| with a request constructed as follows: | ||
|
|
||
| - `Plaintext` **beacon plain-text tuple** |
There was a problem hiding this comment.
resolved at 757de04
framework/branch-key-store.md
Outdated
| the operation MUST use the Encrypt result `CiphertextBlob` | ||
| as the wrapped `ACTIVE` Branch Key. | ||
|
|
||
| #### Writing Branch Key and Beacon Key to Keystore |
There was a problem hiding this comment.
resolved at 757de04
framework/branch-key-store.md
Outdated
| If the `hierarchy-version` is v1, AWS KMS encryption context MUST be same as [branch key context](#branch-key-context). | ||
| If the `hierarchy-version` is v2, AWS KMS encryption context MUST be the [encryption context](../structures.md#encryption-context) send by users without any transformation. | ||
|
|
||
| AWS KMS encryption context MUST be always the same encryption context send by user regardless of any variation of encryption context (i.e.: ACTIVE Encryption Context, DECRYPT_ONLY Encryption Context, Beacon Key Encryption Context and Custom Encryption Context). |
There was a problem hiding this comment.
This line reads funny. I think I understand what we are trying to say.
But I think we need to clean it up.
There was a problem hiding this comment.
I rephrase it to
"""
If the hierarchy-version is v2, the encryption context send to AWS KMS MUST always match the encryption context originally sent by the user, without any variations. This requirement applies regardless of the type of encryption context being used, whether it is the ACTIVE encryption context, the DECRYPT_ONLY encryption context, the Beacon Key encryption context, or a custom encryption context.
"""
lmk if you have any suggestion
Co-authored-by: Tony Knapp <[email protected]>
Co-authored-by: Tony Knapp <[email protected]>
|
Moved to work in progress PR to go through the spec one more time tomorrow. |
| These values are determined by the Branch Key Creator | ||
| or last Branch Key Mutator. | ||
|
|
||
| In DynamoDB and in KMS Encryption Requests, |
There was a problem hiding this comment.
| In DynamoDB and in KMS Encryption Requests, | |
| In DynamoDB and in KMS Encryption Requests for HV-1, |
|
|
||
| # Background | ||
|
|
||
| The current Branch Key Store's Branch Key's use KMS Encryption Context |
There was a problem hiding this comment.
| The current Branch Key Store's Branch Key's use KMS Encryption Context | |
| The current Branch Key Store's Branch Keys use KMS Encryption Context |
| Finally, | ||
| some of the users have insisted that | ||
| Crypto Tools refactor the KMS Encryption Context | ||
| to only be the Branch Key's Encryption Context. |
There was a problem hiding this comment.
Suggestion: Remove; this made sense in private, when I was trying to sell HV-2, but now we have sold HV-2, and do not need this sentence.
| Finally, | |
| some of the users have insisted that | |
| Crypto Tools refactor the KMS Encryption Context | |
| to only be the Branch Key's Encryption Context. |
| The MetaStore was the predecessor to the Branch Key Store; it is the "caching" solution for the legacy DynamoDB Encryption Client (DDBEC). The MetaStore used the DDBEC itself to protect the hierarchical material with KMS. | ||
|
|
||
| Which affords for some flexibility, as the MetaStore was an interface. |
There was a problem hiding this comment.
| The MetaStore was the predecessor to the Branch Key Store; it is the "caching" solution for the legacy DynamoDB Encryption Client (DDBEC). The MetaStore used the DDBEC itself to protect the hierarchical material with KMS. | |
| Which affords for some flexibility, as the MetaStore was an interface. | |
| The MetaStore was the predecessor to the Branch Key Store; | |
| it is the "caching" solution for the legacy DynamoDB Encryption Client (DDBEC). | |
| The MetaStore used the DDBEC itself to protect the hierarchical material with KMS; | |
| this affords for some flexibility, | |
| as the MetaStore was an interface that exposes the full breadth of DDBEC functionality. | |
| This gives customers significant freedom on what data is bound to a Branch Key Item's material and how that binding is facilitated. |
| While such a feature MAY provide the greatest flexibility to | ||
| our customers, | ||
| it is not a simplification of the Hierarchy Keyring, | ||
| but a complication to it. |
There was a problem hiding this comment.
| While such a feature MAY provide the greatest flexibility to | |
| our customers, | |
| it is not a simplification of the Hierarchy Keyring, | |
| but a complication to it. | |
| While such a feature MAY provide the greatest flexibility to | |
| our customers, | |
| it is not a simplification of the Hierarchy Keyring, | |
| but a complication to it. | |
| It also would make the DB-ESDK a dependency of the ESDK, | |
| and introduce a circular dependency between the MPL and the DB-ESDK. | |
|
|
||
| The DECRYPT_ONLY encryption context MUST NOT have a `version` attribute. | ||
| The DECRYPT_ONLY branch key context MUST NOT have a `version` attribute. |
There was a problem hiding this comment.
| The DECRYPT_ONLY branch key context MUST NOT have a `version` attribute. | |
| The DECRYPT_ONLY branch key context MUST NOT have a `version` key. |
|
|
||
| The DECRYPT_ONLY encryption context MUST NOT have a `version` attribute. | ||
| The DECRYPT_ONLY branch key context MUST NOT have a `version` attribute. | ||
| The `type` attribute MUST stores the branch key version formatted like `"branch:version:"` + `version`. |
There was a problem hiding this comment.
| The `type` attribute MUST stores the branch key version formatted like `"branch:version:"` + `version`. | |
| The `type` value MUST store the branch key version formatted like `"branch:version:"` + `<version UUID>`. |
| ### Beacon Key Encryption Context | ||
| ### Beacon Branch Key Context | ||
|
|
||
| In addition to the [branch key context](#encryption-context): |
There was a problem hiding this comment.
| In addition to the [branch key context](#encryption-context): | |
| In addition to the [branch key context](#branch-key-context): |
| In addition to the [branch key context](#encryption-context): | ||
|
|
||
| The Beacon key branch key context MUST includes a key `type` and the value MUST be `"beacon:ACTIVE"`. | ||
| The Beacon key branch key context MUST NOT have a `version` attribute. |
There was a problem hiding this comment.
| The Beacon key branch key context MUST NOT have a `version` attribute. | |
| The Beacon key branch key context MUST NOT have a `version` key. |
| If the `hierarchy-version` is v1, AWS KMS encryption context MUST be same as [branch key context](#branch-key-context). | ||
| If the `hierarchy-version` is v2, AWS KMS encryption context MUST be the [encryption context](../structures.md#encryption-context) send by users without any transformation. | ||
|
|
||
| If the `hierarchy-version` is v2, the encryption context send to AWS KMS MUST always match the encryption context originally sent by the user, without any variations. This requirement applies regardless of the type of encryption context being used, whether it is the ACTIVE encryption context, the DECRYPT_ONLY encryption context, the Beacon Key encryption context, or a custom encryption context. |
There was a problem hiding this comment.
This needs to be revised.
Issue #, if available:
Description of changes:
Crypto tools is adding a new feature (Hierarchical Keyring V2) in MPL main branch. This PR adds the specification for it.
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.
Check any applicable: