From 8db68554ef9075c7f0af0bdd0f6b573d99178c6f Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Wed, 25 Jun 2025 10:19:31 -0700 Subject: [PATCH 001/116] CreateKeyInput changes --- framework/branch-key-store.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 7f3c272e..fc176be3 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -337,6 +337,7 @@ The CreateKey caller MUST provide: - An optional branch key id - An optional encryption context +- An optional hierarchy version If an optional branch key id is provided and no encryption context is provided this operation MUST fail. @@ -348,6 +349,9 @@ If no branch key id is provided, then this operation MUST create a [version 4 UUID](https://www.ietf.org/rfc/rfc4122.txt) to be used as the branch key id. +If no hierarchy version is provided, +then hierarchy version MUST default to 1 + This operation MUST create a [branch key](structures.md#branch-key) and a [beacon key](structures.md#beacon-key) according to the [Branch Key and Beacon Key Creation](#branch-key-and-beacon-key-creation) section. From 464271c72f545ec3f2c5f0538fcd68efdc3766a8 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Wed, 25 Jun 2025 10:34:29 -0700 Subject: [PATCH 002/116] Update branch-key-store.md --- framework/branch-key-store.md | 1 + 1 file changed, 1 insertion(+) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index fc176be3..0bad07d8 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -371,6 +371,7 @@ To create a branch key, this operation MUST take the following: - `branchKeyId`: The identifier - `encryptionContext`: Additional encryption context to bind to the created keys +- `hierarchy version`: Schema Version of the Branch Key. This operation needs to generate the following: From 5a46148ab1db27953db7ff2e766b7bb7ab2c203f Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 25 Jun 2025 11:07:57 -0700 Subject: [PATCH 003/116] auto commit --- framework/branch-key-store.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 0bad07d8..d5bdd80f 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -350,7 +350,10 @@ then this operation MUST create a [version 4 UUID](https://www.ietf.org/rfc/rfc4 to be used as the branch key id. If no hierarchy version is provided, -then hierarchy version MUST default to 1 +then hierarchy version MUST default to 1. + +If a hierarchy version is provided, +and is other then `1` or `2` then this operation MUST fail. This operation MUST create a [branch key](structures.md#branch-key) and a [beacon key](structures.md#beacon-key) according to the [Branch Key and Beacon Key Creation](#branch-key-and-beacon-key-creation) section. @@ -383,9 +386,10 @@ The wrapped Branch Keys, DECRYPT_ONLY and ACTIVE, MUST be created according to [ To create a beacon key, this operation will continue to use the `branchKeyId` and `timestamp` as the [Branch Key](structures.md#branch-key). -The operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html). -The call to AWS KMS GenerateDataKeyWithoutPlaintext MUST use the configured AWS KMS client to make the call. -The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: +If `hierarchy version` is 1, then the operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html). +If `hierarchy version` is 2, then the operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). +The call to AWS KMS GenerateDataKeyWithoutPlaintext or GenerateDataKey MUST use the configured AWS KMS client to make the call. +The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext or GenerateDataKey with a request constructed as follows: - `KeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `NumberOfBytes` MUST be 32. From 1ce8bf09fd6f7d5138a8d36fcc307a14bb4b7d84 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 25 Jun 2025 13:34:41 -0700 Subject: [PATCH 004/116] bkc --- framework/branch-key-store.md | 67 +++++++++++++++++++---------------- 1 file changed, 37 insertions(+), 30 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index d5bdd80f..dc5fc5bc 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -388,7 +388,7 @@ To create a beacon key, this operation will continue to use the `branchKeyId` an If `hierarchy version` is 1, then the operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html). If `hierarchy version` is 2, then the operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). -The call to AWS KMS GenerateDataKeyWithoutPlaintext or GenerateDataKey MUST use the configured AWS KMS client to make the call. +The call to AWS KMS GenerateDataKeyWithoutPlaintext and GenerateDataKey MUST use the configured AWS KMS client to make the call. The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext or GenerateDataKey with a request constructed as follows: - `KeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. @@ -396,16 +396,20 @@ The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext or GenerateDataK - `EncryptionContext` MUST be the [encryption context for beacon keys](#beacon-key-encryption-context). - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -If the call to AWS KMS GenerateDataKeyWithoutPlaintext succeeds, +When `hierarchy version` is 1 and the call to AWS KMS GenerateDataKeyWithoutPlaintext succeeds, the operation MUST use the `CiphertextBlob` as the wrapped Beacon Key. +When `hierarchy version` is 2 and the call to AWS KMS GenerateDataKey succeeds, +the operation MUST use the `Plaintext` as the Beacon Key. This `Plaintext` is wrapped along with branch key context following [Wrapped Plain Text Tuple Creation](#wrapped-Plain-text-tuple-creation). + #### Wrapped Branch Key Creation -Given a `branchKeyId`, `version` and `timestamp` +Given a `branchKeyId`, `version`, `timestamp` and `hierarchy version` -The operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html). -The call to AWS KMS GenerateDataKeyWithoutPlaintext MUST use the configured AWS KMS client to make the call. -The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: +If `hierarchy version` is 1, the operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html). +If `hierarchy version` is 2, then the operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). +The call to AWS KMS GenerateDataKeyWithoutPlaintext and GenerateDataKey MUST use the configured AWS KMS client to make the call. +The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext and GenerateDataKey with a request constructed as follows: - `KeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `NumberOfBytes` MUST be 32. @@ -570,12 +574,12 @@ and the `branchKeyId` from the returned `branch-key-id` field. This operation MUST return the constructed [beacon key materials](./structures.md#beacon-key-materials). -## Encryption Context +## Branch Key Context -This section describes how the AWS KMS encryption context is built -from an [encrypted hierarchical key](./key-store/key-storage.md#encryptedhierarchicalkey). +Branch Key Context is a key value pair that can contain additional contextual information about the data. +This section describes how Branch Key Context is built from an [encrypted hierarchical key](./key-store/key-storage.md#encryptedhierarchicalkey). -The following encryption context keys are shared: +The following branch key context keys are shared: - MUST have a `branch-key-id` attribute - The `branch-key-id` field MUST not be an empty string @@ -587,42 +591,45 @@ The following encryption context keys are shared: - MUST have a `hierarchy-version` - MUST NOT have a `enc` attribute -Any additionally attributes in the EncryptionContext -of the [encrypted hierarchical key](./key-store/key-storage.md#encryptedhierarchicalkey) -MUST be added to the encryption context. - -### ACTIVE Encryption Context +### ACTIVE Branch Key Context The ACTIVE branch key is a copy of the DECRYPT_ONLY with the same `version`. It is structured slightly differently so that the active version can be accessed quickly. -In addition to the [encryption context](#encryption-context): +In addition to the [branch key context](#encryption-context): -The ACTIVE encryption context value of the `type` attribute MUST equal to `"branch:ACTIVE"`. -The ACTIVE encryption context MUST have a `version` attribute. +The ACTIVE branch key context value of the `type` attribute MUST equal to `"branch:ACTIVE"`. +The ACTIVE branch key context MUST have a `version` attribute. The `version` attribute MUST store the branch key version formatted like `"branch:version:"` + `version`. -### DECRYPT_ONLY Encryption Context +### DECRYPT_ONLY Branch Key Context -In addition to the [encryption context](#encryption-context): +In addition to the [branch key context](#encryption-context): -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`. -### Beacon Key Encryption Context +### Beacon Key Branch Key Context -In addition to the [encryption context](#encryption-context): +In addition to the [branch key context](#encryption-context): -The Beacon key encryption context value of the `type` attribute MUST equal to `"beacon:ACTIVE"`. -The Beacon key encryption context MUST NOT have a `version` attribute. +The Beacon key branch key context value of the `type` attribute MUST equal to `"beacon:ACTIVE"`. +The Beacon key branch key context MUST NOT have a `version` attribute. -### Custom Encryption Context +### Custom Branch Key Context -If custom [encryption context](./structures.md#encryption-context-3) -is associated with the branch key these values MUST be added to the AWS KMS encryption context. -To avoid name collisions each added attribute from the custom [encryption context](./structures.md#encryption-context-3) +If custom [branch key context](./structures.md#encryption-context-3) +is associated with the branch key these values MUST be added to the AWS KMS branch key context. +To avoid name collisions each added attribute from the custom [branch key context](./structures.md#encryption-context-3) MUST be prefixed with `aws-crypto-ec:`. -Across all versions of a Branch Key, the custom encryption context MUST be equal. +Across all versions of a Branch Key, the custom branch key context MUST be equal. + +## Encryption Context + +This section describes how the AWS KMS encryption context is built. + +If the `hierarchy-version` is 1, AWS KMS encryption context MUST be same as [branch key context](#branch-key-context). +If the `hierarchy-version` is 2, AWS KMS encryption context MUST be the [encryption context](../structures.md#encryption-context) send by users without any transformation. ## AWS KMS Branch Key Decryption From 3ebc88607f33d3b2fed36ee92fb66fd1c4cd0b4e Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 25 Jun 2025 17:03:10 -0700 Subject: [PATCH 005/116] auto commit --- framework/branch-key-store.md | 247 ++++++++++++++++++++++++++++++---- 1 file changed, 218 insertions(+), 29 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index dc5fc5bc..a8cc74fd 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -60,6 +60,17 @@ This Keystore interface defines operations that any implementation of its specif A root key used to then derive different beacon keys per beacon. - [UUID](https://www.ietf.org/rfc/rfc4122.txt): a universally unique identifier that can be represented as a byte sequence or a string. +#### Hierarchy Version + +Schema Version of the Branch Key. +All items of the same Branch Key Identifier SHOULD have the same hierarchy-version. +The hierarchy-version determines how the Branch Key Store protects and validates the branch key with KMS. + +There are two hierarchy versions: + +- v1 +- v2 + ### Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" @@ -337,7 +348,7 @@ The CreateKey caller MUST provide: - An optional branch key id - An optional encryption context -- An optional hierarchy version +- An optional Hierarchy-Version If an optional branch key id is provided and no encryption context is provided this operation MUST fail. @@ -349,18 +360,20 @@ If no branch key id is provided, then this operation MUST create a [version 4 UUID](https://www.ietf.org/rfc/rfc4122.txt) to be used as the branch key id. -If no hierarchy version is provided, -then hierarchy version MUST default to 1. +If no Hierarchy-Version is provided, +the then this operation MUST use `v1`. -If a hierarchy version is provided, -and is other then `1` or `2` then this operation MUST fail. +This operation needs to generate the following: + +- `version`: a new guid. This guid MUST be [version 4 UUID](https://www.ietf.org/rfc/rfc4122.txt) +- `timestamp`: a timestamp for the current time. + This timestamp MUST be in ISO 8601 format in UTC, to microsecond precision (e.g. “YYYY-MM-DDTHH:mm:ss.ssssssZ“) This operation MUST create a [branch key](structures.md#branch-key) and a [beacon key](structures.md#beacon-key) according to the [Branch Key and Beacon Key Creation](#branch-key-and-beacon-key-creation) section. If creation of the keys are successful, -then the key store MUST call the configured [KeyStorage interface's](./key-store/key-storage.md#interface) -[WriteNewEncryptedBranchKey](./key-store/key-storage.md#writenewencryptedbranchkey) with these 3 [EncryptedHierarchicalKeys](./key-store/key-storage.md#encryptedhierarchicalkey). +the operation MUST call Amazon DynamoDB TransactWriteItems according to the [write key material](#writing-branch-key-and-beacon-key-to-keystore) section. If writing to the keystore succeeds, the operation MUST return the branch-key-id that maps to both @@ -374,47 +387,102 @@ To create a branch key, this operation MUST take the following: - `branchKeyId`: The identifier - `encryptionContext`: Additional encryption context to bind to the created keys -- `hierarchy version`: Schema Version of the Branch Key. - -This operation needs to generate the following: - +- `kms-arn`: The KMS-ARN determined by the KMS Configuration +- `hierarchy-version`: The hierarchy-version determined by the input - `version`: a new guid. This guid MUST be [version 4 UUID](https://www.ietf.org/rfc/rfc4122.txt) - `timestamp`: a timestamp for the current time. This timestamp MUST be in ISO 8601 format in UTC, to microsecond precision (e.g. “YYYY-MM-DDTHH:mm:ss.ssssssZ“) -The wrapped Branch Keys, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Branch Key Creation](#wrapped-branch-key-creation). +The wrapped Branch Key Items, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Branch Key Creation](#wrapped-branch-key-creation). + +If the `hierarchy-version` is `v1`, +the wrapped beacon key MUST be created according to [Wrapped Beacon Key Creation `v1`](#wrapped-beacon-key-creation-v1) and +the wrapped branch keys MUST be created according to +[Wrapped Branch Key Creation `v1`](#wrapped-branch-key-creation-v1); +else the `hierarchy-version` MUST be `v2`, +the wrapped beacon Key MUST be created according to [Wrapped Beacon Key Creation `v2`](#wrapped-beacon-key-creation-v2) and +the wrapped branch keys MUST be created according to +[Wrapped Branch Key Creation `v2`](#wrapped-branch-key-creation-v2),. + +##### Wrapped Beacon Key Creation `v1` To create a beacon key, this operation will continue to use the `branchKeyId` and `timestamp` as the [Branch Key](structures.md#branch-key). -If `hierarchy version` is 1, then the operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html). -If `hierarchy version` is 2, then the operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). -The call to AWS KMS GenerateDataKeyWithoutPlaintext and GenerateDataKey MUST use the configured AWS KMS client to make the call. -The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext or GenerateDataKey with a request constructed as follows: +The operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html). +The call to AWS KMS GenerateDataKeyWithoutPlaintext MUST use the configured AWS KMS client to make the call. +The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: - `KeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `NumberOfBytes` MUST be 32. - `EncryptionContext` MUST be the [encryption context for beacon keys](#beacon-key-encryption-context). - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -When `hierarchy version` is 1 and the call to AWS KMS GenerateDataKeyWithoutPlaintext succeeds, +If the call to AWS KMS GenerateDataKeyWithoutPlaintext succeeds, the operation MUST use the `CiphertextBlob` as the wrapped Beacon Key. -When `hierarchy version` is 2 and the call to AWS KMS GenerateDataKey succeeds, -the operation MUST use the `Plaintext` as the Beacon Key. This `Plaintext` is wrapped along with branch key context following [Wrapped Plain Text Tuple Creation](#wrapped-Plain-text-tuple-creation). +##### Wrapped Beacon Key Creation `v2` + +The operation MUST generate a Map of strings, +the [encryption context for beacon keys](#beacon-key-encryption-context), +using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. + +The operation MUST calculate the **SHA-384 Digest for the beacon key** +by [serializing](../structures.md#serialization) the [encryption context for beacon keys](#beacon-key-encryption-context); +the serialization MUST be done according to the [encryption context serialization specification](../structures.md#serialization). + +**Note**: The Encryption Context sent to KMS is NOT prefixed, but the Encryption Context included in the Digest is. + +The operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). +The call to AWS KMS GenerateDataKey MUST use the configured AWS KMS client to make the call. +The operation MUST call AWS KMS GenerateDataKey with a request constructed as follows: + +- `KeyId` MUST be the `kms-arn` +- `NumberOfBytes` MUST be 32. +- `EncryptionContext` MUST be the `encryption-context` +- `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). + +If the call to AWS KMS GenerateDataKey succeeds, +the operation MUST use the GenerateDataKey results `PlaintextBlob` +as the plain-text Beacon Key. + +The operation MUST concatenate the **SHA-384 Digest for the beacon key** +with the plain-text Beacon Key, +creating the **the beacon plain-text tuple**. + +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` **SHA-384 Digest for the beacon key** +- `KeyId` MUST be the `kms-arn`. +- `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). +- `EncryptionContext` MUST be the `encryption-context` + +If the call to AWS KMS Encrypt succeeds, +the operation MUST use the Encrypt result `CiphertextBlob` +as the wrapped Beacon Key. #### Wrapped Branch Key Creation -Given a `branchKeyId`, `version`, `timestamp` and `hierarchy version` +Given a `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. -If `hierarchy version` is 1, the operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html). -If `hierarchy version` is 2, then the operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). -The call to AWS KMS GenerateDataKeyWithoutPlaintext and GenerateDataKey MUST use the configured AWS KMS client to make the call. -The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext and GenerateDataKey with a request constructed as follows: +##### Wrapped Branch Key Creation `v1` -- `KeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. +The operation MUST generate a Map of strings, +the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context), +using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. + +The operation MUST generate a Map of strings, +the [ACTIVE encryption context for branch keys](#active-encryption-context) +using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. + +The operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html). +The call to AWS KMS GenerateDataKeyWithoutPlaintext MUST use the configured AWS KMS client to make the call. +The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: + +- `KeyId` MUST be the `kms-arn` - `NumberOfBytes` MUST be 32. - `EncryptionContext` MUST be the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context). -- GenerateDataKeyWithoutPlaintext `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). +- `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). If the call to AWS KMS GenerateDataKeyWithoutPlaintext succeeds, the operation MUST use the GenerateDataKeyWithoutPlaintext result `CiphertextBlob` @@ -424,16 +492,137 @@ The operation MUST call [AWS KMS API ReEncrypt](https://docs.aws.amazon.com/kms/ with a request constructed as follows: - `SourceEncryptionContext` MUST be the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context). -- `SourceKeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. +- `SourceKeyId` MUST be the `kms-arn`. - `CiphertextBlob` MUST be the wrapped DECRYPT_ONLY Branch Key. -- ReEncrypt `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -- `DestinationKeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. +- `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). +- `DestinationKeyId` MUST be the `kms-arn`. - `DestinationEncryptionContext` MUST be the [ACTIVE encryption context for branch keys](#active-encryption-context). If the call to AWS KMS ReEncrypt succeeds, the operation MUST use the ReEncrypt result `CiphertextBlob` as the wrapped ACTIVE Branch Key. +##### Wrapped Branch Key Creation `v2` + +The operation MUST generate a Map of strings, +the [`DECRYPT_ONLY` encryption context for branch keys](#decrypt_only-encryption-context), +using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. + +The operation MUST calculate the **SHA-384 Digest for the `DECRYPT_ONLY`** +by [serializing](../structures.md#serialization) the [`DECRYPT_ONLY` encryption context for branch keys](#decrypt_only-encryption-context); +the serialization MUST be done according to the [encryption context serialization specification](../structures.md#serialization). + +The operation MUST generate a Map of strings, +the [ACTIVE encryption context for branch keys](#active-encryption-context) +using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. + +The operation MUST calculate the **SHA-384 Digest for the `ACTIVE`** +by [serializing](../structures.md#serialization) the [`ACTIVE` encryption context for branch keys](#active-encryption-context); +the serialization MUST be done according to the [encryption context serialization specification](../structures.md#serialization). + +**Note**: The Encryption Context sent to KMS is NOT prefixed, but the Encryption Context included in the Digest is. + +The operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). +The call to AWS KMS GenerateDataKey MUST use the configured AWS KMS client to make the call. +The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: + +- `KeyId` MUST be the `kms-arn` +- `NumberOfBytes` MUST be 32. +- `EncryptionContext` MUST be the `encryption-context` +- `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). + +If the call to AWS KMS GenerateDataKey succeeds, +the operation MUST use the GenerateDataKey results `PlaintextBlob` +as the plain-text Branch Key. + +The operation MUST concatenate the **SHA-384 Digest for the `DECRYPT_ONLY`** +with the plain-text Branch Key, +creating the **the `DECRYPT_ONLY` plain-text tuple**. + +The operation MUST call [AWS KMS API Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) +with a request constructed as follows: + +- `Plaintext` **the `DECRYPT_ONLY` plain-text tuple** +- `KeyId` MUST be the `kms-arn`. +- `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). +- `EncryptionContext` MUST be the `encryption-context` + +If the call to AWS KMS Encrypt succeeds, +the operation MUST use the Encrypt result `CiphertextBlob` +as the wrapped `DECRYPT_ONLY` Branch Key. + +The operation MUST concatenate the **SHA-384 Digest for the `ACTIVE`** +with the plain-text Branch Key, +creating the **the `ACTIVE` plain-text tuple**. + +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` **the `ACTIVE` plain-text tuple** +- `KeyId` MUST be the `kms-arn`. +- `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). +- `EncryptionContext` MUST be the `encryption-context` + +If the call to AWS KMS Encrypt succeeds, +the operation MUST use the Encrypt result `CiphertextBlob` +as the wrapped `ACTIVE` Branch Key. + +#### Writing Branch Key and Beacon Key to Keystore + +To add the branch keys and a beacon key to the keystore the +operation MUST call [Amazon DynamoDB API TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html). + +**Note**: The Encryption Context sent to KMS is NOT prefixed, but the Encryption Context written to DynaomDB is. + +The call to Amazon DynamoDB TransactWriteItems MUST use the configured Amazon DynamoDB Client to make the call. +The operation MUST call Amazon DynamoDB TransactWriteItems with a request constructed as follows: + +List of TransactWriteItem: + +- PUT: + - Item: + - “branch-key-id” (S): `branchKeyId`, + - “type“ (S): "branch:version:" + `version`, + - “enc” (B): the wrapped DECRYPT_ONLY Branch Key `CiphertextBlob` from the KMS operation + - “create-time” (S): `timestamp` + - "kms-arn" (S): configured KMS Key + - “hierarchy-version” (N): either `1` or `2`, depending on the `hierarchy-version` + - Every key-value pair of the custom [encryption context](./structures.md#encryption-context-3) that is associated with the branch key + MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. + - ConditionExpression: `attribute_not_exists(branch-key-id)` + - TableName: the configured Table Name +- PUT: + - Item: + - “branch-key-id” (S): `branchKeyId`, + - “type“ (S): "branch:ACTIVE", + - “enc” (B): wrapped ACTIVE Branch Key `CiphertextBlob` from the KMS operation + - “create-time” (S): `timestamp` + - "kms-arn" (S): configured KMS Key + - “hierarchy-version” (N): either `1` or `2`, depending on the `hierarchy-version` + - Every key-value pair of the custom [encryption context](./structures.md#encryption-context-3) that is associated with the branch key + MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. + - ConditionExpression: `attribute_not_exists(branch-key-id)` + - TableName: the configured Table Name +- PUT: + - Item: + - “branch-key-id” (S): `branchKeyId`, + - “type“ (S): "beacon:ACTIVE", + - “enc” (B): the wrapped Beacon Key `CiphertextBlob` from the KMS operation + - “create-time” (S): `timestamp` + - "kms-arn" (S): configured KMS Key + - “hierarchy-version” (N): either `1` or `2`, depending on the `hierarchy-version` + - Every key-value pair of the custom [encryption context](./structures.md#encryption-context-3) that is associated with the branch key + MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. + - ConditionExpression: `attribute_not_exists(branch-key-id)` + - TableName is the configured Table Name + +TransactWriteItemRequest: + +- TransactWriteItems: List of TransactWriteItem + +If DDB TransactWriteItems is successful, this operation MUST return a successful response containing no additional data. +Otherwise, this operation MUST yield an error. + ### VersionKey On invocation, the caller: From 178bd9a719728c717d2b5697651ae2d88c844920 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 25 Jun 2025 18:20:54 -0700 Subject: [PATCH 006/116] auto commit --- framework/branch-key-store.md | 42 ++++++++++++++++++----------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index a8cc74fd..6128e384 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -780,32 +780,41 @@ The following branch key context keys are shared: - MUST have a `hierarchy-version` - MUST NOT have a `enc` attribute -### ACTIVE Branch Key Context +## Encryption Context + +This section describes how the AWS KMS encryption context is built. + +If the `hierarchy-version` is 1, AWS KMS encryption context MUST be same as [branch key context](#branch-key-context). +If the `hierarchy-version` is 2, 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). + +### ACTIVE Encryption Context -The ACTIVE branch key is a copy of the DECRYPT_ONLY with the same `version`. +The ACTIVE encryption context is a copy of the DECRYPT_ONLY with the same `version`. It is structured slightly differently so that the active version can be accessed quickly. -In addition to the [branch key context](#encryption-context): +In addition to the [encryption context](#encryption-context): -The ACTIVE branch key context value of the `type` attribute MUST equal to `"branch:ACTIVE"`. -The ACTIVE branch key context MUST have a `version` attribute. +The ACTIVE encryption context value of the `type` attribute MUST equal to `"branch:ACTIVE"`. +The ACTIVE encryption context MUST have a `version` attribute. The `version` attribute MUST store the branch key version formatted like `"branch:version:"` + `version`. -### DECRYPT_ONLY Branch Key Context +### DECRYPT_ONLY Encryption Context -In addition to the [branch key context](#encryption-context): +In addition to the [encryption context](#encryption-context): -The DECRYPT_ONLY branch key context MUST NOT have a `version` attribute. +The DECRYPT_ONLY encryption context MUST NOT have a `version` attribute. The `type` attribute MUST stores the branch key version formatted like `"branch:version:"` + `version`. -### Beacon Key Branch Key Context +### Beacon Key Encryption Context -In addition to the [branch key context](#encryption-context): +In addition to the [encryption context](#encryption-context): -The Beacon key branch key context value of the `type` attribute MUST equal to `"beacon:ACTIVE"`. -The Beacon key branch key context MUST NOT have a `version` attribute. +The Beacon key encryption context value of the `type` attribute MUST equal to `"beacon:ACTIVE"`. +The Beacon key encryption context MUST NOT have a `version` attribute. -### Custom Branch Key Context +### Custom Encryption Context If custom [branch key context](./structures.md#encryption-context-3) is associated with the branch key these values MUST be added to the AWS KMS branch key context. @@ -813,13 +822,6 @@ To avoid name collisions each added attribute from the custom [branch key contex MUST be prefixed with `aws-crypto-ec:`. Across all versions of a Branch Key, the custom branch key context MUST be equal. -## Encryption Context - -This section describes how the AWS KMS encryption context is built. - -If the `hierarchy-version` is 1, AWS KMS encryption context MUST be same as [branch key context](#branch-key-context). -If the `hierarchy-version` is 2, AWS KMS encryption context MUST be the [encryption context](../structures.md#encryption-context) send by users without any transformation. - ## AWS KMS Branch Key Decryption The operation MUST use the configured `KMS SDK Client` to decrypt the value of the branch key field. From f246cc4c942239b1e738ff276e017efeee9969f9 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 25 Jun 2025 19:42:38 -0700 Subject: [PATCH 007/116] auto commit --- framework/branch-key-store.md | 94 ++++++++++++++++++++++++++--------- 1 file changed, 70 insertions(+), 24 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 6128e384..fe38f8cd 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -427,7 +427,7 @@ the [encryption context for beacon keys](#beacon-key-encryption-context), using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. The operation MUST calculate the **SHA-384 Digest for the beacon key** -by [serializing](../structures.md#serialization) the [encryption context for beacon keys](#beacon-key-encryption-context); +by [serializing](../structures.md#serialization) the [branch key context for beacon keys](#beacon-key-branch-key-context); the serialization MUST be done according to the [encryption context serialization specification](../structures.md#serialization). **Note**: The Encryption Context sent to KMS is NOT prefixed, but the Encryption Context included in the Digest is. @@ -780,6 +780,39 @@ The following branch key context keys are shared: - MUST have a `hierarchy-version` - MUST NOT have a `enc` attribute +### ACTIVE Branch Key Context + +The ACTIVE branch key is a copy of the DECRYPT_ONLY with the same `version`. +It is structured slightly differently so that the active version can be accessed quickly. + +In addition to the [branch key context](#encryption-context): + +The ACTIVE branch key context value of the `type` attribute MUST equal to `"branch:ACTIVE"`. +The ACTIVE branch key context MUST have a `version` attribute. +The `version` attribute MUST store the branch key version formatted like `"branch:version:"` + `version`. + +### DECRYPT_ONLY Branch Key Context + +In addition to the [branch key context](#encryption-context): + +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`. + +### Beacon Key Branch Key Context + +In addition to the [branch key context](#encryption-context): + +The Beacon key branch key context value of the `type` attribute MUST equal to `"beacon:ACTIVE"`. +The Beacon key branch key context MUST NOT have a `version` attribute. + +### Custom Branch Key Context + +If custom [branch key context](./structures.md#encryption-context-3) +is associated with the branch key these values MUST be added to the AWS KMS branch key context. +To avoid name collisions each added attribute from the custom [branch key context](./structures.md#encryption-context-3) +MUST be prefixed with `aws-crypto-ec:`. +Across all versions of a Branch Key, the custom branch key context MUST be equal. + ## Encryption Context This section describes how the AWS KMS encryption context is built. @@ -791,36 +824,19 @@ AWS KMS encryption context MUST be always the same encryption context send by us ### ACTIVE Encryption Context -The ACTIVE encryption context is a copy of the DECRYPT_ONLY with the same `version`. -It is structured slightly differently so that the active version can be accessed quickly. - -In addition to the [encryption context](#encryption-context): - -The ACTIVE encryption context value of the `type` attribute MUST equal to `"branch:ACTIVE"`. -The ACTIVE encryption context MUST have a `version` attribute. -The `version` attribute MUST store the branch key version formatted like `"branch:version:"` + `version`. +ACTIVE Encryption Context is same as [ACTIVE Branch Key Context](#active-branch-key-context) ### DECRYPT_ONLY Encryption Context -In addition to the [encryption context](#encryption-context): - -The DECRYPT_ONLY encryption context MUST NOT have a `version` attribute. -The `type` attribute MUST stores the branch key version formatted like `"branch:version:"` + `version`. +DECRYPT_ONLY Encryption Context is same as [DECRYPT_ONLY Branch Key Context](#decrypt_only-branch-key-context) ### Beacon Key Encryption Context -In addition to the [encryption context](#encryption-context): - -The Beacon key encryption context value of the `type` attribute MUST equal to `"beacon:ACTIVE"`. -The Beacon key encryption context MUST NOT have a `version` attribute. +Beacon Encryption Context is same as [Beacon Key Branch Key Context](#beacon-key-branch-key-context) ### Custom Encryption Context -If custom [branch key context](./structures.md#encryption-context-3) -is associated with the branch key these values MUST be added to the AWS KMS branch key context. -To avoid name collisions each added attribute from the custom [branch key context](./structures.md#encryption-context-3) -MUST be prefixed with `aws-crypto-ec:`. -Across all versions of a Branch Key, the custom branch key context MUST be equal. +Custom Encryption Context is same as [Beacon Key Branch Key Context](#custom-branch-key-context) ## AWS KMS Branch Key Decryption @@ -844,10 +860,40 @@ the keystore operation MUST call with a request constructed as follows: - `KeyId`, if the KMS Configuration is Discovery, MUST be the `kms-arn` attribute value of the AWS DDB response item. If the KMS Configuration is MRDiscovery, `KeyId` MUST be the `kms-arn` attribute value of the AWS DDB response item, with the region replaced by the configured region. Otherwise, it MUST BE the Keystore's configured KMS Key. -- `CiphertextBlob` MUST be the `CiphertextBlob` attribute value on the provided EncryptedHierarchicalKey -- `EncryptionContext` MUST be the [encryption context](#encryption-context) of the provided EncryptedHierarchicalKey +- `CiphertextBlob` MUST be the enc attribute value on the AWS DDB response item +- `EncryptionContext` MUST be the [encryption context](#encryption-context) constructed above - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). +Every attribute except for `enc` on the AWS DDB response item +MUST be authenticated in the decryption of `enc`. +In Hierarchy Version `v1`, when AWS KMS Decrypt succeeds this attribute gets +authenticated by KMS as they are included in the AWS KMS encryption context. +For authentication of these attributes in Hierarchy Version `v2`, +the operation MUST match the first 48 bytes of `Plaintext` returned by AWS KMS Decrypt operation with SHA-384 Digest for the beacon key of serialization of the [branch key context](#branch-key-context). + +## Record Format + +A branch key record MUST include the following key-value pairs: + +1. `branch-key-id` : Unique identifier for a branch key; represented as [AWS DDB String](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) +1. `type` : One of the following; represented as [AWS DDB String](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) + - The string literal `"beacon:ACTIVE"`. Then `enc` is the wrapped beacon key. + - The string `"branch:version:"` + `version`, where `version` is the Branch Key Version. Then `enc` is the wrapped branch key. + - The string literal `"branch:ACTIVE"`. Then `enc` is the wrapped beacon key of the active version. Then +1. `version` : Only exists if `type` is the string literal `"branch:ACTIVE"`. + Then it is the Branch Key Version. represented as [AWS DDB String](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) +1. `enc` : Encrypted version of the key; + represented as [AWS DDB Binary](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) +1. `kms-arn`: The AWS KMS Key ARN used to generate the `enc` value. + represented as [AWS DDB String](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) +1. `create-time`: Timestamp in ISO 8601 format in UTC, to microsecond precision. + Represented as [AWS DDB String](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) +1. `hierarchy-version`: Version of the hierarchical keyring; + represented as [AWS DDB Number](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) + +A branch key record MAY include [custom encryption context](#custom-encryption-context) key-value pairs. +These attributes MUST be always prefixed with `aws-crypto-ec:` regardless of the item's `hierarchy-version`. + ### Branch Key Materials From Authenticated Encryption Context The `type` attribute MUST either be equal to `"branch:ACTIVE"` or start with `"branch:version:"`. From 838e818deefa53d90f660934eca8cec8d2f3aea3 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 26 Jun 2025 09:07:22 -0700 Subject: [PATCH 008/116] auto commit --- framework/branch-key-store.md | 73 ++++++++++++----------------------- 1 file changed, 24 insertions(+), 49 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index fe38f8cd..f3cfe9db 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -423,15 +423,12 @@ the operation MUST use the `CiphertextBlob` as the wrapped Beacon Key. ##### Wrapped Beacon Key Creation `v2` The operation MUST generate a Map of strings, -the [encryption context for beacon keys](#beacon-key-encryption-context), -using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. +the [branch key context for beacon keys](#beacon-key-branch-key-context). The operation MUST calculate the **SHA-384 Digest for the beacon key** by [serializing](../structures.md#serialization) the [branch key context for beacon keys](#beacon-key-branch-key-context); the serialization MUST be done according to the [encryption context serialization specification](../structures.md#serialization). -**Note**: The Encryption Context sent to KMS is NOT prefixed, but the Encryption Context included in the Digest is. - The operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). The call to AWS KMS GenerateDataKey MUST use the configured AWS KMS client to make the call. The operation MUST call AWS KMS GenerateDataKey with a request constructed as follows: @@ -505,23 +502,20 @@ as the wrapped ACTIVE Branch Key. ##### Wrapped Branch Key Creation `v2` The operation MUST generate a Map of strings, -the [`DECRYPT_ONLY` encryption context for branch keys](#decrypt_only-encryption-context), +the [`DECRYPT_ONLY` branch key context for branch keys](#decrypt_only-branch-key-context), using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. The operation MUST calculate the **SHA-384 Digest for the `DECRYPT_ONLY`** -by [serializing](../structures.md#serialization) the [`DECRYPT_ONLY` encryption context for branch keys](#decrypt_only-encryption-context); +by [serializing](../structures.md#serialization) the [`DECRYPT_ONLY` branch key context for branch keys](#decrypt_only-branch-key-context); the serialization MUST be done according to the [encryption context serialization specification](../structures.md#serialization). The operation MUST generate a Map of strings, -the [ACTIVE encryption context for branch keys](#active-encryption-context) -using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. +the [ACTIVE branch key context for branch keys](#active-branch-key-context). The operation MUST calculate the **SHA-384 Digest for the `ACTIVE`** by [serializing](../structures.md#serialization) the [`ACTIVE` encryption context for branch keys](#active-encryption-context); the serialization MUST be done according to the [encryption context serialization specification](../structures.md#serialization). -**Note**: The Encryption Context sent to KMS is NOT prefixed, but the Encryption Context included in the Digest is. - The operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). The call to AWS KMS GenerateDataKey MUST use the configured AWS KMS client to make the call. The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: @@ -572,8 +566,6 @@ as the wrapped `ACTIVE` Branch Key. To add the branch keys and a beacon key to the keystore the operation MUST call [Amazon DynamoDB API TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html). -**Note**: The Encryption Context sent to KMS is NOT prefixed, but the Encryption Context written to DynaomDB is. - The call to Amazon DynamoDB TransactWriteItems MUST use the configured Amazon DynamoDB Client to make the call. The operation MUST call Amazon DynamoDB TransactWriteItems with a request constructed as follows: @@ -689,18 +681,14 @@ On invocation, the caller: - MUST supply a `branch-key-id` -GetActiveBranchKey MUST get the active version for the branch key id from the keystore -by calling the configured [KeyStorage interface's](./key-store/key-storage.md#interface) -[GetEncryptedActiveBranchKey](./key-store/key-storage.md#getencryptedactivebranchkey) -using the supplied `branch-key-id`. - -Because the storage interface can be a custom implementation the key store needs to verify correctness. +To get the active version for the branch key id from the keystore +this operation MUST call AWS DDB `GetItem` +using the `branch-key-id` as the Partition Key and `"branch:ACTIVE"` value as the Sort Key. -GetActiveBranchKey MUST verify that the returned EncryptedHierarchicalKey MUST have the requested `branch-key-id`. -GetActiveBranchKey MUST verify that the returned EncryptedHierarchicalKey is an ActiveHierarchicalSymmetricVersion. -GetActiveBranchKey MUST verify that the returned EncryptedHierarchicalKey MUST have a logical table name equal to the configured logical table name. +The AWS DDB response MUST contain the fields defined in the [branch keystore record format](#record-format). +If the record does not contain the defined fields, this operation MUST fail. -The operation MUST decrypt the EncryptedHierarchicalKey according to the [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) section. +The operation MUST decrypt the branch key according to the [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) section. If the branch key fails to decrypt, GetActiveBranchKey MUST fail. @@ -711,22 +699,14 @@ This operation MUST return the constructed [branch key materials](./structures.m ### GetBranchKeyVersion -On invocation, the caller: - - MUST supply a `branch-key-id` - MUST supply a `branchKeyVersion` -GetBranchKeyVersion MUST get the requested version for the branch key id from the keystore -by calling the configured [KeyStorage interface's](./key-store/key-storage.md#interface) -[GetEncryptedActiveBranchKey](./key-store/key-storage.md#getencryptedbranchkeyversion) -using the supplied `branch-key-id`. +To get a branch key from the keystore this operation MUST call AWS DDB `GetItem` +using the `branch-key-id` as the Partition Key and "branch:version:" + `branchKeyVersion` value as the Sort Key. -Because the storage interface can be a custom implementation the key store needs to verify correctness. - -GetBranchKeyVersion MUST verify that the returned EncryptedHierarchicalKey MUST have the requested `branch-key-id`. -GetBranchKeyVersion MUST verify that the returned EncryptedHierarchicalKey MUST have the requested `branchKeyVersion`. -GetActiveBranchKey MUST verify that the returned EncryptedHierarchicalKey is an HierarchicalSymmetricVersion. -GetBranchKeyVersion MUST verify that the returned EncryptedHierarchicalKey MUST have a logical table name equal to the configured logical table name. +The AWS DDB response MUST contain the fields defined in the [branch keystore record format](#record-format). +If the record does not contain the defined fields, this operation MUST fail. The operation MUST decrypt the branch key according to the [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) section. @@ -743,16 +723,11 @@ On invocation, the caller: - MUST supply a `branch-key-id` -GetBeaconKey MUST get the requested beacon key from the keystore -by calling the configured [KeyStorage interface's](./key-store/key-storage.md#interface) -[GetEncryptedBeaconKey](./key-store/key-storage.md#getencryptedbeaconkey) -using the supplied `branch-key-id`. - -Because the storage interface can be a custom implementation the key store needs to verify correctness. +To get a branch key from the keystore this operation MUST call AWS DDB `GetItem` +using the `branch-key-id` as the Partition Key and "beacon:ACTIVE" value as the Sort Key. -GetBeaconKey MUST verify that the returned EncryptedHierarchicalKey MUST have the requested `branch-key-id`. -GetBeaconKey MUST verify that the returned EncryptedHierarchicalKey is an ActiveHierarchicalSymmetricBeacon. -GetBeaconKey MUST verify that the returned EncryptedHierarchicalKey MUST have a logical table name equal to the configured logical table name. +The AWS DDB response MUST contain the fields defined in the [branch keystore record format](#record-format). +If the record does not contain the defined fields, this operation MUST fail. The operation MUST decrypt the beacon key according to the [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) section. @@ -817,26 +792,26 @@ Across all versions of a Branch Key, the custom branch key context MUST be equal This section describes how the AWS KMS encryption context is built. -If the `hierarchy-version` is 1, AWS KMS encryption context MUST be same as [branch key context](#branch-key-context). -If the `hierarchy-version` is 2, AWS KMS encryption context MUST be the [encryption context](../structures.md#encryption-context) send by users without any transformation. +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). ### ACTIVE Encryption Context -ACTIVE Encryption Context is same as [ACTIVE Branch Key Context](#active-branch-key-context) +If the `hierarchy-version` is v1, ACTIVE Encryption Context is same as [ACTIVE Branch Key Context](#active-branch-key-context) ### DECRYPT_ONLY Encryption Context -DECRYPT_ONLY Encryption Context is same as [DECRYPT_ONLY Branch Key Context](#decrypt_only-branch-key-context) +If the `hierarchy-version` is v1, DECRYPT_ONLY Encryption Context is same as [DECRYPT_ONLY Branch Key Context](#decrypt_only-branch-key-context) ### Beacon Key Encryption Context -Beacon Encryption Context is same as [Beacon Key Branch Key Context](#beacon-key-branch-key-context) +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 -Custom Encryption Context is same as [Beacon Key Branch Key Context](#custom-branch-key-context) +If the `hierarchy-version` is v1, Custom Encryption Context is same as [Beacon Key Branch Key Context](#custom-branch-key-context) ## AWS KMS Branch Key Decryption From 6bff806116085d3e832ff6e1bfd9b6ab25cd3d52 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 26 Jun 2025 10:06:19 -0700 Subject: [PATCH 009/116] auto commit --- framework/branch-key-store.md | 114 +++++++++++++++++++++++++--------- 1 file changed, 86 insertions(+), 28 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index f3cfe9db..b95cfe07 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -625,55 +625,113 @@ If the Keystore's KMS Configuration is `Discovery` or `MRDiscovery`, this operation MUST immediately fail. VersionKey MUST first get the active version for the branch key from the keystore -by calling the configured [KeyStorage interface's](./key-store/key-storage.md#interface) -[GetEncryptedActiveBranchKey](./key-store/key-storage.md##getencryptedactivebranchkey) -using the `branch-key-id`. +by calling AWS DDB `GetItem` +using the `branch-key-id` as the Partition Key and `"branch:ACTIVE"` value as the Sort Key. -The `KmsArn` of the [EncryptedHierarchicalKey](./key-store/key-storage.md##encryptedhierarchicalkey) -MUST be [compatible with](#aws-key-arn-compatibility) +The `kms-arn` field of DDB response item MUST be [compatible with](#aws-key-arn-compatibility) the configured `KMS ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. -Because the storage interface can be a custom implementation the key store needs to verify correctness. - -VersionKey MUST verify that the returned EncryptedHierarchicalKey MUST have the requested `branch-key-id`. -VersionKey MUST verify that the returned EncryptedHierarchicalKey is an ActiveHierarchicalSymmetricVersion. -VersionKey MUST verify that the returned EncryptedHierarchicalKey MUST have a logical table name equal to the configured logical table name. - -The `kms-arn` stored in the table MUST NOT change as a result of this operation, +The `kms-arn` stored in the DDB table MUST NOT change as a result of this operation, even if the KeyStore is configured with a `KMS MRKey ARN` that does not exactly match the stored ARN. If such were allowed, clients using non-MRK KeyStores might suddenly stop working. -The [EncryptedHierarchicalKey](./key-store/key-storage.md##encryptedhierarchicalkey) -MUST be authenticated according to [authenticating a keystore item](#authenticating-an-encryptedhierarchicalkey). +The values on the AWS DDB response item +MUST be authenticated according to [authenticating a keystore item](#authenticating-a-keystore-item). If the item fails to authenticate this operation MUST fail. The wrapped Branch Keys, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Branch Key Creation](#wrapped-branch-key-creation). -If creation of the keys are successful, -then the key store MUST call the configured [KeyStorage interface's](./key-store/key-storage.md#interface) -[WriteNewEncryptedBranchKeyVersion](./key-store/key-storage.md#writenewencryptedbranchkeyversion) -with an [OverWriteEncryptedHierarchicalKey](./key-store/key-storage.md#overwriteencryptedhierarchicalkey) -with an `Item` that is the new ACTIVE -and an `Old` that is the original ACTIVE, -along with DECRYPT_ONLY. - -If the [WriteNewEncryptedBranchKeyVersion](./key-store/key-storage.md##writenewencryptedbranchkeyversion) is successful, -this operation MUST return a successful response containing no additional data. +To add the new branch key to the keystore, +the operation MUST call [Amazon DynamoDB API TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html). +The call to Amazon DynamoDB TransactWriteItems MUST use the configured Amazon DynamoDB Client to make the call. +The operation MUST call Amazon DynamoDB TransactWriteItems with a request constructed as follows: + +List of TransactWriteItem: + +- PUT: + - Item: + - “branch-key-id” (S): `branchKeyId`, + - “type“ (S): "branch:version:" + `version`, + - “enc” (B): the wrapped DECRYPT_ONLY Branch Key `CiphertextBlob` from the KMS operation + - “create-time” (S): `timestamp` + - "kms-arn" (S): configured KMS Key + - “hierarchy-version” (N): 1 + - Every key-value pair of the custom [encryption context](./structures.md#encryption-context-3) that is associated with the branch key + MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. + - ConditionExpression: `attribute_not_exists(branch-key-id)` + - TableName: the configured Table Name +- PUT: + - Item: + - “branch-key-id” (S): `branchKeyId`, + - “type“ (S): "branch:ACTIVE", + - “enc” (B): wrapped ACTIVE Branch Key `CiphertextBlob` from the KMS operation + - “create-time” (S): `timestamp` + - "kms-arn" (S): configured KMS Key + - “hierarchy-version” (N): 1 + - Every key-value pair of the custom [encryption context](./structures.md#encryption-context-3) that is associated with the branch key + MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. + - ConditionExpression: `attribute_exists(branch-key-id) AND enc = :encOld` + - ExpressionAttributeValues: `{":encOld" := DDB.AttributeValue.B(oldCiphertextBlob)}` + - TableName: the configured Table Name + +TransactWriteItemRequest: + +- TransactWriteItems: List of TransactWriteItem + +If DDB TransactWriteItems is successful, this operation MUST return a successful response containing no additional data. Otherwise, this operation MUST yield an error. -#### Authenticating an EncryptedHierarchicalKey +The condition expression for the Active Input ensures +the Active Item in storage has not changed since it was read. +This prevents overwrites due to a race in updating the Active Item. + +#### Authenticating a Keystore item for item with `hierarchy-version` v1 The operation MUST use the configured `KMS SDK Client` to authenticate the value of the keystore item. +Every attribute on the AWS DDB response item will be authenticated. + +Every key in the constructed [encryption context](#encryption-context) +except `tableName` +MUST exist as a string attribute in the AWS DDB response item. +Every value in the constructed [encryption context](#encryption-context) +except the logical table name +MUST equal the value with the same key in the AWS DDB response item. +The key `enc` MUST NOT exist in the constructed [encryption context](#encryption-context). + The operation MUST call [AWS KMS API ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) with a request constructed as follows: -- `SourceEncryptionContext` MUST be the [encryption context](#encryption-context) of the EncryptedHierarchicalKey to be authenticated +- `SourceEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above +- `SourceKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured KMS Key in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. +- `CiphertextBlob` MUST be the `enc` attribute value on the AWS DDB response item +- `GrantTokens` MUST be the configured [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). +- `DestinationKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured KMS Key in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. +- `DestinationEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above + +#### Authenticating a Keystore item for item with `hierarchy-version` v2 + +The operation MUST use the configured `KMS SDK Client` to authenticate the value of the keystore item. + +Every attribute on the AWS DDB response item will be authenticated. + +Every key in the constructed [branch key context](#branch-key-context) +except `tableName` +MUST exist as a string attribute in the AWS DDB response item. +Every value in the constructed [branch key context](#branch-key-context) +except the logical table name +MUST equal the value with the same key in the AWS DDB response item. +The key `enc` MUST NOT exist in the constructed [branch key context](#branch-key-context). + +The operation MUST call [AWS KMS API Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) +with a request constructed as follows: + +- `SourceEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above - `SourceKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured KMS Key in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. -- `CiphertextBlob` MUST be the `CiphertextBlob` attribute value on the EncryptedHierarchicalKey to be authenticated +- `CiphertextBlob` MUST be the `enc` attribute value on the AWS DDB response item - `GrantTokens` MUST be the configured [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). - `DestinationKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured KMS Key in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. -- `DestinationEncryptionContext` MUST be the [encryption context](#encryption-context) of the EncryptedHierarchicalKey to be authenticated +- `DestinationEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above ### GetActiveBranchKey From 413d74d8bf3e1c725d28df5583d8e541945b4f07 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 26 Jun 2025 10:39:57 -0700 Subject: [PATCH 010/116] auto commit --- framework/branch-key-store.md | 21 +++------------------ 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index b95cfe07..b87424fc 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -713,25 +713,10 @@ with a request constructed as follows: The operation MUST use the configured `KMS SDK Client` to authenticate the value of the keystore item. -Every attribute on the AWS DDB response item will be authenticated. - -Every key in the constructed [branch key context](#branch-key-context) -except `tableName` -MUST exist as a string attribute in the AWS DDB response item. -Every value in the constructed [branch key context](#branch-key-context) -except the logical table name -MUST equal the value with the same key in the AWS DDB response item. -The key `enc` MUST NOT exist in the constructed [branch key context](#branch-key-context). - -The operation MUST call [AWS KMS API Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) -with a request constructed as follows: +Every attribute on the AWS DDB response item expect `enc` MUST be authenticated. +From the AWS DDB response item, the operation MUST create a [branch key context](#branch-key-context) and [encryption context](#encryption-context). -- `SourceEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above -- `SourceKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured KMS Key in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. -- `CiphertextBlob` MUST be the `enc` attribute value on the AWS DDB response item -- `GrantTokens` MUST be the configured [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -- `DestinationKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured KMS Key in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. -- `DestinationEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above +The operation MUST call [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) to decrypt and authentication the branch key context. ### GetActiveBranchKey From ab82862a130306cea8068cd5d61f963b7e1a8002 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 26 Jun 2025 10:42:18 -0700 Subject: [PATCH 011/116] auto commit --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index b87424fc..ad1eada0 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -636,7 +636,7 @@ even if the KeyStore is configured with a `KMS MRKey ARN` that does not exactly If such were allowed, clients using non-MRK KeyStores might suddenly stop working. The values on the AWS DDB response item -MUST be authenticated according to [authenticating a keystore item](#authenticating-a-keystore-item). +MUST be authenticated according to [authenticating a keystore item for item with hierarchy version v1](#authenticating-a-keystore-item-for-item-with-hierarchy-version-v1) or [authenticating a keystore item for item with hierarchy version v2](#authenticating-a-keystore-item-for-item-with-hierarchy-version-v2) based on schema version of the item. If the item fails to authenticate this operation MUST fail. The wrapped Branch Keys, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Branch Key Creation](#wrapped-branch-key-creation). From 5f9db4c0f6a0eb0a224157ddc658299c77bf6c7e Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 26 Jun 2025 11:45:16 -0700 Subject: [PATCH 012/116] auto commit --- framework/branch-key-store.md | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index ad1eada0..45084292 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -39,7 +39,7 @@ A Keystore persists hierarchical data that allows customers to call AWS KMS less often. The Keystore persists branch keys that wrap multiple data keys. This creates a hierarchy where a branch key wraps multiple data keys and facilitates caching. -These branch keys are only generated using the [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html). +These branch keys are only generated using the [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) in Hierarchy Version `v1` or [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) in Hierarchy Version `v2`. By creating and persisting a data key to an accessible medium, such as a DynamoDb table, @@ -361,7 +361,7 @@ then this operation MUST create a [version 4 UUID](https://www.ietf.org/rfc/rfc4 to be used as the branch key id. If no Hierarchy-Version is provided, -the then this operation MUST use `v1`. +then this operation MUST use `v1`. This operation needs to generate the following: @@ -402,7 +402,7 @@ the wrapped branch keys MUST be created according to else the `hierarchy-version` MUST be `v2`, the wrapped beacon Key MUST be created according to [Wrapped Beacon Key Creation `v2`](#wrapped-beacon-key-creation-v2) and the wrapped branch keys MUST be created according to -[Wrapped Branch Key Creation `v2`](#wrapped-branch-key-creation-v2),. +[Wrapped Branch Key Creation `v2`](#wrapped-branch-key-creation-v2). ##### Wrapped Beacon Key Creation `v1` @@ -422,7 +422,7 @@ the operation MUST use the `CiphertextBlob` as the wrapped Beacon Key. ##### Wrapped Beacon Key Creation `v2` -The operation MUST generate a Map of strings, +The operation MUST create a map of strings, the [branch key context for beacon keys](#beacon-key-branch-key-context). The operation MUST calculate the **SHA-384 Digest for the beacon key** @@ -439,17 +439,17 @@ The operation MUST call AWS KMS GenerateDataKey with a request constructed as fo - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). If the call to AWS KMS GenerateDataKey succeeds, -the operation MUST use the GenerateDataKey results `PlaintextBlob` +the operation MUST use the `Plaintext` from GenerateDataKey result as the plain-text Beacon Key. The operation MUST concatenate the **SHA-384 Digest for the beacon key** with the plain-text Beacon Key, -creating the **the beacon plain-text tuple**. +creating the **beacon plain-text tuple**. 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` **SHA-384 Digest for the beacon key** +- `Plaintext` **beacon plain-text tuple** - `KeyId` MUST be the `kms-arn`. - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). - `EncryptionContext` MUST be the `encryption-context` @@ -464,11 +464,11 @@ Given a `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, ##### Wrapped Branch Key Creation `v1` -The operation MUST generate a Map of strings, +The operation MUST generate a map of strings, the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context), using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. -The operation MUST generate a Map of strings, +The operation MUST generate a map of strings, the [ACTIVE encryption context for branch keys](#active-encryption-context) using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. @@ -501,15 +501,14 @@ as the wrapped ACTIVE Branch Key. ##### Wrapped Branch Key Creation `v2` -The operation MUST generate a Map of strings, -the [`DECRYPT_ONLY` branch key context for branch keys](#decrypt_only-branch-key-context), -using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. +The operation MUST generate a map of strings, +the [`DECRYPT_ONLY` branch key context for branch keys](#decrypt_only-branch-key-context). The operation MUST calculate the **SHA-384 Digest for the `DECRYPT_ONLY`** by [serializing](../structures.md#serialization) the [`DECRYPT_ONLY` branch key context for branch keys](#decrypt_only-branch-key-context); the serialization MUST be done according to the [encryption context serialization specification](../structures.md#serialization). -The operation MUST generate a Map of strings, +The operation MUST generate a map of strings, the [ACTIVE branch key context for branch keys](#active-branch-key-context). The operation MUST calculate the **SHA-384 Digest for the `ACTIVE`** @@ -518,7 +517,7 @@ the serialization MUST be done according to the [encryption context serializatio The operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). The call to AWS KMS GenerateDataKey MUST use the configured AWS KMS client to make the call. -The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: +The operation MUST call AWS KMS GenerateDataKey with a request constructed as follows: - `KeyId` MUST be the `kms-arn` - `NumberOfBytes` MUST be 32. @@ -526,12 +525,12 @@ The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request c - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). If the call to AWS KMS GenerateDataKey succeeds, -the operation MUST use the GenerateDataKey results `PlaintextBlob` +the operation MUST use the `Plaintext` from GenerateDataKey result as the plain-text Branch Key. The operation MUST concatenate the **SHA-384 Digest for the `DECRYPT_ONLY`** with the plain-text Branch Key, -creating the **the `DECRYPT_ONLY` plain-text tuple**. +creating the **`DECRYPT_ONLY` plain-text tuple**. The operation MUST call [AWS KMS API Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) with a request constructed as follows: @@ -636,7 +635,7 @@ even if the KeyStore is configured with a `KMS MRKey ARN` that does not exactly If such were allowed, clients using non-MRK KeyStores might suddenly stop working. The values on the AWS DDB response item -MUST be authenticated according to [authenticating a keystore item for item with hierarchy version v1](#authenticating-a-keystore-item-for-item-with-hierarchy-version-v1) or [authenticating a keystore item for item with hierarchy version v2](#authenticating-a-keystore-item-for-item-with-hierarchy-version-v2) based on schema version of the item. +MUST be authenticated according to [authenticating a keystore item for item with hierarchy version v1](#authenticating-a-keystore-item-for-item-with-hierarchy-version-v1) or [authenticating a keystore item for item with hierarchy version v2](#authenticating-a-keystore-item-for-item-with-hierarchy-version-v2) based on schema version of the branch key item. If the item fails to authenticate this operation MUST fail. The wrapped Branch Keys, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Branch Key Creation](#wrapped-branch-key-creation). From 8b54bac47f0e98ddf511ce3112e4fe281910a76d Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 26 Jun 2025 11:48:15 -0700 Subject: [PATCH 013/116] auto commit --- framework/branch-key-store.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 45084292..334a2684 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -512,7 +512,7 @@ The operation MUST generate a map of strings, the [ACTIVE branch key context for branch keys](#active-branch-key-context). The operation MUST calculate the **SHA-384 Digest for the `ACTIVE`** -by [serializing](../structures.md#serialization) the [`ACTIVE` encryption context for branch keys](#active-encryption-context); +by [serializing](../structures.md#serialization) the [`ACTIVE` branch key context for branch keys](#active-branch-key-context); the serialization MUST be done according to the [encryption context serialization specification](../structures.md#serialization). The operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). @@ -810,7 +810,7 @@ The `version` attribute MUST store the branch key version formatted like `"branc ### DECRYPT_ONLY Branch Key Context -In addition to the [branch key context](#encryption-context): +In addition to the [branch key context](#branch-key-context): 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`. From 8308fcb62e1dde601252960d07a3ff88efbec434 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 26 Jun 2025 11:57:37 -0700 Subject: [PATCH 014/116] auto commit --- framework/branch-key-store.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 334a2684..dfa66d05 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -476,7 +476,7 @@ The operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://do The call to AWS KMS GenerateDataKeyWithoutPlaintext MUST use the configured AWS KMS client to make the call. The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request constructed as follows: -- `KeyId` MUST be the `kms-arn` +- `KeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `NumberOfBytes` MUST be 32. - `EncryptionContext` MUST be the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context). - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). @@ -635,7 +635,7 @@ even if the KeyStore is configured with a `KMS MRKey ARN` that does not exactly If such were allowed, clients using non-MRK KeyStores might suddenly stop working. The values on the AWS DDB response item -MUST be authenticated according to [authenticating a keystore item for item with hierarchy version v1](#authenticating-a-keystore-item-for-item-with-hierarchy-version-v1) or [authenticating a keystore item for item with hierarchy version v2](#authenticating-a-keystore-item-for-item-with-hierarchy-version-v2) based on schema version of the branch key item. +MUST be authenticated according to [authenticating a keystore item for item with hierarchy version v1](#authenticating-a-branch-keystore-item-for-item-with-hierarchy-version-v1) or [authenticating a keystore item for item with hierarchy version v2](#authenticating-a-branch-keystore-item-for-item-with-hierarchy-version-v2) based on schema version of the branch key item. If the item fails to authenticate this operation MUST fail. The wrapped Branch Keys, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Branch Key Creation](#wrapped-branch-key-creation). @@ -684,11 +684,11 @@ The condition expression for the Active Input ensures the Active Item in storage has not changed since it was read. This prevents overwrites due to a race in updating the Active Item. -#### Authenticating a Keystore item for item with `hierarchy-version` v1 +#### Authenticating a Branch Keystore item for item with `hierarchy-version` v1 The operation MUST use the configured `KMS SDK Client` to authenticate the value of the keystore item. -Every attribute on the AWS DDB response item will be authenticated. +Every attribute on the AWS DDB response item except `enc` attribute MUST be authenticated. Every key in the constructed [encryption context](#encryption-context) except `tableName` @@ -708,7 +708,7 @@ with a request constructed as follows: - `DestinationKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured KMS Key in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `DestinationEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above -#### Authenticating a Keystore item for item with `hierarchy-version` v2 +#### Authenticating a Branch Keystore item for item with `hierarchy-version` v2 The operation MUST use the configured `KMS SDK Client` to authenticate the value of the keystore item. From 8baeb725d3df271c0188ac364c3ca1cd8a66ad85 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 26 Jun 2025 12:02:51 -0700 Subject: [PATCH 015/116] auto commit --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index dfa66d05..7342cb76 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -715,7 +715,7 @@ The operation MUST use the configured `KMS SDK Client` to authenticate the value Every attribute on the AWS DDB response item expect `enc` MUST be authenticated. From the AWS DDB response item, the operation MUST create a [branch key context](#branch-key-context) and [encryption context](#encryption-context). -The operation MUST call [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) to decrypt and authentication the branch key context. +The operation MUST follow [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) to decrypt and authentication the branch key context. ### GetActiveBranchKey From 879f13c9db41633b2a36e355cc7a12878e1c6e84 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 26 Jun 2025 12:15:49 -0700 Subject: [PATCH 016/116] auto commit --- framework/branch-key-store.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 7342cb76..53c325b9 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -822,14 +822,6 @@ In addition to the [branch key context](#encryption-context): The Beacon key branch key context value of the `type` attribute MUST equal to `"beacon:ACTIVE"`. The Beacon key branch key context MUST NOT have a `version` attribute. -### Custom Branch Key Context - -If custom [branch key context](./structures.md#encryption-context-3) -is associated with the branch key these values MUST be added to the AWS KMS branch key context. -To avoid name collisions each added attribute from the custom [branch key context](./structures.md#encryption-context-3) -MUST be prefixed with `aws-crypto-ec:`. -Across all versions of a Branch Key, the custom branch key context MUST be equal. - ## Encryption Context This section describes how the AWS KMS encryption context is built. @@ -853,7 +845,11 @@ If the `hierarchy-version` is v1, Beacon Encryption Context is same as [Beacon K ### Custom Encryption Context -If the `hierarchy-version` is v1, Custom Encryption Context is same as [Beacon Key Branch Key Context](#custom-branch-key-context) +If custom [encrpytion context](./structures.md#encryption-context) +is associated with the branch key these values MUST be added to the AWS KMS encrpytion context. +To avoid name collisions each added attribute from the custom [encrpytion context](./structures.md#encryption-context-3) +MUST be prefixed with `aws-crypto-ec:`. +Across all versions of a Branch Key, the custom encrpytion context MUST be equal. ## AWS KMS Branch Key Decryption From 13aef97ce5c315c7a81c6fb17f54caa665251677 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 26 Jun 2025 12:17:04 -0700 Subject: [PATCH 017/116] auto commit --- framework/branch-key-store.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 53c325b9..642b0d89 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -845,11 +845,11 @@ If the `hierarchy-version` is v1, Beacon Encryption Context is same as [Beacon K ### Custom Encryption Context -If custom [encrpytion context](./structures.md#encryption-context) -is associated with the branch key these values MUST be added to the AWS KMS encrpytion context. -To avoid name collisions each added attribute from the custom [encrpytion context](./structures.md#encryption-context-3) +If custom [encryption context](./structures.md#encryption-context) +is associated with the branch key these values MUST be added to the AWS KMS encryption context. +To avoid name collisions each added attribute from the custom [encryption context](./structures.md#encryption-context-3) MUST be prefixed with `aws-crypto-ec:`. -Across all versions of a Branch Key, the custom encrpytion context MUST be equal. +Across all versions of a Branch Key, the custom encryption context MUST be equal. ## AWS KMS Branch Key Decryption From 6a35be89506b4b1f4670bd2e6b6bd3a1699ad192 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 26 Jun 2025 12:22:47 -0700 Subject: [PATCH 018/116] auto commit --- framework/branch-key-store.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 642b0d89..9276aa90 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -439,7 +439,7 @@ The operation MUST call AWS KMS GenerateDataKey with a request constructed as fo - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). If the call to AWS KMS GenerateDataKey succeeds, -the operation MUST use the `Plaintext` from GenerateDataKey result +the operation MUST use the `Plaintext` from GenerateDataKey result as the plain-text Beacon Key. The operation MUST concatenate the **SHA-384 Digest for the beacon key** @@ -525,7 +525,7 @@ The operation MUST call AWS KMS GenerateDataKey with a request constructed as fo - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). If the call to AWS KMS GenerateDataKey succeeds, -the operation MUST use the `Plaintext` from GenerateDataKey result +the operation MUST use the `Plaintext` from GenerateDataKey result as the plain-text Branch Key. The operation MUST concatenate the **SHA-384 Digest for the `DECRYPT_ONLY`** @@ -782,7 +782,7 @@ This operation MUST return the constructed [beacon key materials](./structures.m ## Branch Key Context -Branch Key Context is a key value pair that can contain additional contextual information about the data. +Branch Key Context is a key value pair that can contain additional contextual information about the data. This section describes how Branch Key Context is built from an [encrypted hierarchical key](./key-store/key-storage.md#encryptedhierarchicalkey). The following branch key context keys are shared: @@ -878,10 +878,10 @@ the keystore operation MUST call with a request constructed as follows: - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). Every attribute except for `enc` on the AWS DDB response item -MUST be authenticated in the decryption of `enc`. -In Hierarchy Version `v1`, when AWS KMS Decrypt succeeds this attribute gets -authenticated by KMS as they are included in the AWS KMS encryption context. -For authentication of these attributes in Hierarchy Version `v2`, +MUST be authenticated in the decryption of `enc`. +In Hierarchy Version `v1`, when AWS KMS Decrypt succeeds this attribute gets +authenticated by KMS as they are included in the AWS KMS encryption context. +For authentication of these attributes in Hierarchy Version `v2`, the operation MUST match the first 48 bytes of `Plaintext` returned by AWS KMS Decrypt operation with SHA-384 Digest for the beacon key of serialization of the [branch key context](#branch-key-context). ## Record Format From 1360dabbad097d83c0badb65b2d76c1c7b53a069 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 26 Jun 2025 12:27:30 -0700 Subject: [PATCH 019/116] auto commit --- .github/workflows/ci_static-analysis.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci_static-analysis.yaml b/.github/workflows/ci_static-analysis.yaml index bdfe9d58..3e15bfbb 100644 --- a/.github/workflows/ci_static-analysis.yaml +++ b/.github/workflows/ci_static-analysis.yaml @@ -16,6 +16,6 @@ jobs: - uses: actions/checkout@v2 - uses: actions/setup-node@v3 - name: install - run: npm install --global prettier + run: npm install --global prettier@3.5.3 - name: prettify run: ./ci/prettify.sh check From 4550addd85ce4135db905600efffe2c021aba688 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Fri, 27 Jun 2025 12:47:19 -0700 Subject: [PATCH 020/116] auto commit --- framework/branch-key-store.md | 4 +++- framework/structures.md | 36 ++++++++++++++++++++++++++++++++++- 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 9276aa90..ccfa8114 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -5,10 +5,12 @@ ## Version -0.7.0 +0.8.0 ### Changelog +- 0.8.0 + - Hierarchy Version 2 - 0.7.1 - Branch key creation only uses customer input - 0.7.0 diff --git a/framework/structures.md b/framework/structures.md index 34c6f088..70af2081 100644 --- a/framework/structures.md +++ b/framework/structures.md @@ -5,10 +5,14 @@ ## Version -0.6.0 +0.7.0 ### Changelog +- 0.7.0 + + - Update Branch Key Structures to include KMS ARN, Create Time, and Hierarchy Version + - 0.6.0 - Update keystore structure and add encryption context options @@ -386,6 +390,9 @@ This structure MUST include all of the following fields: - [Branch Key Id](#branch-key-id) - [Branch Key Version](#branch-key-version) - [Encryption Context](#encryption-context-3) +- [KMS ARN](#kms-arn) +- [Create Time](#create-time) +- [Hierarchy Version](#hierarchy-version) ##### Branch Key @@ -409,6 +416,18 @@ This value MUST be a version 4 [UUID](https://www.ietf.org/rfc/rfc4122.txt). The [custom encryption context](#encryption-context) associated with this branch key. +##### KMS ARN + +The AWS KMS Key ARN used to protect these materials. + +##### Create Time + +Timestamp in ISO 8601 format in UTC, to microsecond precision, that the Material was generated. + +##### Hierarchy Version + +[Schema Version of the Branch Key](branch-key-store.md#hierarchy-version). + ## Beacon Key Materials #### Implementations @@ -427,6 +446,9 @@ This structure MUST include the following fields: - [Beacon Key Id](#beacon-key-id) - [Encryption Context](#encryption-context-4) +- [KMS ARN](#kms-arn) +- [Create Time](#create-time) +- [Hierarchy Version](#hierarchy-version) This structure MAY include the following fields: @@ -447,6 +469,18 @@ the beacon key can be discarded. The [custom encryption context](#encryption-context) associated with this beacon key. +##### KMS ARN + +The AWS KMS Key ARN used to protect these materials. + +##### Create Time + +Timestamp in ISO 8601 format in UTC, to microsecond precision, that the Material was generated. + +##### Hierarchy Version + +[Schema Version of the Branch Key](branch-key-store.md#hierarchy-version). + ##### Beacon Key Id The Beacon key id that was used to obtain From 757de044819ab04e1e0835cea793987ba0a46990 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Fri, 27 Jun 2025 12:49:54 -0700 Subject: [PATCH 021/116] nits --- framework/branch-key-store.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index ccfa8114..262a7708 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -451,7 +451,7 @@ creating the **beacon plain-text tuple**. 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** +- `Plaintext` Must be the **beacon plain-text tuple** - `KeyId` MUST be the `kms-arn`. - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). - `EncryptionContext` MUST be the `encryption-context` @@ -562,7 +562,7 @@ If the call to AWS KMS Encrypt succeeds, the operation MUST use the Encrypt result `CiphertextBlob` as the wrapped `ACTIVE` Branch Key. -#### Writing Branch Key and Beacon Key to Keystore +#### Writing Branch Key and Beacon Key to Branch Key Store table To add the branch keys and a beacon key to the keystore the operation MUST call [Amazon DynamoDB API TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html). From fe9405cda0134ddf17f3e0f652c7c979faa89bf3 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 30 Jun 2025 10:27:40 -0700 Subject: [PATCH 022/116] Update framework/branch-key-store.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 262a7708..32377e8e 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -817,7 +817,7 @@ In addition to the [branch key context](#branch-key-context): 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`. -### Beacon Key Branch Key Context +### Beacon Branch Key Context In addition to the [branch key context](#encryption-context): From 117b632ccee040eb8f4a581c2c2c7498fde63e3a Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 30 Jun 2025 10:28:36 -0700 Subject: [PATCH 023/116] Update framework/branch-key-store.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 32377e8e..3e47311c 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -821,7 +821,7 @@ The `type` attribute MUST stores the branch key version formatted like `"branch: In addition to the [branch key context](#encryption-context): -The Beacon key branch key context value of the `type` attribute MUST equal to `"beacon:ACTIVE"`. +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. ## Encryption Context From 9f7b93e2dd6993f33568c5f7cafd441f5a85fea0 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Mon, 30 Jun 2025 11:40:31 -0700 Subject: [PATCH 024/116] DQ1 --- .../DesignQuestion.md | 394 ++++++++++++++++++ 1 file changed, 394 insertions(+) create mode 100644 changes/2025-06-30_branch_keys_version_2/DesignQuestion.md diff --git a/changes/2025-06-30_branch_keys_version_2/DesignQuestion.md b/changes/2025-06-30_branch_keys_version_2/DesignQuestion.md new file mode 100644 index 00000000..15051ea2 --- /dev/null +++ b/changes/2025-06-30_branch_keys_version_2/DesignQuestion.md @@ -0,0 +1,394 @@ +[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved." +[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0" + +# How can the Branch Key's Metadata be protected without using KMS EC? + +# Definitions + +See [Definitions](./background#Definitions). + +# 1 Plain-text Commitment instead of KMS Encryption Context + +The KMS RSA Keyring has already solved the need +to substitute KMS Encryption Context; +we need only adapt that solution and apply it here. + +## 1.1 Branch Key Creation + +The KMS RSA Keyring, in `OnEncrypt`, +[establishes an "Encryption Context Digest" by](https://github.com/awslabs/aws-encryption-sdk-specification/blob/8d6bb5665c1017bd64989e4bd66bd8759f1e4b1c/framework/aws-kms/aws-kms-rsa-keyring.md?plain=1#L95-L100): + +> 1. Serializing the [encryption context](../../framework/structures.md#encryption-context) from the input [encryption materials](../../framework/structures.md#encryption-materials) according to the [encryption context serialization specification](../../framework/structures.md#serialization). + +> 2. Taking the SHA-384 Digest of this concatenation. + +Except rather than working with the encryption context +from the encryption materials, +HV-2 will serialize the Branch Key's +Metadata according to the +[encryption context serialization specification](../../framework/../framework/structures.md#serialization), +and then take a SHA-384 Digest of these bytes, +creating the Branch Key's **Branch Key Context Digest**. + +This **Branch Key Context Digest** is 48 bytes long, +and MUST be bound to the Branch Key Cryptographic Materials. + +1.3 & 1.4 talk about options that use KMS Encrypt to protect the **Branch Key Context Digest**; +without KMS Encrypt access, +an actor cannot modify the **Branch Key Context Digest**. + +1.5 considers a local HMAC operation, +with the plain-text AES-256 being the key. + +## 1.2 Getting Branch Keys + +The Branch Key Item is read from DDB table; +assuming the read Item is allowed by the Branch Key Store client +(KMS Config restriction; [`hierarchy-version-policy`](./background.md#3-how-are-we-going-to-offer-operation-in-a-mixed-mode)) +the **Branch Key Context Digest** is recreated on the read values. + +`kms:Decrypt` is called. + +If (1.3) or (1.4), +break the plain-text response into +the **protected Branch Key Context Digest** and the plain-text AES-256. + +Compare the **protected Branch Key Context Digest** to the **Branch Key Context Digest**; +if not equal, fail, else, succeed. + +If we go with (1.5), +then we need to use the plain-text AES-256 +to verify the MAC. + +## 1.3 Binding the **Branch Key Context Digest** via KMS Encrypt + +One option is to refactor Branch Key Creation to use `kms:GenerateDataKey` +to get a plain text cryptographic materials. + +This **Branch Key Context Digest** is then concatenated with +the plain-text material in a deterministic fashion. The result of concatenation is then encrypted with KMS Encrypt + +The option to use local entropy instead of `kms:GenerateDataKey` was rejected primarily because +if this local entropy fails to be random then cryptographic integrity of the message/item is compromised. + +## 1.4 KMS Random and then Bind the **Branch Key Context Digest** via KMS Encrypt + +KMS provides the kms:GenerateRandom operation, which allows to generate random data without using a specific KMS key. +This can be useful in situations where you need to generate random data, but don't require access controls provided by KMS keys with key policy. +Unlike operations that use KMS keys, the kms:GenerateRandom operation does not involve any specific KMS key. +As a result, the access control for this operation is only managed through IAM policies, which can either allow or deny the kms:GenerateRandom permission. + +Some customers may prefer to have a separate KMS client just for calling the kms:GenerateRandom operation, +as they can't use key policy for it. However, this approach could lead to a "clunkier" interface, as it would involve managing multiple KMS clients. +So, option 1.4 was rejected. + + +## 1.5 Use Branch Key's cryptographic material in an HMAC on the Branch Key's Metadata and Location + +Rather than appending the **Branch Key Context Digest** to the plain-text AES-256, +we can use the plain-text AES-256 as the key +for a HMAC. + +In this scenario, +the **Branch Key Context Digest** is passed to an HMAC function with the plain-text AES-256; +the result is a `MAC` (Message Authentication Code) which can be included +on the Branch Key Item as binary field. + +**HMAC does not add value**: +The HMAC is created with the plain-text AES-256; +the plain-text AES-256 is avabile to both +Branch Key Store Admins and Branch Key Store Users. + +In contrast to the plain-text AES-256, +`kms:Encrypt` access can be restricted to ONLY +Branch Key Store Admins; +Branch Key Store Users have no need of `kms:Encrypt`. + +Thus, +the option that affords distinction between +Admin and Users are 1.3 & 1.4. + +As such, 1.4 is the recommended path. + +**Both HAMC and 1.4 adds complexity but does not add value**: +To the author's knowledge, +there is no threat mitigated by doing +an HMAC and committing the `mac` +with the plain-text AES-256 +via the `kms:Encrypt` call +that is not mitigated by committing +just the **Branch Key Context Digest**. + +## 1.6 Downsides to Plain-text Commitment + +**Exposure**: +The plain-text AES-256 is now exposed to the Creating Agent, +where as in HV-1 the plain-text AES-256 is never exposed +to the Creating agent. + +However, +the `KeyManagementStrategy` of Encrypt/Decrypt, +introduced by Mutations, +already leaked the plain-text material to Key Store Administrative Agents; +and the `Get*` operations always expose the plain-text material to usage agents. + +Additionally, +conversations with Security Engineers have generally +regarded any plain-text material +access outside of KMS to be equivalent[^1]. +Thus, +considering this exposure a risk is questionable at best. + +**Change of KMS Permissions**: +HV-1 never required `kms:Encrypt` and `kms:GenerateDataKey` permission. +Migrating to HV-2 will thus need a permission change. + +_Note_: `kms:GenerateRandom` permission is required, +but not to any resource (i.e: KMS Key), +only to the calling principle in general. + +**Feature Requests to KMS/LockBox**: +We could also ask KMS or LockBox to consider this use case of +Generate Data Key and Encrypt Payload; +we should not block on that, +but it could be useful for the future. + +**KMS Key/IAM Policies Cannot Evaluate Branch Key Location/Metadata**: +See [Appendix 1](./appendix.md#1-kms-key-admin-policy-downsides-and-rebuttals) and [Appendix 2](./appendix.md#2-mpl-consumer-key-policy-downsides-and-rebuttal). + +## 2 KMS HMAC Key + +Rather than using the Branch Key's KMS Key to protect all the Branch Key's metadata, +we could use a KMS HAMC Key to protect/validate the metadata, +and only the Branch Key's AES-256 would be protected by the Branch Key's KMS Key. + +## 2.1 Branch Key Creation + +MPL Consumers (users of the library), +when creating/versioning/mutation Branch Keys, +would provide two KMS Key ARNs: + +- An HMAC Key ARN (name subject to bike-shedding) that points to a KMS Key with a Key Spec of HMAC_384 +- A KMS Key ARN that points to a KMS Key with a Key Spec of SYMMETRIC_DEFAULT + +The Branch Key's AES-256 can than be created by +a `kms:GenerateDataKeyWithoutPlaintext` request, +with the MPL Consumer supplied Encryption Context (unmodified, "foo": "baz"); +the responses' `CiphertextBlob` is put into a variable, `enc`. + +The HAMC key's ARN is added to the metadata as `kms-hmac-arn`. +All the Branch Key's data, +including the `enc` (so metadata + `enc`) +is then normalized to a byte representation, +which we can call `hmac-input`. + +A `kms:GenerateMac` request is constructed +with the `KeyId` of `kms-hamc-arn`, +the `MacAlgorithm` of `HMAC_SHA_384`, +and `Message` of `hmac-input`; +we will call responses `Mac` the `mac`. + +The `mac` is added to the metadata, +and all of the metadata and the `enc` are written to DynamoDB. + +## 2.2 Getting Branch Keys + +The usage Branch Key Store will need +to be configured with a `hmac-key`, +or probably a list of `hamc-key`s, `hamc-keys`. + +The process for getting the item is then: + +1. Read the item from DDB +2. Ensure the `kms-hmac-arn` is in `hmac-keys`; if not, fail +3. Ensure the `kmsArn` is acceptable to the KMS Configuration; if not, fail +4. re-calculate the `hamc-input` +5. issue a `kms:VerifyMac` request, with `KeyId` of `kms-mac-arn`, `MacAlgorithm` of `HMAC_SHA_384`, `Message` of `hamc-input`, & `Mac` of `mac`; if KMS returns `KMSInvalidMacException`, then the Branch Key has been tampered with, and fail +6. Otherwise, issue a `kms:Decrypt` with `CiphertextBlob` of `enc`, `KeyId` of `kms-arn`, and the Encryption Context +7. If that succeeds, return the plain-text AES-256 as we have been doing + +## 2.3 Cons + +**More Complicated Permissions**: +Customers would need to configure and manage +a KMS HMAC Key, the backing DDB table, & the tenant or default KMS Key(s). +This is only one more KMS Key than they already use, +but it is additional complexity. + +**Additional Web/KMS Request for Gets Complicate Failures**: +Whenever fetching Branch Keys, +two KMS requests MUST succeed: + +- `kms:VerifyMac` +- `kms:Decrypt` + +These SHOULD be serial requests, +or the plain-text material MAY be retrieved +before the metadata has been validated. + +(The library could withhold the plain-text material +until both calls, issued in parallel, succeed, +but then we need to consider memory access/thread safety issues; +it is simpler and safer to ensure the calls are sequential.) + +Web requests transitively fail for any number of reasons; +Crypto Tools will need to introduce errors that differentiate +between a KMS signing key error and KMS symmetric default error, +and we will need to document that for our customers. + +That is effort on both Crypto Tools and it's customers; +HV-1 Branch Keys will fail on one group of conditions, +while HV-2 Branch Keys will fail on a larger group of conditions. + +This challenge could be overcome by a couple of means +(error hierarchies, +re-using existing error types but with additional messaging details, +offering [Requirement 5. Support for operating in a mixed HV-1, HV-2 state]() +as a multi-keyring) +but it will be effort. + +**Additional Web/KMS Request for Gets Increases Latency**: + +The Branch Key Store's `Get*` operations are used by +Amazon Services, and presumably external services, +to service latency sensitive requests. + +While working with such services, +Crypto Tools has observed that the KMS requests +are generally the largest driver of latency. + +An additional KMS request to use Branch Keys is, +potentially, +a significant increase in latency for these customers. + +It is not clear that the KMS HMAC key justifies this cost. + +## 2.4 Pros + +**An Additional Hurdle For Malicious Writers**: +The Branch Key Store/Hierarchy Keyring is the only +"data key caching" solution for Client Side of Encryption (CSE) +of DynamoDB items via the AWS Database Encryption SDK for DynamoDB +(DB-ESDK). + +Traditionally, +CSE is used when the data store is NOT trusted. + +However, +write access to the Branch Key Store's backing table +along with administrative control to any KMS Key is sufficient +for a malicious actor to overwrite a tenant's Active Branch Key, +which will induce any non-strict Branch Key Store to protect +any new data of the tenant with the malicious KMS Key. + +The Branch Key Store is, +for all customers that we know of, +a DynamoDB table. + +The KMS HMAC Key is exclusively managed by the application; +if the application does not want to trust DynamoDB/data base administrators, +but is not the administrators of all the KMS Keys used by the Key Store +(i.e: multi-tenant) +and does not want to utilize strict Branch Key Stores +(as they do not scale well with many KMS Keys), +they can trust their KMS HMAC Key and NOT DynamoDB/the database. + +This is a very strong argument FOR using a KMS HMAC Key, +and potentially justifies the additional latency cost, +error complications, +and development complexities. + +**Static KMS Symmetric Default Permissions**: +If Crypto Tools requires the usage of a KMS HMAC Key, +then we can keep the KMS operations that +use the KMS Symmetric Default Key as they are in HV-1. + +This simplifies customers who want to transition from HV-1 to HV-2. + +# 3 Expand System Key/Double Encryption + +This option is much like [2 KMS HMAC Key](#2-kms-hmac-key), +but it allows the MPL Consumers to write +KMS Key/IAM Policies constraints against +the Branch Key's Metadata. + +## 3.1 Branch Key Creation + +MPL Consumers (users of the library), +when creating/versioning/mutation of Branch Keys, +would provide two KMS Key ARNs: + +- A System Key ARN (name subject to bike-shedding) that points to a KMS Key with a Key Spec of SYMMETRIC_DEFAULT +- A KMS Key ARN that points to a KMS Key with a Key Spec of SYMMETRIC_DEFAULT + +The Branch Key's AES-256 can than be created by +a `kms:GenerateDataKeyWithoutPlaintext` request against the KMS Key ARN, +with the MPL Consumer supplied Encryption Context (unmodified, "foo": "baz"); +the responses' `CiphertextBlob` is put into a variable, `enc`. + +`system-key-arn` is added to the Branch Key's Metadata. + +All of the Branch Key's Metadata is then put into the `EncryptionContext` of a +`kms:Encrypt` request against the `system-key-arn` with no plain-text. + +The resulting `CiphertextBlob` is added +to the Branch Key Item as `aad`, +and the Branch Key is written to storage as normal. + +## 3.2 Getting Branch Keys + +The usage Branch Key Store will need +to be configured with a `system-kms-arn`, +or probably a list of `system-kms-arn`s, `system-kms-arns`. + +The process for getting the item is then: + +1. Read the item from DDB +2. Ensure the `system-kms-arn` is in `system-kms-arns`; if not, fail +3. Ensure the `kmsArn` is acceptable to the KMS Configuration; if not, fail +4. issue a `kms:Decrypt` request, with `KeyId` of `system-kms-arn`, `EncryptionContext` of the Branch Key's Metadata, `CiphertextBlob` of `aad`; if KMS returns `KMSInvalidCiphertextException`, then the Branch Key has been tampered with, and fail +5. Otherwise, issue a `kms:Decrypt` with `CiphertextBlob` of `enc`, `KeyId` of `kms-arn`, and the Encryption Context +6. If that succeeds, return the plain-text AES-256 as we have been doing + +## 3.3 Cons + +Everything in 2.3 applies here, +modulo that the KMS requests are both `kms:Decrypt`. + +## 3.4 Pros + +Everything in 2.4 applies here, +AND we allow MPL Consumers to write KMS Key/IAM Policies against +the Branch Key Metadata. + +# 4 No Protection + +Do not protect the Branch Key Metadata. + +## 4.1 Pros + +None. + +## 4.2 Cons + +**A new threat model**: +We would need to re-write the Branch Key Store's +threat model basically from scratch, +likely accepting a number of confused deputy threats. + +We would then need to get AppSec sign off for this +more vulnerable iteration (hint: Sanders and Filip were not keen) +and then document this for our customers, +which would require extensive documentation work. + +# 5 Binding the **Branch Key Context Digest** via KMS Encryption Context + +We could put the **Branch Key Context Digest** into the KMS Encryption Context. + +## Pro and Con + +This lets us use `kms:GenerateDataKeyWithoutPlaintext`. +But it violates the Requirement 2. +Given the feedback we have been given from PEs across AWS, +including KMS', +we should not violate Requirement 2. From 05a9cf7e87996289d3dc0e36e93228ec8b6e8bd1 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Mon, 30 Jun 2025 11:43:46 -0700 Subject: [PATCH 025/116] formatting: --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 3e47311c..57b3007f 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -821,7 +821,7 @@ The `type` attribute MUST stores the branch key version formatted like `"branch: 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 includes a key `type` and the value MUST be `"beacon:ACTIVE"`. The Beacon key branch key context MUST NOT have a `version` attribute. ## Encryption Context From 95b70f3ba2e29ee45b78ab7b38d28af987b194b4 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Tue, 1 Jul 2025 13:21:01 -0700 Subject: [PATCH 026/116] auto commit --- .../DesignQuestion.md | 11 +- .../background.md | 333 ++++++++++++++++++ 2 files changed, 338 insertions(+), 6 deletions(-) create mode 100644 changes/2025-06-30_branch_keys_version_2/background.md diff --git a/changes/2025-06-30_branch_keys_version_2/DesignQuestion.md b/changes/2025-06-30_branch_keys_version_2/DesignQuestion.md index 15051ea2..162e8bfc 100644 --- a/changes/2025-06-30_branch_keys_version_2/DesignQuestion.md +++ b/changes/2025-06-30_branch_keys_version_2/DesignQuestion.md @@ -62,7 +62,7 @@ to verify the MAC. ## 1.3 Binding the **Branch Key Context Digest** via KMS Encrypt -One option is to refactor Branch Key Creation to use `kms:GenerateDataKey` +One option is to refactor Branch Key Creation to use `kms:GenerateDataKey` to get a plain text cryptographic materials. This **Branch Key Context Digest** is then concatenated with @@ -73,16 +73,15 @@ if this local entropy fails to be random then cryptographic integrity of the mes ## 1.4 KMS Random and then Bind the **Branch Key Context Digest** via KMS Encrypt -KMS provides the kms:GenerateRandom operation, which allows to generate random data without using a specific KMS key. +KMS provides the kms:GenerateRandom operation, which allows to generate random data without using a specific KMS key. This can be useful in situations where you need to generate random data, but don't require access controls provided by KMS keys with key policy. -Unlike operations that use KMS keys, the kms:GenerateRandom operation does not involve any specific KMS key. -As a result, the access control for this operation is only managed through IAM policies, which can either allow or deny the kms:GenerateRandom permission. +Unlike operations that use KMS keys, the kms:GenerateRandom operation does not involve any specific KMS key. +As a result, the access control for this operation is only managed through IAM policies, which can either allow or deny the kms:GenerateRandom permission. -Some customers may prefer to have a separate KMS client just for calling the kms:GenerateRandom operation, +Some customers may prefer to have a separate KMS client just for calling the kms:GenerateRandom operation, as they can't use key policy for it. However, this approach could lead to a "clunkier" interface, as it would involve managing multiple KMS clients. So, option 1.4 was rejected. - ## 1.5 Use Branch Key's cryptographic material in an HMAC on the Branch Key's Metadata and Location Rather than appending the **Branch Key Context Digest** to the plain-text AES-256, diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md new file mode 100644 index 00000000..43ed59df --- /dev/null +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -0,0 +1,333 @@ +[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved." +[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0" + +# Customers should control encryption context + +# Definitions + +## Conventions used in this document + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + +## HV-1 + +The Branch Key Store's Branch Keys are designated as `"hierarchy-version" : "1"`. + +This document proposes changes to theses Branch Keys; +when HV-1 is written, +we mean a Branch Key Item written by the Branch Key Store v0.2.0 to v0.7.0. + +## Branch Key's Cryptographic Material + +Cryptographic material (AES-256 bit key) generated and protected by KMS. + +## Branch Key's Properities + +These three values are stored on every +Active, +Version, +and Beacon Key Item in the Branch Key Store's Storage. + +They are also present in the KMS Encryption Context. + +```json +"kms-arn" : "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", +"create-time" : "2023-06-03T19:03:29.358Z", +"hierarchy-version" : "1", +``` + +The Active has an additional field: + +```json +"version": "branch:version:83eec007-5659-4554-bf11-699b90f41ac6" +``` + +## Branch Key's Location + +These two values are stored on every +Active, +Version, +and Beacon Key Item in the Branch Key Store's Storage. + +For Active: + +```json +"branch-key-id" : "bbb9baf1-03e6-4716-a586-6bf29995314b", +"type" : "branch:ACTIVE" +``` + +For Version: + +```json +"branch-key-id" : "bbb9baf1-03e6-4716-a586-6bf29995314b", +"type": "branch:version:83eec007-5659-4554-bf11-699b90f41ac6" +``` + +For Beacon: + +```json +"branch-key-id" : "bbb9baf1-03e6-4716-a586-6bf29995314b", +"type": "beacon:ACTIVE" +``` + +However, +the Logical Key Store Name is also included in the KMS Encryption Context. + +```json +"branch-key-id" : "bbb9baf1-03e6-4716-a586-6bf29995314b", +"type" : "branch:ACTIVE", +"tablename": "KeyStore" +``` + +These three values describe where the Branch Key is stored; however, the tablename is a logical description, not a physical description. +At this time, no cryptography binds the Branch Key to the physical table. + +```json +"branch-key-id" : "bbb9baf1-03e6-4716-a586-6bf29995314b", +"tablename": "KeyStore" +``` + +These two values label the Branch Key, seperating it from all other Branch Keys. + +## Branch Key's Encryption Context + +These values are determined by the Branch Key Creator +or last Branch Key Mutator. + +In DynamoDB and in KMS Encryption Requests, +their keys are prefixed with `aws-crypto-ec:`. + +```json +"aws-crypto-ec:department" : "admin" +``` + +However, +when returned to the requesters of the Branch Key Store's +`Get*Key*` operations, +the prefix is removed. + +## Branch Key's Context + +The union of the Branch Key's: + +- Properities +- Location (including logical key store name) +- Encryption Context + +# Background + +The current Branch Key Store's Branch Key's use KMS Encryption Context +to cryptographically bind the Branch Key's cryptographic material to +the Branch Key's Context. + +This cryptographic binding mitigates a number of threats around +storing the Branch Keys +and is vital to the safe usage of the Hierarchal Keyring. + +However, +it is not clear that this is the best use of KMS Encryption Context, +as it interferes with customers ability to use KMS Key Policies to +constrain Key Usage. + +Further more, +Encryption Context evaluation can be customized by the calling principles authorization; +KMS Key Grants can have restricted but unique conditions. + +Many potential Branch Key Customers are prevented from using +the Hierarchy Keyring, +as they have pre-existing Key Policies with their tenants +that cannot be met if the KMS Encryption Context is populated +by the Branch Key's 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. + +# Requirements + +1. Branch Key's Context be cryptographically bound to the Branch Key's Cryptographic Material + +2. Branch Key's Encryption Context, untransformed in any way, is the KMS Encryption Context + +3. Support for all of Behaviors of the current Branch Key Store (Create, Version, Get\*) + +# Out of Scope + +- Abstracting away from KMS +- Supporting any Branch Key protection Scheme via the DB-ESDK, much like the DDBEC's MetaStore. + +## Why not Abstract away from KMS + +Over the past year, +Crypto Tools has spent a significant amount of our time +supporting services integrating with KMS for multi-tenant applications. + +While we MAY eventually want to support GCP or Azure, +we MUST focus on the fasting growing customer base we have; +AWS Services and Software-as-a-service providers integrating with KMS. + +## Why not the MetaStore approach? + +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. + +However, our customers have complained that the DB-ESDK is complicated; +using the DB-ESDK to protect the materials used by the DB-ESDK is NOT +a step towards simplification. + +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. + +# Design Questions + +## 1 How can the Branch Key's Context be protected without using KMS EC? + +See [DesignQuestion.md](./DesignQuestion.md). + +## 2 How are we going to offer operation in a mixed mode? + +UPDATE: 2.1 was rejected. +There will be no Policy (2.2). + +### 2.1 `hierarchy-version-policy` + +Much like [Key Commitment](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#key-commitment), +I suggest we introduce a policy that +would allow for mixed usage or restricting to one or the other. + +Something like `hierarchy-version-policy`: + +- ALLOW_V1 +- ALLOW_V2 +- ALLOW_V1_OR_V2 +- ANY + +This policy would be part of (all) Branch Key Store configuration. + +(all: Branch Key Store, any future Branch Key Store Usage client.) + +This allows our customers to +restrict to one KMS Encryption Context +experience or another. + +The effort to implement and test this is very low, +relative to other code paths in this effort. + +### 2.2 Do Nothing + +UPDATE: We are going with Do Nothing + +There is no immediate customer demand for a policy like this. +In general, +the Branch Key in the table, +in combination with KMS, +the authority of it's treatment. + +However, +given the low effort required to implement/support this, +and the aid it gives our customers in having +a consistent KMS Encryption Context experience, +I suggest we implement the policy. + +### 2.3 Pros of 2.1 + +**Update Readers, than Writers**: +To use HV-2, +customers already using the H-Keyring will need +to update their readers before they start creating +or mutating Branch Keys to HV-2. + +i.e: They need to update their readers before they update their writers. + +This alone is justification for the policy. + +**Consistent KMS Encryption Context**: +[Much has been said for](https://quip-amazon.com/rc9CARWxsCTT#LHG9AA64tJh) and [against the Encryption Context](https://quip-amazon.com/l5d8AHH0hgZs/Encryption-Context-Exposure-by-Dynamo-ESDK) +witnessed by KMS in HV-1. + +The arguments for the HV-1 Encryption Context suggest +users SHOULD be able to restrict their Branch Key Store clients +to a HV-1 such that they know any IAM or KMS Key Policies +they created that depend on HV-1's Encryption Context +are still valid. + +### 2.4 Cons + +**Additional Development work and documentation**: +Nothing is free; +we would need to implement, document, test, and maintain this policy. + +Still, +the migration benefit justifies this cost. + +## 3 Branch Key Creation + +UPDATE: The team decided that the Branch Key Store would create and version both HV-1 and HV-2 BKs. +UPDATE: The team changed their mind; the Branch Key Store WILL support HV-2 Branch Key Creation, via a flag. + +Customers MUST be able to chose which `hierarchy-version` +new Branch Keys are created with. + +The question is what should the UX be. + +### 3.1 Specify the `hierarchy-version` at Creation + +Currently, our library has one Branch Key Creation operations: + +- `BranchKeyStore#CreateKey` + +To this operation, +we could add a flag that dictates the `hierarchy-version` to be created with. + +If that flag conflicts with `hierarchy-version-policy`, +then FAIL. + +Otherwise, respect the flag. + +**Plumbing through `GenerateRandom`**: +UPDATE: `kms:GenerateDataKey` closed this negative consequence. +We will had to add an optional `AwsKms` input +to supply the plain-text data key. + +### 3.2 Follow the Configuration + +This does not work if the configuration is `ALLOW\_V1\_OR_V2`; +this is not recommended. + +### 3.3 New Operation or Client + +We could leave the old Branch Key Store alone, +and introduce a new Branch Key Store V2. + +The UX advantage here is that we can introduce new error types +without breaking customers. + +For example, +the creation of the `hierarchy-version-policy` implies +that we will need an error type for rejecting a Branch Key +that does not match. + +Particularly if we went down the additional KMS approaches (1.2, 1.3), +new error types will need to be created to represent +failures from the additional KMS key. + +But we have committed to 1.4; +this limits the failure modes/additional errors +to the point that I do not think new client +or operation is needed. + +### 3.4 Author's conclusion + +Unless someone can think of something else, +3.1. + +## 4 Branch Key Versioning (Rotation) + +UPDATE: The team elected for 3.5; we will Mirror 3.5. +(BKS can VersionKey HV-1 or HV-2). \ No newline at end of file From e8f57841a1bb048a87753afc087f8412b3d717e1 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Tue, 1 Jul 2025 13:44:45 -0700 Subject: [PATCH 027/116] auto commit --- changes/2025-06-30_branch_keys_version_2/background.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 43ed59df..01c22d1e 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -330,4 +330,4 @@ Unless someone can think of something else, ## 4 Branch Key Versioning (Rotation) UPDATE: The team elected for 3.5; we will Mirror 3.5. -(BKS can VersionKey HV-1 or HV-2). \ No newline at end of file +(BKS can VersionKey HV-1 or HV-2). From 02ea9a30af0b4459a6c7ecf90be8263ac26a91a1 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Tue, 1 Jul 2025 14:39:56 -0700 Subject: [PATCH 028/116] Initial empty commit --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 3e47311c..57b3007f 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -821,7 +821,7 @@ The `type` attribute MUST stores the branch key version formatted like `"branch: 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 includes a key `type` and the value MUST be `"beacon:ACTIVE"`. The Beacon key branch key context MUST NOT have a `version` attribute. ## Encryption Context From 9635b60c6ad1b574248efb0ea36aa583b35fea7a Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Tue, 1 Jul 2025 14:41:59 -0700 Subject: [PATCH 029/116] auto commit --- changes/2025-06-30_branch_keys_version_2/DesignQuestion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/DesignQuestion.md b/changes/2025-06-30_branch_keys_version_2/DesignQuestion.md index 162e8bfc..bfae4603 100644 --- a/changes/2025-06-30_branch_keys_version_2/DesignQuestion.md +++ b/changes/2025-06-30_branch_keys_version_2/DesignQuestion.md @@ -5,7 +5,7 @@ # Definitions -See [Definitions](./background#Definitions). +See [Definitions](./background.md#definitions). # 1 Plain-text Commitment instead of KMS Encryption Context From 686f21cf45646841bb2cf0df182d148bd0ee2c24 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Tue, 1 Jul 2025 14:44:50 -0700 Subject: [PATCH 030/116] auto commit --- changes/2025-06-30_branch_keys_version_2/background.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 01c22d1e..4d0c65bb 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -248,9 +248,6 @@ i.e: They need to update their readers before they update their writers. This alone is justification for the policy. **Consistent KMS Encryption Context**: -[Much has been said for](https://quip-amazon.com/rc9CARWxsCTT#LHG9AA64tJh) and [against the Encryption Context](https://quip-amazon.com/l5d8AHH0hgZs/Encryption-Context-Exposure-by-Dynamo-ESDK) -witnessed by KMS in HV-1. - The arguments for the HV-1 Encryption Context suggest users SHOULD be able to restrict their Branch Key Store clients to a HV-1 such that they know any IAM or KMS Key Policies From ebac8ac70515ebbbb390559bf510ded8659475c1 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Tue, 1 Jul 2025 14:51:27 -0700 Subject: [PATCH 031/116] auto commit --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 57b3007f..6b8fe76e 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -831,7 +831,7 @@ This section describes how the AWS KMS encryption context is built. 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). +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. ### ACTIVE Encryption Context From a2d8a48c08116f13c906ebc8feab3444a4294968 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 2 Jul 2025 11:05:24 -0700 Subject: [PATCH 032/116] auto commit --- .../{DesignQuestion.md => designquestion.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changes/2025-06-30_branch_keys_version_2/{DesignQuestion.md => designquestion.md} (100%) diff --git a/changes/2025-06-30_branch_keys_version_2/DesignQuestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md similarity index 100% rename from changes/2025-06-30_branch_keys_version_2/DesignQuestion.md rename to changes/2025-06-30_branch_keys_version_2/designquestion.md From 01a22e600c2a6cf674a4959761be12492e5c65f9 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Wed, 2 Jul 2025 11:08:14 -0700 Subject: [PATCH 033/116] Update changes/2025-06-30_branch_keys_version_2/background.md --- changes/2025-06-30_branch_keys_version_2/background.md | 1 + 1 file changed, 1 insertion(+) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 4d0c65bb..e50af961 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -266,6 +266,7 @@ the migration benefit justifies this cost. ## 3 Branch Key Creation UPDATE: The team decided that the Branch Key Store would create and version both HV-1 and HV-2 BKs. + UPDATE: The team changed their mind; the Branch Key Store WILL support HV-2 Branch Key Creation, via a flag. Customers MUST be able to chose which `hierarchy-version` From ef6d1dcac0efc259b818fd752a661e5c5d327396 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Wed, 2 Jul 2025 11:11:28 -0700 Subject: [PATCH 034/116] Update branch-key-store.md --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 6b8fe76e..1e93c9c9 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -10,7 +10,7 @@ ### Changelog - 0.8.0 - - Hierarchy Version 2 + - [Hierarchy Version 2](../changes/2025-06-30_branch_keys_version_2/background.md) - 0.7.1 - Branch key creation only uses customer input - 0.7.0 From e8d54f21e3ac03708ebd7d993e916b8e9abd67eb Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 9 Jul 2025 14:40:33 -0700 Subject: [PATCH 035/116] auto commit --- .../designquestion.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index bfae4603..22b340f6 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -270,20 +270,6 @@ The Branch Key Store/Hierarchy Keyring is the only of DynamoDB items via the AWS Database Encryption SDK for DynamoDB (DB-ESDK). -Traditionally, -CSE is used when the data store is NOT trusted. - -However, -write access to the Branch Key Store's backing table -along with administrative control to any KMS Key is sufficient -for a malicious actor to overwrite a tenant's Active Branch Key, -which will induce any non-strict Branch Key Store to protect -any new data of the tenant with the malicious KMS Key. - -The Branch Key Store is, -for all customers that we know of, -a DynamoDB table. - The KMS HMAC Key is exclusively managed by the application; if the application does not want to trust DynamoDB/data base administrators, but is not the administrators of all the KMS Keys used by the Key Store From e768f46f8fa1f8c10be80376dfef5f30639698b4 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 09:00:52 -0700 Subject: [PATCH 036/116] Update changes/2025-06-30_branch_keys_version_2/background.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/background.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index e50af961..bbea19a6 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -141,10 +141,6 @@ as they have pre-existing Key Policies with their tenants that cannot be met if the KMS Encryption Context is populated by the Branch Key's 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. # Requirements From 0481ed31418c673455604eae8c30d3288f20c100 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 09:01:20 -0700 Subject: [PATCH 037/116] Update changes/2025-06-30_branch_keys_version_2/background.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/background.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index bbea19a6..106d9e6a 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -167,9 +167,12 @@ AWS Services and Software-as-a-service providers integrating with KMS. ## Why not the MetaStore approach? -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. However, our customers have complained that the DB-ESDK is complicated; using the DB-ESDK to protect the materials used by the DB-ESDK is NOT From 4aa2261f0ec461f0ad9f195db25f8bbdaeec22eb Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 09:04:02 -0700 Subject: [PATCH 038/116] Update changes/2025-06-30_branch_keys_version_2/background.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/background.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 106d9e6a..63172a45 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -175,7 +175,7 @@ as the MetaStore was an interface that exposes the full breadth of DDBEC functio This gives customers significant freedom on what data is bound to a Branch Key Item's material and how that binding is facilitated. However, our customers have complained that the DB-ESDK is complicated; -using the DB-ESDK to protect the materials used by the DB-ESDK is NOT +using the DB-ESDK to protect the materials used by the DB-ESDK and the ESDK is NOT a step towards simplification. While such a feature MAY provide the greatest flexibility to From db3300d7a1c64d38892557d9da89c02fb0c75d03 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 09:04:20 -0700 Subject: [PATCH 039/116] Update changes/2025-06-30_branch_keys_version_2/background.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/background.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 63172a45..716e4537 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -96,7 +96,7 @@ These two values label the Branch Key, seperating it from all other Branch Keys. These values are determined by the Branch Key Creator or last Branch Key Mutator. -In DynamoDB and in KMS Encryption Requests, +In DynamoDB and in KMS Encryption Requests for HV-1, their keys are prefixed with `aws-crypto-ec:`. ```json From a48aabf4804fc8952d8dcbb07677f832431dfa60 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 09:04:35 -0700 Subject: [PATCH 040/116] Update changes/2025-06-30_branch_keys_version_2/background.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/background.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 716e4537..9c969f47 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -118,7 +118,7 @@ The union of the Branch Key's: # Background -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 to cryptographically bind the Branch Key's cryptographic material to the Branch Key's Context. From 02de72b8c879de874df919934d52a3aa7fab0dfe Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 09:05:08 -0700 Subject: [PATCH 041/116] Update changes/2025-06-30_branch_keys_version_2/background.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/background.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 9c969f47..199348c2 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -182,6 +182,9 @@ 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. + # Design Questions From bbe76a8acf9a212c62a8d5352d6dcf75a361799f Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 09:05:37 -0700 Subject: [PATCH 042/116] Update changes/2025-06-30_branch_keys_version_2/background.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/background.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 199348c2..57993817 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -200,7 +200,7 @@ There will be no Policy (2.2). ### 2.1 `hierarchy-version-policy` Much like [Key Commitment](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#key-commitment), -I suggest we introduce a policy that +we could introduce a policy that would allow for mixed usage or restricting to one or the other. Something like `hierarchy-version-policy`: From 83bff87711064e21b972fd1db22ce852fb9b375f Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 09:05:58 -0700 Subject: [PATCH 043/116] Update changes/2025-06-30_branch_keys_version_2/background.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/background.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 57993817..534c38f2 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -283,7 +283,7 @@ Currently, our library has one Branch Key Creation operations: - `BranchKeyStore#CreateKey` To this operation, -we could add a flag that dictates the `hierarchy-version` to be created with. +we add a flag that dictates the `hierarchy-version` to be created with. If that flag conflicts with `hierarchy-version-policy`, then FAIL. From 896340449c8f362e05d8858af8acc6661cc522df Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Mon, 14 Jul 2025 09:08:51 -0700 Subject: [PATCH 044/116] auto commit --- changes/2025-06-30_branch_keys_version_2/background.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 534c38f2..a8b83c00 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -286,7 +286,7 @@ To this operation, we add a flag that dictates the `hierarchy-version` to be created with. If that flag conflicts with `hierarchy-version-policy`, -then FAIL. +then FAIL (update: `hierarchy-version-policy` was rejected, see [section 2](#2-how-are-we-going-to-offer-operation-in-a-mixed-mode)). Otherwise, respect the flag. From 4eafe3d44c78fda3aa525f6284c801e39224cfee Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 09:13:23 -0700 Subject: [PATCH 045/116] Update changes/2025-06-30_branch_keys_version_2/background.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/background.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index a8b83c00..382c953f 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -292,8 +292,6 @@ Otherwise, respect the flag. **Plumbing through `GenerateRandom`**: UPDATE: `kms:GenerateDataKey` closed this negative consequence. -We will had to add an optional `AwsKms` input -to supply the plain-text data key. ### 3.2 Follow the Configuration From d538a41e9ac920db2716855480b904aaff71d713 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 09:14:13 -0700 Subject: [PATCH 046/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 22b340f6..06b9639d 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -1,7 +1,7 @@ [//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved." [//]: # "SPDX-License-Identifier: CC-BY-SA-4.0" -# How can the Branch Key's Metadata be protected without using KMS EC? +# How can the Branch Key's Context be protected without using KMS EC? # Definitions From a341b0d013c066234c12e74473ab327a2de972ed Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 09:15:15 -0700 Subject: [PATCH 047/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- .../2025-06-30_branch_keys_version_2/designquestion.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 06b9639d..09718daf 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -22,11 +22,10 @@ The KMS RSA Keyring, in `OnEncrypt`, > 2. Taking the SHA-384 Digest of this concatenation. -Except rather than working with the encryption context -from the encryption materials, -HV-2 will serialize the Branch Key's -Metadata according to the -[encryption context serialization specification](../../framework/../framework/structures.md#serialization), +Adapting this same pattern to Branch Keys, +rather than working with the encryption context from the encryption materials, +HV-2 will serialize the Branch Key's Context according +to the [encryption context serialization specification](../../framework/../framework/structures.md#serialization), and then take a SHA-384 Digest of these bytes, creating the Branch Key's **Branch Key Context Digest**. From 72d95fb8e1b0afa73af5af2b17b804ddf9f8b8dd Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 09:15:50 -0700 Subject: [PATCH 048/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 09718daf..0c042212 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -33,7 +33,7 @@ This **Branch Key Context Digest** is 48 bytes long, and MUST be bound to the Branch Key Cryptographic Materials. 1.3 & 1.4 talk about options that use KMS Encrypt to protect the **Branch Key Context Digest**; -without KMS Encrypt access, +thus, without KMS Encrypt access, an actor cannot modify the **Branch Key Context Digest**. 1.5 considers a local HMAC operation, From a16bcbb6dff279b0ddb0b6d1e9bc1e90082d7869 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 11:10:19 -0700 Subject: [PATCH 049/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 0c042212..59f2764e 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -72,7 +72,7 @@ if this local entropy fails to be random then cryptographic integrity of the mes ## 1.4 KMS Random and then Bind the **Branch Key Context Digest** via KMS Encrypt -KMS provides the kms:GenerateRandom operation, which allows to generate random data without using a specific KMS key. +KMS provides the kms:GenerateRandom operation, which generates random bytes without using a specific KMS key. This can be useful in situations where you need to generate random data, but don't require access controls provided by KMS keys with key policy. Unlike operations that use KMS keys, the kms:GenerateRandom operation does not involve any specific KMS key. As a result, the access control for this operation is only managed through IAM policies, which can either allow or deny the kms:GenerateRandom permission. From d853d8f061f480305546992286e7c543f9799f01 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 11:10:46 -0700 Subject: [PATCH 050/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 59f2764e..3cc0f797 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -92,7 +92,7 @@ the **Branch Key Context Digest** is passed to an HMAC function with the plain-t the result is a `MAC` (Message Authentication Code) which can be included on the Branch Key Item as binary field. -**HMAC does not add value**: +**HMAC does not add value compared to a protected digest**: The HMAC is created with the plain-text AES-256; the plain-text AES-256 is avabile to both Branch Key Store Admins and Branch Key Store Users. From 55d690f89adff73be2735c9401d062524c3e566f Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 11:11:22 -0700 Subject: [PATCH 051/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 3cc0f797..590d8872 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -133,7 +133,7 @@ and the `Get*` operations always expose the plain-text material to usage agents. Additionally, conversations with Security Engineers have generally regarded any plain-text material -access outside of KMS to be equivalent[^1]. +access outside of KMS to be equivalent. Thus, considering this exposure a risk is questionable at best. From 8ed6bfe6b774b216529e282ea0d04a5969f00558 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 11:33:25 -0700 Subject: [PATCH 052/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 590d8872..05fa84c2 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -65,7 +65,8 @@ One option is to refactor Branch Key Creation to use `kms:GenerateDataKey` to get a plain text cryptographic materials. This **Branch Key Context Digest** is then concatenated with -the plain-text material in a deterministic fashion. The result of concatenation is then encrypted with KMS Encrypt +the plain-text material in a deterministic fashion. +The result of concatenation is then encrypted with KMS Encrypt. The option to use local entropy instead of `kms:GenerateDataKey` was rejected primarily because if this local entropy fails to be random then cryptographic integrity of the message/item is compromised. From d3100a938717b7fe42398d87812410051262d0c5 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 11:33:48 -0700 Subject: [PATCH 053/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 05fa84c2..47e28011 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -131,7 +131,7 @@ introduced by Mutations, already leaked the plain-text material to Key Store Administrative Agents; and the `Get*` operations always expose the plain-text material to usage agents. -Additionally, +However, conversations with Security Engineers have generally regarded any plain-text material access outside of KMS to be equivalent. From 0593bdbfafa2c232b03dd1cd1fc4347d082d432c Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 11:34:30 -0700 Subject: [PATCH 054/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 47e28011..569e7cdc 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -69,7 +69,10 @@ the plain-text material in a deterministic fashion. The result of concatenation is then encrypted with KMS Encrypt. The option to use local entropy instead of `kms:GenerateDataKey` was rejected primarily because -if this local entropy fails to be random then cryptographic integrity of the message/item is compromised. +if this local entropy fails to be random then cryptographic integrity of +ALL the messages/items protected by the Branch Key Item is compromised. +[//]: # "TODO: Detail more of the GDK vs Local Entropy discussion" + ## 1.4 KMS Random and then Bind the **Branch Key Context Digest** via KMS Encrypt From 865c3ed44e5ff95a15e4cff48920e894fbc228f7 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 11:35:12 -0700 Subject: [PATCH 055/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 1 - 1 file changed, 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 569e7cdc..209ca982 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -77,7 +77,6 @@ ALL the messages/items protected by the Branch Key Item is compromised. ## 1.4 KMS Random and then Bind the **Branch Key Context Digest** via KMS Encrypt KMS provides the kms:GenerateRandom operation, which generates random bytes without using a specific KMS key. -This can be useful in situations where you need to generate random data, but don't require access controls provided by KMS keys with key policy. Unlike operations that use KMS keys, the kms:GenerateRandom operation does not involve any specific KMS key. As a result, the access control for this operation is only managed through IAM policies, which can either allow or deny the kms:GenerateRandom permission. From 9858b491931909e367da0559b35ac5447324f111 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 11:36:03 -0700 Subject: [PATCH 056/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- .../designquestion.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 209ca982..1356dcee 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -80,8 +80,17 @@ KMS provides the kms:GenerateRandom operation, which generates random bytes with Unlike operations that use KMS keys, the kms:GenerateRandom operation does not involve any specific KMS key. As a result, the access control for this operation is only managed through IAM policies, which can either allow or deny the kms:GenerateRandom permission. -Some customers may prefer to have a separate KMS client just for calling the kms:GenerateRandom operation, -as they can't use key policy for it. However, this approach could lead to a "clunkier" interface, as it would involve managing multiple KMS clients. +Multi-tenant Branch Key Store users +MAY have an obligation to use +tenant specific credentials or IAM roles to access a tenant specific KMS Key. +However, these credentials or IAM roles are unlikely to grant `kms:GenerateRandom` permission, +as it is not related to a KMS Key. +Thus, +these multi-tenant users would need a separate KMS client, +which would use non-tenant related credentials or IAM role. +This approach leads to a "clunkier" interface, +as it involves managing more KMS clients. +Hence, Option 1.4 is rejected. So, option 1.4 was rejected. ## 1.5 Use Branch Key's cryptographic material in an HMAC on the Branch Key's Metadata and Location From 752909992d6e910ec12921889ee7e9c2f16c4dfe Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 11:36:23 -0700 Subject: [PATCH 057/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 1 - 1 file changed, 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 1356dcee..d837e1d9 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -91,7 +91,6 @@ which would use non-tenant related credentials or IAM role. This approach leads to a "clunkier" interface, as it involves managing more KMS clients. Hence, Option 1.4 is rejected. -So, option 1.4 was rejected. ## 1.5 Use Branch Key's cryptographic material in an HMAC on the Branch Key's Metadata and Location From bc6c700871ebb4b6089dd1361b1557a6318c0a87 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 11:37:12 -0700 Subject: [PATCH 058/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index d837e1d9..21bed7d5 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -119,7 +119,7 @@ Admin and Users are 1.3 & 1.4. As such, 1.4 is the recommended path. -**Both HAMC and 1.4 adds complexity but does not add value**: +**Doing both HAMC and a "protected digest" adds complexity but does not add value**: To the author's knowledge, there is no threat mitigated by doing an HMAC and committing the `mac` From 47d1cdc8b1f1779a9aa2eb4ebcbb1a4a1a3bbbb1 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 11:37:24 -0700 Subject: [PATCH 059/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 21bed7d5..64be0589 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -117,7 +117,7 @@ Thus, the option that affords distinction between Admin and Users are 1.3 & 1.4. -As such, 1.4 is the recommended path. +As such, 1.3 is the recommended path. **Doing both HAMC and a "protected digest" adds complexity but does not add value**: To the author's knowledge, From 2b2873535a4f51d7eadc0d5834134365712acfbc Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 11:57:51 -0700 Subject: [PATCH 060/116] Update changes/2025-06-30_branch_keys_version_2/designquestion.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/designquestion.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index 64be0589..b92ca853 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -135,11 +135,6 @@ The plain-text AES-256 is now exposed to the Creating Agent, where as in HV-1 the plain-text AES-256 is never exposed to the Creating agent. -However, -the `KeyManagementStrategy` of Encrypt/Decrypt, -introduced by Mutations, -already leaked the plain-text material to Key Store Administrative Agents; -and the `Get*` operations always expose the plain-text material to usage agents. However, conversations with Security Engineers have generally From 9e4c9aae9972ad20803dea164d5a393de27f4163 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 12:06:58 -0700 Subject: [PATCH 061/116] Update framework/branch-key-store.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 1e93c9c9..7f550888 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -784,7 +784,7 @@ This operation MUST return the constructed [beacon key materials](./structures.m ## Branch Key Context -Branch Key Context is a key value pair that can contain additional contextual information about the data. +Branch Key Context is a set of key value pairs (a Map) that contain contextual information about the Branch Key Item. This section describes how Branch Key Context is built from an [encrypted hierarchical key](./key-store/key-storage.md#encryptedhierarchicalkey). The following branch key context keys are shared: From 3ee3a0cf4dc2a7a571e28c8afa8f33334d5764b8 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 12:08:56 -0700 Subject: [PATCH 062/116] Update framework/branch-key-store.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 7f550888..0c42b8fa 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -804,7 +804,7 @@ The following branch key context keys are shared: The ACTIVE branch key is a copy of the DECRYPT_ONLY with the same `version`. It is structured slightly differently so that the active version can be accessed quickly. -In addition to the [branch key context](#encryption-context): +In addition to the [branch key context](#branch-key-context): The ACTIVE branch key context value of the `type` attribute MUST equal to `"branch:ACTIVE"`. The ACTIVE branch key context MUST have a `version` attribute. From d827b211fbada386ac95beec25fa41a6d76b53f5 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 12:12:46 -0700 Subject: [PATCH 063/116] Update framework/branch-key-store.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 0c42b8fa..4ee30395 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -822,7 +822,7 @@ The `type` attribute MUST stores the branch key version formatted like `"branch: 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. +The Beacon key branch key context MUST NOT have a `version` key. ## Encryption Context From 25c5b20e7ac0ba4baa46c390bb0dd69099cd2d01 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 12:14:12 -0700 Subject: [PATCH 064/116] Update framework/branch-key-store.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- framework/branch-key-store.md | 1 - 1 file changed, 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 4ee30395..6ea582b1 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -785,7 +785,6 @@ This operation MUST return the constructed [beacon key materials](./structures.m ## Branch Key Context Branch Key Context is a set of key value pairs (a Map) that contain contextual information about the Branch Key Item. -This section describes how Branch Key Context is built from an [encrypted hierarchical key](./key-store/key-storage.md#encryptedhierarchicalkey). The following branch key context keys are shared: From 55fccff53ac94512b6720a1e9db951e215dd914a Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 14 Jul 2025 12:15:01 -0700 Subject: [PATCH 065/116] Apply suggestions from code review Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- framework/branch-key-store.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 6ea582b1..82ed514a 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -805,20 +805,20 @@ It is structured slightly differently so that the active version can be accessed In addition to the [branch key context](#branch-key-context): -The ACTIVE branch key context value of the `type` attribute MUST equal to `"branch:ACTIVE"`. -The ACTIVE branch key context MUST have a `version` attribute. -The `version` attribute MUST store the branch key version formatted like `"branch:version:"` + `version`. +The ACTIVE branch key context value of the `type`key MUST equal to `"branch:ACTIVE"`. +The ACTIVE branch key context MUST have a `version` key. +The `version` key MUST store the branch key version formatted like `"branch:version:"` + `version`. ### DECRYPT_ONLY Branch Key Context In addition to the [branch key context](#branch-key-context): -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`. +The DECRYPT_ONLY branch key context MUST NOT have a `version` key. +The `type` value MUST store the branch key version formatted like `"branch:version:"` + ``. ### Beacon Branch Key Context -In addition to the [branch key context](#encryption-context): +In addition to the [branch key context](#branch-key-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` key. From 8095f24484162a9e8800acc88b340019294c04ae Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Tue, 15 Jul 2025 09:47:47 -0700 Subject: [PATCH 066/116] auto commit --- .../2025-06-30_branch_keys_version_2/background.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 382c953f..e2ce4777 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -141,7 +141,6 @@ as they have pre-existing Key Policies with their tenants that cannot be met if the KMS Encryption Context is populated by the Branch Key's Context. - # Requirements 1. Branch Key's Context be cryptographically bound to the Branch Key's Cryptographic Material @@ -167,12 +166,12 @@ AWS Services and Software-as-a-service providers integrating with KMS. ## Why not the MetaStore approach? -The MetaStore was the predecessor to the Branch Key Store; -it is the "caching" solution for the legacy DynamoDB Encryption Client (DDBEC). +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, +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. +This gives customers significant freedom on what data is bound to a Branch Key Item's material and how that binding is facilitated. However, our customers have complained that the DB-ESDK is complicated; using the DB-ESDK to protect the materials used by the DB-ESDK and the ESDK is NOT @@ -183,8 +182,7 @@ 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. - +and introduce a circular dependency between the MPL and the DB-ESDK. # Design Questions From ca4d91215a47324a34448195de59fbf6c2ad4fb3 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Tue, 15 Jul 2025 09:51:37 -0700 Subject: [PATCH 067/116] auto commit --- .../background.md | 2 +- .../designquestion.md | 18 ++++++++---------- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index e2ce4777..767c80d8 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -289,7 +289,7 @@ then FAIL (update: `hierarchy-version-policy` was rejected, see [section 2](#2-h Otherwise, respect the flag. **Plumbing through `GenerateRandom`**: -UPDATE: `kms:GenerateDataKey` closed this negative consequence. +UPDATE: `kms:GenerateDataKey` closed this negative consequence. ### 3.2 Follow the Configuration diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/designquestion.md index b92ca853..5c30682a 100644 --- a/changes/2025-06-30_branch_keys_version_2/designquestion.md +++ b/changes/2025-06-30_branch_keys_version_2/designquestion.md @@ -65,32 +65,31 @@ One option is to refactor Branch Key Creation to use `kms:GenerateDataKey` to get a plain text cryptographic materials. This **Branch Key Context Digest** is then concatenated with -the plain-text material in a deterministic fashion. +the plain-text material in a deterministic fashion. The result of concatenation is then encrypted with KMS Encrypt. The option to use local entropy instead of `kms:GenerateDataKey` was rejected primarily because -if this local entropy fails to be random then cryptographic integrity of +if this local entropy fails to be random then cryptographic integrity of ALL the messages/items protected by the Branch Key Item is compromised. [//]: # "TODO: Detail more of the GDK vs Local Entropy discussion" - ## 1.4 KMS Random and then Bind the **Branch Key Context Digest** via KMS Encrypt KMS provides the kms:GenerateRandom operation, which generates random bytes without using a specific KMS key. Unlike operations that use KMS keys, the kms:GenerateRandom operation does not involve any specific KMS key. As a result, the access control for this operation is only managed through IAM policies, which can either allow or deny the kms:GenerateRandom permission. -Multi-tenant Branch Key Store users -MAY have an obligation to use +Multi-tenant Branch Key Store users +MAY have an obligation to use tenant specific credentials or IAM roles to access a tenant specific KMS Key. -However, these credentials or IAM roles are unlikely to grant `kms:GenerateRandom` permission, +However, these credentials or IAM roles are unlikely to grant `kms:GenerateRandom` permission, as it is not related to a KMS Key. -Thus, +Thus, these multi-tenant users would need a separate KMS client, which would use non-tenant related credentials or IAM role. -This approach leads to a "clunkier" interface, +This approach leads to a "clunkier" interface, as it involves managing more KMS clients. -Hence, Option 1.4 is rejected. +Hence, Option 1.4 is rejected. ## 1.5 Use Branch Key's cryptographic material in an HMAC on the Branch Key's Metadata and Location @@ -135,7 +134,6 @@ The plain-text AES-256 is now exposed to the Creating Agent, where as in HV-1 the plain-text AES-256 is never exposed to the Creating agent. - However, conversations with Security Engineers have generally regarded any plain-text material From 8d4eb7f0593bd10781ade69a0b1548788377595e Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 16 Jul 2025 11:18:41 -0700 Subject: [PATCH 068/116] auto commit --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 00e2cc1d..5c6d1315 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -10,7 +10,7 @@ ### Changelog - 0.9.0 - - [Hierarchy Version 2](../changes/2025-06-30_branch_keys_version_2/background.md) + - Add [hierarchy version 2](../changes/2025-06-30_branch_keys_version_2/background.md) - 0.8.0 - Revert Key store storage option. This reverts changes in 0.6.0 and 0.7.0 - 0.7.1 From 541c729ce894089aaa8f60b1ec9a750b3d61c54f Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Wed, 16 Jul 2025 11:20:23 -0700 Subject: [PATCH 069/116] Update framework/branch-key-store.md --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 5c6d1315..b723d712 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -43,7 +43,7 @@ A Keystore persists hierarchical data that allows customers to call AWS KMS less often. The Keystore persists branch keys in DynamoDb that wrap multiple data keys. This creates a hierarchy where a branch key wraps multiple data keys and facilitates caching. -These branch keys are only generated using the [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) in Hierarchy Version `v1` or [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) in Hierarchy Version `v2`. +These branch keys are generated using the [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) in Hierarchy Version `v1` or [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) in Hierarchy Version `v2`. By creating and persisting a data key to an accesbile medium, such as a DynamoDb table, From 82c1ad8b0556f4b2b78f10173f2d221e93e2fa05 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 16 Jul 2025 11:49:32 -0700 Subject: [PATCH 070/116] auto commit --- framework/branch-key-store.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index b723d712..6225c343 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -609,19 +609,6 @@ List of TransactWriteItem: MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. - ConditionExpression: `attribute_not_exists(branch-key-id)` - TableName: the configured Table Name -- PUT: - - Item: - - “branch-key-id” (S): `branchKeyId`, - - “type“ (S): "branch:ACTIVE", - - “enc” (B): wrapped ACTIVE Branch Key `CiphertextBlob` from the KMS operation - - “create-time” (S): `timestamp` - - "kms-arn" (S): configured KMS Key - - “hierarchy-version” (N): 1 - - Every key-value pair of the custom [encryption context](./structures.md#encryption-context-3) that is associated with the branch key - MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. - - ConditionExpression: `attribute_exists(branch-key-id) AND enc = :encOld` - - ExpressionAttributeValues: `{":encOld" := DDB.AttributeValue.B(oldCiphertextBlob)}` - - TableName: the configured Table Name TransactWriteItemRequest: From 688c35438da05abfd533fb7ce1c74bfe9d2a3f9f Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 16 Jul 2025 12:51:29 -0700 Subject: [PATCH 071/116] auto commit --- framework/branch-key-store.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 6225c343..7510c1c5 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -609,7 +609,19 @@ List of TransactWriteItem: MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. - ConditionExpression: `attribute_not_exists(branch-key-id)` - TableName: the configured Table Name - +- PUT: + - Item: + - “branch-key-id” (S): `branchKeyId`, + - “type“ (S): "branch:ACTIVE", + - “enc” (B): wrapped ACTIVE Branch Key `CiphertextBlob` from the KMS operation + - “create-time” (S): `timestamp` + - "kms-arn" (S): configured KMS Key + - “hierarchy-version” (N): 1 + - Every key-value pair of the custom [encryption context](./structures.md#encryption-context-3) that is associated with the branch key + MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. + - ConditionExpression: `attribute_exists(branch-key-id)` + - TableName: the configured Table Name + TransactWriteItemRequest: - TransactWriteItems: List of TransactWriteItem From 81b60e87e0cae0384afb1dff5d32ff10444dd616 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 16 Jul 2025 12:54:28 -0700 Subject: [PATCH 072/116] auto commit --- framework/branch-key-store.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 7510c1c5..642961e3 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -621,7 +621,7 @@ List of TransactWriteItem: MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. - ConditionExpression: `attribute_exists(branch-key-id)` - TableName: the configured Table Name - + TransactWriteItemRequest: - TransactWriteItems: List of TransactWriteItem @@ -749,17 +749,16 @@ This operation MUST return the constructed [beacon key materials](./structures.m Branch Key Context is a set of key value pairs (a Map) that contain contextual information about the Branch Key Item. -The following branch key context keys are shared: - -- MUST have a `branch-key-id` attribute -- The `branch-key-id` field MUST not be an empty string -- MUST have a `type` attribute -- The `type` field MUST not be an empty string -- MUST have a `create-time` attribute -- MUST have a `tablename` attribute to store the logicalKeyStoreName -- MUST have a `kms-arn` attribute -- MUST have a `hierarchy-version` -- MUST NOT have a `enc` attribute +The Branch Key Context: + +- MUST have a `branch-key-id` key who's value MUST not be an empty string +- MUST have a `type` key who's value MUST not be an empty string +- MUST have a `create-time` key in ISO 8601 format in UTC +- MUST have a `tablename` key who's value is the logicalKeyStoreName +- MUST have a `kms-arn` key who's value is valid KMS ARN +- MUST have a `hierarchy-version` key who's value is either "1" or "2" +- MUST NOT have a `enc` key +- MAY have one or more keys prefixed with `aws-crypto-ec:` ### ACTIVE Branch Key Context From 30e58d90a252e5ab64921314fdae7e0b9e49f937 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Wed, 16 Jul 2025 14:20:43 -0700 Subject: [PATCH 073/116] Update background.md --- changes/2025-06-30_branch_keys_version_2/background.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 767c80d8..598911b3 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -325,5 +325,4 @@ Unless someone can think of something else, ## 4 Branch Key Versioning (Rotation) -UPDATE: The team elected for 3.5; we will Mirror 3.5. -(BKS can VersionKey HV-1 or HV-2). +Branch key store can VersionKey for HV-1 or HV-2 based on schema version (equivalent to hierarchical version) of the branch key item. From ec22bf418c0d77714e37649f1fcf26ff756cb1ac Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 16 Jul 2025 15:01:00 -0700 Subject: [PATCH 074/116] auto commit --- framework/branch-key-store.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 642961e3..1a1fd383 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -633,15 +633,9 @@ Otherwise, this operation MUST yield an error. The operation MUST use the configured `KMS SDK Client` to authenticate the value of the keystore item. -Every attribute on the AWS DDB response item will be authenticated. - -Every key in the constructed [encryption context](#encryption-context) -except `tableName` -MUST exist as a string attribute in the AWS DDB response item. -Every value in the constructed [encryption context](#encryption-context) -except the logical table name -MUST equal the value with the same key in the AWS DDB response item. -The key `enc` MUST NOT exist in the constructed [encryption context](#encryption-context). +This operation MUST call AWS DDB `GetItem`. +Every attribute except `enc` on the AWS DDB response item MUST be converted to a set of key value pairs (a Map) +which is the [encryption context](#encryption-context). The operation MUST call [AWS KMS API ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) with a request constructed as follows: @@ -657,8 +651,9 @@ with a request constructed as follows: The operation MUST use the configured `KMS SDK Client` to authenticate the value of the keystore item. -Every attribute on the AWS DDB response item expect `enc` MUST be authenticated. -From the AWS DDB response item, the operation MUST create a [branch key context](#branch-key-context) and [encryption context](#encryption-context). +This operation MUST call AWS DDB `GetItem`. +Every attribute except `enc` on the AWS DDB response item MUST be converted to a set of key value pairs (a Map) +which is the [branch key context](#branch-key-context). The [encryption context](#encryption-context) is built from branch key context by extracting keys with prefix `aws-crypto-ec:` and then dropping the prefix. The operation MUST follow [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) to decrypt and authentication the branch key context. From 8db8704831b3b3456fd6bd07a6f2c8f38daaa7bd Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 16 Jul 2025 15:07:57 -0700 Subject: [PATCH 075/116] auto commit --- framework/branch-key-store.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 1a1fd383..8e053ef2 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -753,7 +753,8 @@ The Branch Key Context: - MUST have a `kms-arn` key who's value is valid KMS ARN - MUST have a `hierarchy-version` key who's value is either "1" or "2" - MUST NOT have a `enc` key -- MAY have one or more keys prefixed with `aws-crypto-ec:` +- MAY have one or more keys prefixed with `aws-crypto-ec:` which is the encyption context send by the customer. +The `aws-crypto-ec:` prefix is prepended by the library ### ACTIVE Branch Key Context From d062762bb5d2af2239101bb4047e53a8f41fe4f1 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Wed, 16 Jul 2025 15:08:37 -0700 Subject: [PATCH 076/116] formatting --- framework/branch-key-store.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 8e053ef2..89cb0458 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -633,7 +633,7 @@ Otherwise, this operation MUST yield an error. The operation MUST use the configured `KMS SDK Client` to authenticate the value of the keystore item. -This operation MUST call AWS DDB `GetItem`. +This operation MUST call AWS DDB `GetItem`. Every attribute except `enc` on the AWS DDB response item MUST be converted to a set of key value pairs (a Map) which is the [encryption context](#encryption-context). @@ -651,7 +651,7 @@ with a request constructed as follows: The operation MUST use the configured `KMS SDK Client` to authenticate the value of the keystore item. -This operation MUST call AWS DDB `GetItem`. +This operation MUST call AWS DDB `GetItem`. Every attribute except `enc` on the AWS DDB response item MUST be converted to a set of key value pairs (a Map) which is the [branch key context](#branch-key-context). The [encryption context](#encryption-context) is built from branch key context by extracting keys with prefix `aws-crypto-ec:` and then dropping the prefix. @@ -754,7 +754,7 @@ The Branch Key Context: - MUST have a `hierarchy-version` key who's value is either "1" or "2" - MUST NOT have a `enc` key - MAY have one or more keys prefixed with `aws-crypto-ec:` which is the encyption context send by the customer. -The `aws-crypto-ec:` prefix is prepended by the library + The `aws-crypto-ec:` prefix is prepended by the library ### ACTIVE Branch Key Context From b49dd3ff20067ec802f5832d08e548ff7cc81d2b Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 17 Jul 2025 10:26:35 -0700 Subject: [PATCH 077/116] auto commit --- framework/branch-key-store.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 89cb0458..cbc667ab 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -339,6 +339,9 @@ To create a branch key, this operation MUST take the following: - `encryptionContext`: Additional encryption context to bind to the created keys - `kms-arn`: The KMS-ARN determined by the KMS Configuration - `hierarchy-version`: The hierarchy-version determined by the input + +This operation needs to generate the following: + - `version`: a new guid. This guid MUST be [version 4 UUID](https://www.ietf.org/rfc/rfc4122.txt) - `timestamp`: a timestamp for the current time. This timestamp MUST be in ISO 8601 format in UTC, to microsecond precision (e.g. “YYYY-MM-DDTHH:mm:ss.ssssssZ“) From 1ad7803b5b18a33ba2cab0c2bc785981b37ab3e1 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 17 Jul 2025 10:31:38 -0700 Subject: [PATCH 078/116] auto commit --- framework/branch-key-store.md | 1 - 1 file changed, 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index cbc667ab..8ca5b4f5 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -337,7 +337,6 @@ To create a branch key, this operation MUST take the following: - `branchKeyId`: The identifier - `encryptionContext`: Additional encryption context to bind to the created keys -- `kms-arn`: The KMS-ARN determined by the KMS Configuration - `hierarchy-version`: The hierarchy-version determined by the input This operation needs to generate the following: From 15bc50abfd7cb05387d5e41437867152d0e25346 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 17 Jul 2025 12:26:39 -0700 Subject: [PATCH 079/116] auto commit --- framework/branch-key-store.md | 1 - 1 file changed, 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 8ca5b4f5..c038a74b 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -679,7 +679,6 @@ using the `branch-key-id` as the Partition Key and `"branch:ACTIVE"` value as th The AWS DDB response MUST contain the fields defined in the [branch keystore record format](#record-format). If the record does not contain the defined fields, this operation MUST fail. -The operation MUST decrypt the branch key according to the [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) section. The operation MUST decrypt the branch key according to the [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) section. If the branch key fails to decrypt, GetActiveBranchKey MUST fail. From aad0ee3b47e9d3d01a625df8a7db89d40957eac3 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 17 Jul 2025 12:31:36 -0700 Subject: [PATCH 080/116] designq -> protect_branch_key_without_kms_ec --- changes/2025-06-30_branch_keys_version_2/background.md | 2 +- .../{designquestion.md => protect_branch_key_without_kms_ec.md} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename changes/2025-06-30_branch_keys_version_2/{designquestion.md => protect_branch_key_without_kms_ec.md} (100%) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 598911b3..ab3d1dd7 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -188,7 +188,7 @@ and introduce a circular dependency between the MPL and the DB-ESDK. ## 1 How can the Branch Key's Context be protected without using KMS EC? -See [DesignQuestion.md](./DesignQuestion.md). +See [protect_branch_key_without_kms_ec.md](./protect_branch_key_without_kms_ec.md). ## 2 How are we going to offer operation in a mixed mode? diff --git a/changes/2025-06-30_branch_keys_version_2/designquestion.md b/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md similarity index 100% rename from changes/2025-06-30_branch_keys_version_2/designquestion.md rename to changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md From 2d105eacaa95b0cd0647ec5fdcb7f71f77da183d Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Fri, 18 Jul 2025 11:25:48 -0700 Subject: [PATCH 081/116] resolve https://github.com/awslabs/aws-encryption-sdk-specification/pull/297\#discussion_r2214396257 --- framework/branch-key-store.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index c038a74b..cd629954 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -339,12 +339,6 @@ To create a branch key, this operation MUST take the following: - `encryptionContext`: Additional encryption context to bind to the created keys - `hierarchy-version`: The hierarchy-version determined by the input -This operation needs to generate the following: - -- `version`: a new guid. This guid MUST be [version 4 UUID](https://www.ietf.org/rfc/rfc4122.txt) -- `timestamp`: a timestamp for the current time. - This timestamp MUST be in ISO 8601 format in UTC, to microsecond precision (e.g. “YYYY-MM-DDTHH:mm:ss.ssssssZ“) - The wrapped Branch Key Items, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Branch Key Creation](#wrapped-branch-key-creation). If the `hierarchy-version` is `v1`, From 7d10c1ff868a6b83af19fd210b06b9baf150f0ff Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Fri, 18 Jul 2025 11:36:52 -0700 Subject: [PATCH 082/116] resolve https://github.com/awslabs/aws-encryption-sdk-specification/pull/297\#discussion_r2214397623 --- framework/branch-key-store.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index cd629954..b05f1431 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -404,11 +404,7 @@ If the call to AWS KMS Encrypt succeeds, the operation MUST use the Encrypt result `CiphertextBlob` as the wrapped Beacon Key. -#### Wrapped Branch Key Creation - -Given a `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. - -##### Wrapped Branch Key Creation `v1` +#### Wrapped Branch Key Creation `v1` The operation MUST generate a map of strings, the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context), @@ -445,7 +441,7 @@ If the call to AWS KMS ReEncrypt succeeds, the operation MUST use the ReEncrypt result `CiphertextBlob` as the wrapped ACTIVE Branch Key. -##### Wrapped Branch Key Creation `v2` +#### Wrapped Branch Key Creation `v2` The operation MUST generate a map of strings, the [`DECRYPT_ONLY` branch key context for branch keys](#decrypt_only-branch-key-context). From a725bc05b3bf75fe8c18b278bd672e63d72a00a7 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Fri, 18 Jul 2025 11:44:13 -0700 Subject: [PATCH 083/116] nit fix Co-authored-by: Darwin Chowdary <39110935+imabhichow@users.noreply.github.com> --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index b05f1431..45f5a59e 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -298,7 +298,7 @@ The CreateKey caller MUST provide: - An optional branch key id - An optional encryption context -- An optional Hierarchy-Version +- An optional hierarchy-version If an optional branch key id is provided and no encryption context is provided this operation MUST fail. From 79c5efd1381e22fb1fb6905a117fbc09728336a0 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Fri, 18 Jul 2025 11:47:01 -0700 Subject: [PATCH 084/116] resolve https://github.com/awslabs/aws-encryption-sdk-specification/pull/297\#discussion_r2214397623 --- framework/branch-key-store.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 45f5a59e..b9a01e3a 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -339,8 +339,6 @@ To create a branch key, this operation MUST take the following: - `encryptionContext`: Additional encryption context to bind to the created keys - `hierarchy-version`: The hierarchy-version determined by the input -The wrapped Branch Key Items, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Branch Key Creation](#wrapped-branch-key-creation). - If the `hierarchy-version` is `v1`, the wrapped beacon key MUST be created according to [Wrapped Beacon Key Creation `v1`](#wrapped-beacon-key-creation-v1) and the wrapped branch keys MUST be created according to From feaa9f060e2b18d12b3602436f49f7a93d059fb4 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Fri, 18 Jul 2025 12:11:32 -0700 Subject: [PATCH 085/116] Update framework/branch-key-store.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: José Corella <39066999+josecorella@users.noreply.github.com> --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index b9a01e3a..fa80d9fa 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -643,7 +643,7 @@ The operation MUST use the configured `KMS SDK Client` to authenticate the value This operation MUST call AWS DDB `GetItem`. Every attribute except `enc` on the AWS DDB response item MUST be converted to a set of key value pairs (a Map) -which is the [branch key context](#branch-key-context). The [encryption context](#encryption-context) is built from branch key context by extracting keys with prefix `aws-crypto-ec:` and then dropping the prefix. +which is the [branch key context](#branch-key-context). The [encryption context](#encryption-context) MUST be built from branch key context by extracting keys with prefix `aws-crypto-ec:` and then dropping the prefix. The operation MUST follow [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) to decrypt and authentication the branch key context. From e2f3eb898769673beef5f61a6a61b15da5f2feb1 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 21 Jul 2025 10:21:46 -0700 Subject: [PATCH 086/116] Update framework/branch-key-store.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index fa80d9fa..ee986e01 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -864,7 +864,7 @@ A branch key record MUST include the following key-value pairs: represented as [AWS DDB Number](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) A branch key record MAY include [custom encryption context](#custom-encryption-context) key-value pairs. -These attributes MUST be always prefixed with `aws-crypto-ec:` regardless of the item's `hierarchy-version`. +These attributes MUST always be prefixed with `aws-crypto-ec:` regardless of the item's `hierarchy-version`. ### Branch Key Materials From Authenticated Encryption Context From 625ec56bfa2a27c8b106f2b135216ee63281b3ef Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Mon, 21 Jul 2025 10:34:37 -0700 Subject: [PATCH 087/116] auto commit --- framework/branch-key-store.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index ee986e01..a837a5d5 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -578,7 +578,10 @@ The values on the AWS DDB response item MUST be authenticated according to [authenticating a keystore item for item with hierarchy version v1](#authenticating-a-branch-keystore-item-for-item-with-hierarchy-version-v1) or [authenticating a keystore item for item with hierarchy version v2](#authenticating-a-branch-keystore-item-for-item-with-hierarchy-version-v2) based on schema version of the branch key item. If the item fails to authenticate this operation MUST fail. -The wrapped Branch Keys, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Branch Key Creation](#wrapped-branch-key-creation). +If the `hierarchy-version` is `v1`, +the wrapped Branch Keys, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Beacon Key Creation `v1`](#wrapped-beacon-key-creation-v1); +else the `hierarchy-version` MUST be `v2`, +[Wrapped Branch Key Creation `v2`](#wrapped-branch-key-creation-v2). To add the new branch key to the keystore, the operation MUST call [Amazon DynamoDB API TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html). From e8185818f2e9f4f8ae80dd12ad2f1d7bed3c6a0c Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 21 Jul 2025 10:41:15 -0700 Subject: [PATCH 088/116] Update framework/branch-key-store.md --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index a837a5d5..bcbdbcfe 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -780,7 +780,7 @@ This section describes how the AWS KMS encryption context is built. 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. +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 transformations. 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. ### ACTIVE Encryption Context From 372503296607d3a5ff5024e2c52973c03a7caf3a Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 21 Jul 2025 10:42:12 -0700 Subject: [PATCH 089/116] Update framework/structures.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: José Corella <39066999+josecorella@users.noreply.github.com> --- framework/structures.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/structures.md b/framework/structures.md index 70af2081..408bfe56 100644 --- a/framework/structures.md +++ b/framework/structures.md @@ -422,7 +422,7 @@ The AWS KMS Key ARN used to protect these materials. ##### Create Time -Timestamp in ISO 8601 format in UTC, to microsecond precision, that the Material was generated. +Timestamp in ISO 8601 format in UTC, to microsecond precision, of when the material was generated. ##### Hierarchy Version From d6fd9904dec19bd6024dd6f76d97af858dcca65d Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Mon, 21 Jul 2025 10:43:21 -0700 Subject: [PATCH 090/116] Update framework/branch-key-store.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: José Corella <39066999+josecorella@users.noreply.github.com> --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index bcbdbcfe..9b5141aa 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -778,7 +778,7 @@ The Beacon key branch key context MUST NOT have a `version` key. This section describes how the AWS KMS encryption context is built. 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, AWS KMS encryption context MUST be the [encryption context](../structures.md#encryption-context) sent 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 transformations. 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. From 9c5c2813c3e580812b8449d2d603d4e4e976fe1f Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Mon, 21 Jul 2025 10:56:14 -0700 Subject: [PATCH 091/116] auto commit --- framework/branch-key-store.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 9b5141aa..ed84757a 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -757,7 +757,7 @@ In addition to the [branch key context](#branch-key-context): The ACTIVE branch key context value of the `type`key MUST equal to `"branch:ACTIVE"`. The ACTIVE branch key context MUST have a `version` key. -The `version` key MUST store the branch key version formatted like `"branch:version:"` + `version`. +The `version` key MUST store the branch key version formatted like `"branch:version:"` + ``. ### DECRYPT_ONLY Branch Key Context @@ -806,6 +806,8 @@ Across all versions of a Branch Key, the custom encryption context MUST be equal The operation MUST use the configured `KMS SDK Client` to decrypt the value of the branch key field. +To get attributes in branch key item from the keystore +this operation MUST call AWS DDB `GetItem`. Every attribute except for `enc` on the AWS DDB response item MUST be authenticated in the decryption of `enc` @@ -839,12 +841,8 @@ the keystore operation MUST call with a request constructed as follows: - `EncryptionContext` MUST be the [encryption context](#encryption-context) constructed above - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -Every attribute except for `enc` on the AWS DDB response item -MUST be authenticated in the decryption of `enc`. -In Hierarchy Version `v1`, when AWS KMS Decrypt succeeds this attribute gets -authenticated by KMS as they are included in the AWS KMS encryption context. -For authentication of these attributes in Hierarchy Version `v2`, -the operation MUST match the first 48 bytes of `Plaintext` returned by AWS KMS Decrypt operation with SHA-384 Digest for the beacon key of serialization of the [branch key context](#branch-key-context). +For authentication of attributes except for `enc` on AWS DDB response item in Hierarchy Version `v2`, +the operation MUST match the first 48 bytes of `Plaintext` returned by AWS KMS Decrypt operation with SHA-384 Digest for the branch key of serialization of the [branch key context](#branch-key-context). ## Record Format From 1ccbcbe3cb3536e27c822fa5664e85c0952a3d45 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Mon, 21 Jul 2025 11:03:38 -0700 Subject: [PATCH 092/116] auto commit --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index ed84757a..50077c99 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -646,7 +646,7 @@ The operation MUST use the configured `KMS SDK Client` to authenticate the value This operation MUST call AWS DDB `GetItem`. Every attribute except `enc` on the AWS DDB response item MUST be converted to a set of key value pairs (a Map) -which is the [branch key context](#branch-key-context). The [encryption context](#encryption-context) MUST be built from branch key context by extracting keys with prefix `aws-crypto-ec:` and then dropping the prefix. +which is the [branch key context](#branch-key-context). Every key in the constructed branch key context except tableName MUST exist as a string attribute in the AWS DDB response item. The [encryption context](#encryption-context) MUST be built from branch key context by extracting keys with prefix `aws-crypto-ec:` and then dropping the prefix. The operation MUST follow [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) to decrypt and authentication the branch key context. From e982ff036970f303839b213e8dec33df079c6e2b Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Mon, 21 Jul 2025 11:04:27 -0700 Subject: [PATCH 093/116] auto commit --- framework/branch-key-store.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 50077c99..ffbe8363 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -646,7 +646,9 @@ The operation MUST use the configured `KMS SDK Client` to authenticate the value This operation MUST call AWS DDB `GetItem`. Every attribute except `enc` on the AWS DDB response item MUST be converted to a set of key value pairs (a Map) -which is the [branch key context](#branch-key-context). Every key in the constructed branch key context except tableName MUST exist as a string attribute in the AWS DDB response item. The [encryption context](#encryption-context) MUST be built from branch key context by extracting keys with prefix `aws-crypto-ec:` and then dropping the prefix. +which is the [branch key context](#branch-key-context). +Every key in the constructed branch key context except tableName MUST exist as a string attribute in the AWS DDB response item. +The [encryption context](#encryption-context) MUST be built from branch key context by extracting keys with prefix `aws-crypto-ec:` and then dropping the prefix. The operation MUST follow [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) to decrypt and authentication the branch key context. From 24b76b8d7b6fc956ec6fa5fe4d91c6897169d81c Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Mon, 21 Jul 2025 11:32:32 -0700 Subject: [PATCH 094/116] auto commit --- framework/branch-key-store.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index ffbe8363..b48920dd 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -64,6 +64,10 @@ This Keystore interface defines operations that any implementation of its specif A root key used to then derive different beacon keys per beacon. - [UUID](https://www.ietf.org/rfc/rfc4122.txt): a universally unique identifier that can be represented as a byte sequence or a string. +#### kms-arn + +`kms-arn` is the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. + #### Hierarchy Version Schema Version of the Branch Key. From f300cd0f2b4bc07a8248330519cee5db16e64ea2 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Mon, 21 Jul 2025 11:35:59 -0700 Subject: [PATCH 095/116] formatting --- framework/branch-key-store.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index b48920dd..1df387c7 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -650,8 +650,8 @@ The operation MUST use the configured `KMS SDK Client` to authenticate the value This operation MUST call AWS DDB `GetItem`. Every attribute except `enc` on the AWS DDB response item MUST be converted to a set of key value pairs (a Map) -which is the [branch key context](#branch-key-context). -Every key in the constructed branch key context except tableName MUST exist as a string attribute in the AWS DDB response item. +which is the [branch key context](#branch-key-context). +Every key in the constructed branch key context except tableName MUST exist as a string attribute in the AWS DDB response item. The [encryption context](#encryption-context) MUST be built from branch key context by extracting keys with prefix `aws-crypto-ec:` and then dropping the prefix. The operation MUST follow [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) to decrypt and authentication the branch key context. @@ -812,7 +812,7 @@ Across all versions of a Branch Key, the custom encryption context MUST be equal The operation MUST use the configured `KMS SDK Client` to decrypt the value of the branch key field. -To get attributes in branch key item from the keystore +To get attributes in branch key item from the keystore this operation MUST call AWS DDB `GetItem`. Every attribute except for `enc` on the AWS DDB response item MUST be authenticated in the decryption of `enc` From 7fa33639842e7d2a967eca858f2ef0b59f2c4948 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Wed, 23 Jul 2025 11:26:01 -0700 Subject: [PATCH 096/116] chore: encryption-context changes (#300) Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> Co-authored-by: seebees --- framework/branch-key-store.md | 112 ++++++++++++++-------------------- framework/structures.md | 4 +- 2 files changed, 47 insertions(+), 69 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 6499d5df..8bf34496 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -342,7 +342,7 @@ Otherwise, this operation MUST yield an error. To create a branch key, this operation MUST take the following: - `branchKeyId`: The identifier -- `encryptionContext`: Additional encryption context to bind to the created keys +- `encryption-context`: Additional encryption context to bind to the created keys - `hierarchy-version`: The hierarchy-version determined by the input If the `hierarchy-version` is `v1`, @@ -364,7 +364,7 @@ The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request c - `KeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `NumberOfBytes` MUST be 32. -- `EncryptionContext` MUST be the [encryption context for beacon keys](#beacon-key-encryption-context). +- `EncryptionContext` MUST be the [branch key context for beacon keys](#beacon-branch-key-context). - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). If the call to AWS KMS GenerateDataKeyWithoutPlaintext succeeds, @@ -411,11 +411,11 @@ as the wrapped Beacon Key. #### Wrapped Branch Key Creation `v1` The operation MUST generate a map of strings, -the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context), +the [DECRYPT_ONLY branch context for branch keys](#decrypt_only-branch-key-context), using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. The operation MUST generate a map of strings, -the [ACTIVE encryption context for branch keys](#active-encryption-context) +the [ACTIVE branch context for branch keys](#active-branch-key-context) using the `branchKeyId`, `version`, `timestamp`, `kms-arn`, `encryption-context`, and `hierarchy-version`. The operation MUST call [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html). @@ -424,7 +424,7 @@ The operation MUST call AWS KMS GenerateDataKeyWithoutPlaintext with a request c - `KeyId` MUST be the configured `AWS KMS Key ARN` in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `NumberOfBytes` MUST be 32. -- `EncryptionContext` MUST be the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context). +- `EncryptionContext` MUST be the [DECRYPT_ONLY branch context for branch keys](#decrypt_only-branch-key-context). - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). If the call to AWS KMS GenerateDataKeyWithoutPlaintext succeeds, @@ -434,12 +434,12 @@ as the wrapped DECRYPT_ONLY Branch Key. The operation MUST call [AWS KMS API ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) with a request constructed as follows: -- `SourceEncryptionContext` MUST be the [DECRYPT_ONLY encryption context for branch keys](#decrypt_only-encryption-context). +- `SourceEncryptionContext` MUST be the [DECRYPT_ONLY branch key context for branch keys](#decrypt_only-branch-key-context). - `SourceKeyId` MUST be the `kms-arn`. - `CiphertextBlob` MUST be the wrapped DECRYPT_ONLY Branch Key. - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). - `DestinationKeyId` MUST be the `kms-arn`. -- `DestinationEncryptionContext` MUST be the [ACTIVE encryption context for branch keys](#active-encryption-context). +- `DestinationEncryptionContext` MUST be the [ACTIVE branch key context for branch keys](#active-branch-key-context). If the call to AWS KMS ReEncrypt succeeds, the operation MUST use the ReEncrypt result `CiphertextBlob` @@ -524,7 +524,7 @@ List of TransactWriteItem: - “create-time” (S): `timestamp` - "kms-arn" (S): configured KMS Key - “hierarchy-version” (N): either `1` or `2`, depending on the `hierarchy-version` - - Every key-value pair of the custom [encryption context](./structures.md#encryption-context-3) that is associated with the branch key + - Every key-value pair in the input `encryption-context` MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. - ConditionExpression: `attribute_not_exists(branch-key-id)` - TableName: the configured Table Name @@ -536,7 +536,7 @@ List of TransactWriteItem: - “create-time” (S): `timestamp` - "kms-arn" (S): configured KMS Key - “hierarchy-version” (N): either `1` or `2`, depending on the `hierarchy-version` - - Every key-value pair of the custom [encryption context](./structures.md#encryption-context-3) that is associated with the branch key + - Every key-value pair in the input `encryption-context` MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. - ConditionExpression: `attribute_not_exists(branch-key-id)` - TableName: the configured Table Name @@ -548,7 +548,7 @@ List of TransactWriteItem: - “create-time” (S): `timestamp` - "kms-arn" (S): configured KMS Key - “hierarchy-version” (N): either `1` or `2`, depending on the `hierarchy-version` - - Every key-value pair of the custom [encryption context](./structures.md#encryption-context-3) that is associated with the branch key + - Every key-value pair in the input `encryption-context` MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. - ConditionExpression: `attribute_not_exists(branch-key-id)` - TableName is the configured Table Name @@ -603,9 +603,8 @@ List of TransactWriteItem: - “enc” (B): the wrapped DECRYPT_ONLY Branch Key `CiphertextBlob` from the KMS operation - “create-time” (S): `timestamp` - "kms-arn" (S): configured KMS Key - - “hierarchy-version” (N): 1 - - Every key-value pair of the custom [encryption context](./structures.md#encryption-context-3) that is associated with the branch key - MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. + - “hierarchy-version” (N): either `1` or `2`, depending on the `hierarchy-version` + - Every other key-value pair in the [branch key context](./structures.md#branch-key-context). - ConditionExpression: `attribute_not_exists(branch-key-id)` - TableName: the configured Table Name - PUT: @@ -615,8 +614,8 @@ List of TransactWriteItem: - “enc” (B): wrapped ACTIVE Branch Key `CiphertextBlob` from the KMS operation - “create-time” (S): `timestamp` - "kms-arn" (S): configured KMS Key - - “hierarchy-version” (N): 1 - - Every key-value pair of the custom [encryption context](./structures.md#encryption-context-3) that is associated with the branch key + - “hierarchy-version” (N): either `1` or `2`, depending on the `hierarchy-version` + - Every key-value pair in the [encryption context](./structures.md#encryption-context) provided by users and is associated with the branch key MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. - ConditionExpression: `attribute_exists(branch-key-id) AND enc = :encOld` - ExpressionAttributeValues: `{":encOld" := DDB.AttributeValue.B(oldCiphertextBlob)}` @@ -638,18 +637,18 @@ This prevents overwrites due to a race in updating the Active Item. The operation MUST use the configured `KMS SDK Client` to authenticate the value of the keystore item. This operation MUST call AWS DDB `GetItem`. -Every attribute except `enc` on the AWS DDB response item MUST be converted to a set of key value pairs (a Map) -which is the [encryption context](#encryption-context). +Every attribute except `enc` on the AWS DDB response item MUST be converted to a set of key value pairs +which is the [branch key context](#branch-key-context). The operation MUST call [AWS KMS API ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) with a request constructed as follows: -- `SourceEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above +- `SourceEncryptionContext` MUST be the [branch key context](#branch-key-context) constructed above - `SourceKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured KMS Key in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. - `CiphertextBlob` MUST be the `enc` attribute value on the AWS DDB response item - `GrantTokens` MUST be the configured [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). - `DestinationKeyId` MUST be [compatible with](#aws-key-arn-compatibility) the configured KMS Key in the [AWS KMS Configuration](#aws-kms-configuration) for this keystore. -- `DestinationEncryptionContext` MUST be the [encryption context](#encryption-context) constructed above +- `DestinationEncryptionContext` MUST be the [branch key context](#branch-key-context) constructed above #### Authenticating a Branch Keystore item for item with `hierarchy-version` v2 @@ -659,7 +658,7 @@ This operation MUST call AWS DDB `GetItem`. Every attribute except `enc` on the AWS DDB response item MUST be converted to a set of key value pairs (a Map) which is the [branch key context](#branch-key-context). Every key in the constructed branch key context except tableName MUST exist as a string attribute in the AWS DDB response item. -The [encryption context](#encryption-context) MUST be built from branch key context by extracting keys with prefix `aws-crypto-ec:` and then dropping the prefix. +The [AWS KMS Encryption Context](#aws-kms-encryption-context) MUST be the [encryption context](#encryption-context), which is built from the branch key context by extracting the keys with prefix `aws-crypto-ec:` and then dropping the prefix. See [Encryption Context From Authenticated Branch Key Context](#encryption-context-from-authenticated-branch-key-context). The operation MUST follow [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) to decrypt and authentication the branch key context. @@ -688,7 +687,7 @@ The operation MUST decrypt the branch key according to the [AWS KMS Branch Key D If the branch key fails to decrypt, GetActiveBranchKey MUST fail. This GetActiveBranchKey MUST construct [branch key materials](./structures.md#branch-key-materials) -according to [Branch Key Materials From Authenticated Encryption Context](#branch-key-materials-from-authenticated-encryption-context). +according to [Branch Key Materials From Authenticated Branch Key Context](#branch-key-materials-from-authenticated-branch-key-context). This operation MUST return the constructed [branch key materials](./structures.md#branch-key-materials). @@ -714,7 +713,7 @@ The operation MUST decrypt the branch key according to the [AWS KMS Branch Key D If the branch key fails to decrypt, this operation MUST fail. This GetBranchKeyVersion MUST construct [branch key materials](./structures.md#branch-key-materials) -according to [Branch Key Materials From Authenticated Encryption Context](#branch-key-materials-from-authenticated-encryption-context). +according to [Branch Key Materials From Authenticated Branch Key Context](#branch-key-materials-from-authenticated-branch-key-context). This operation MUST return the constructed [branch key materials](./structures.md#branch-key-materials). @@ -753,13 +752,14 @@ The Branch Key Context: - MUST have a `branch-key-id` key who's value MUST not be an empty string - MUST have a `type` key who's value MUST not be an empty string -- MUST have a `create-time` key in ISO 8601 format in UTC +- MUST have a `create-time` key with a value in ISO 8601 format in UTC - MUST have a `tablename` key who's value is the logicalKeyStoreName - MUST have a `kms-arn` key who's value is valid KMS ARN - MUST have a `hierarchy-version` key who's value is either "1" or "2" - MUST NOT have a `enc` key - MAY have one or more keys prefixed with `aws-crypto-ec:` which is the encyption context send by the customer. The `aws-crypto-ec:` prefix is prepended by the library +- MUST NOT have any other keys apart from the ones mentioned above if `hierarchy-version` is "2" ### ACTIVE Branch Key Context @@ -786,34 +786,10 @@ In addition to the [branch key context](#branch-key-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` key. -## Encryption Context - -This section describes how the AWS KMS encryption context is built. +## AWS KMS Encryption Context 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) sent 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 transformations. 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. - -### ACTIVE Encryption Context - -If the `hierarchy-version` is v1, ACTIVE Encryption Context is same as [ACTIVE Branch Key Context](#active-branch-key-context) - -### DECRYPT_ONLY Encryption Context - -If the `hierarchy-version` is v1, DECRYPT_ONLY Encryption Context is same as [DECRYPT_ONLY Branch Key Context](#decrypt_only-branch-key-context) - -### Beacon Key Encryption Context - -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 - -If custom [encryption context](./structures.md#encryption-context) -is associated with the branch key these values MUST be added to the AWS KMS encryption context. -To avoid name collisions each added attribute from the custom [encryption context](./structures.md#encryption-context-3) -MUST be prefixed with `aws-crypto-ec:`. -Across all versions of a Branch Key, the custom encryption context MUST be equal. +If the `hierarchy-version` is v2, AWS KMS encryption context MUST be the [encryption context from authenticated branch key context](#encryption-context-from-authenticated-branch-key-context) without any transformation. This requirement applies regardless of the Branch Key Item's `type`. ## AWS KMS Branch Key Decryption @@ -824,13 +800,15 @@ this operation MUST call AWS DDB `GetItem`. Every attribute except for `enc` on the AWS DDB response item MUST be authenticated in the decryption of `enc` -Every key in the constructed [encryption context](#encryption-context) +Every key in the constructed [branch key context](#branch-key-context) except `tableName` -MUST exist as a string attribute in the AWS DDB response item. -Every value in the constructed [encryption context](#encryption-context) +MUST exist as a attribute in the AWS DDB response item. +All attributes in the AWS DynamoDB response item MUST be of type string, +with the exception of hierarchy-version, which MUST be of type number. +Every value in the constructed [branch key context](#branch-key-context) except the logical table name MUST equal the value with the same key in the AWS DDB response item. -The key `enc` MUST NOT exist in the constructed [encryption context](#encryption-context). +The key `enc` MUST NOT exist in the constructed [branch key context](#branch-key-context). If the Keystore's [AWS KMS Configuration](#aws-kms-configuration) is `KMS Key ARN` or `KMS MRKey ARN`, the `kms-arn` field of the DDB response item MUST be @@ -851,7 +829,7 @@ the keystore operation MUST call with a request constructed as follows: If the KMS Configuration is MRDiscovery, `KeyId` MUST be the `kms-arn` attribute value of the AWS DDB response item, with the region replaced by the configured region. Otherwise, it MUST BE the Keystore's configured KMS Key. - `CiphertextBlob` MUST be the `enc` attribute value on the AWS DDB response item -- `EncryptionContext` MUST be the [encryption context](#encryption-context) constructed above +- `EncryptionContext` MUST be the [encryption context from authenticated branch key context](#encryption-context-from-authenticated-branch-key-context) - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). For authentication of attributes except for `enc` on AWS DDB response item in Hierarchy Version `v2`, @@ -877,19 +855,19 @@ A branch key record MUST include the following key-value pairs: 1. `hierarchy-version`: Version of the hierarchical keyring; represented as [AWS DDB Number](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) -A branch key record MAY include [custom encryption context](#custom-encryption-context) key-value pairs. -These attributes MUST always be prefixed with `aws-crypto-ec:` regardless of the item's `hierarchy-version`. +A branch key record MAY include [encryption context](./structures.md#encryption-context) key-value pairs. +These attributes MUST be prefixed with `aws-crypto-ec:` regardless of the item's `hierarchy-version`. -### Branch Key Materials From Authenticated Encryption Context +### Branch Key Materials From Authenticated Branch key Context The `type` attribute MUST either be equal to `"branch:ACTIVE"` or start with `"branch:version:"`. If the `type` attribute is equal to `"branch:ACTIVE"` -then the authenticated encryption context MUST have a `version` attribute +then the authenticated branch key context MUST have a `version` attribute and the version string is this value. If the `type` attribute start with `"branch:version:"` then the version string MUST be equal to this value. -To construct [branch key materials](./structures.md#branch-key-materials) from authenticated encryption context as follows: +To construct [branch key materials](./structures.md#branch-key-materials) from authenticated branch key context as follows: - [Branch Key](./structures.md#branch-key) MUST be the [decrypted branch key material](#aws-kms-branch-key-decryption) - [Branch Key Id](./structures.md#branch-key-id) MUST be the `branch-key-id` @@ -897,18 +875,18 @@ To construct [branch key materials](./structures.md#branch-key-materials) from a The version string MUST start with `branch:version:`. The remaining string encoded as UTF8 bytes MUST be the Branch Key version. - [Encryption Context](./structures.md#encryption-context-3) MUST be constructed by - [Custom Encryption Context From Authenticated Encryption Context](#custom-encryption-context-from-authenticated-encryption-context) + [Encryption Context From Authenticated Branch Key Context](#encryption-context-from-authenticated-branch-key-context) -### Custom Encryption Context From Authenticated Encryption Context +### Encryption Context From Authenticated Branch Key Context -The custom encryption context is stored as map of UTF8 Encoded bytes. +The [encryption context](./structures.md#encryption-context) is stored as map of UTF8 Encoded bytes. -For every key in the [encryption context](./structures.md#encryption-context-3) +For every key in the [encryption context](./structures.md#encryption-context) the string `aws-crypto-ec:` + the UTF8 decode of this key -MUST exist as a key in the authenticated encryption context. -Also, the value in the [encryption context](./structures.md#encryption-context-3) for this key -MUST equal the value in the authenticated encryption context -for the constructed key. +MUST exist as a key in the authenticated branch key context. +Also, the value in the [encryption context](./structures.md#encryption-context) for this key +MUST equal the value in the authenticated branch key context +for the prefixed key. ### Example diff --git a/framework/structures.md b/framework/structures.md index 408bfe56..5ce1610f 100644 --- a/framework/structures.md +++ b/framework/structures.md @@ -414,7 +414,7 @@ This value MUST be a version 4 [UUID](https://www.ietf.org/rfc/rfc4122.txt). ##### Encryption Context -The [custom encryption context](#encryption-context) associated with this branch key. +The [encryption context](./structures.md#encryption-context) associated with all the items of this Branch Key. ##### KMS ARN @@ -467,7 +467,7 @@ the beacon key can be discarded. ##### Encryption Context -The [custom encryption context](#encryption-context) associated with this beacon key. +The [encryption context](./structures.md#encryption-context) is a key-value pair provided by users and is associated with the beacon key. ##### KMS ARN From ebec074507c4db06b2cb8b2396c73ef7ec05f454 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Tue, 5 Aug 2025 10:35:35 -0700 Subject: [PATCH 097/116] Update framework/branch-key-store.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 8bf34496..420fe25b 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -763,7 +763,7 @@ The Branch Key Context: ### ACTIVE Branch Key Context -The ACTIVE branch key is a copy of the DECRYPT_ONLY with the same `version`. +The ACTIVE branch key is a copy of a DECRYPT_ONLY with the same `version`. It is structured slightly differently so that the active version can be accessed quickly. In addition to the [branch key context](#branch-key-context): From 921c377a494d55205a13232f6f3693ffdb9109c4 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Tue, 5 Aug 2025 10:38:36 -0700 Subject: [PATCH 098/116] Apply suggestions from code review Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- framework/branch-key-store.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 420fe25b..2afcfa5b 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -768,7 +768,7 @@ It is structured slightly differently so that the active version can be accessed In addition to the [branch key context](#branch-key-context): -The ACTIVE branch key context value of the `type`key MUST equal to `"branch:ACTIVE"`. +The ACTIVE branch key context value of the key `type` MUST equal to `"branch:ACTIVE"`. The ACTIVE branch key context MUST have a `version` key. The `version` key MUST store the branch key version formatted like `"branch:version:"` + ``. @@ -804,7 +804,8 @@ Every key in the constructed [branch key context](#branch-key-context) except `tableName` MUST exist as a attribute in the AWS DDB response item. All attributes in the AWS DynamoDB response item MUST be of type string, -with the exception of hierarchy-version, which MUST be of type number. +with the exception of hierarchy-version, which MUST be of type number, +and `enc`, which MUST be of type binary. Every value in the constructed [branch key context](#branch-key-context) except the logical table name MUST equal the value with the same key in the AWS DDB response item. From d2732193225f62b134992bbafc19df98075a831e Mon Sep 17 00:00:00 2001 From: Andrew Jewell <107044381+ajewellamz@users.noreply.github.com> Date: Tue, 5 Aug 2025 14:41:45 -0400 Subject: [PATCH 099/116] chore: fix typos (#303) --- framework/branch-key-store.md | 16 ++++++++-------- framework/structures.md | 22 +++++++++++----------- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 2afcfa5b..150f70e7 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -47,18 +47,18 @@ The Keystore persists branch keys in DynamoDb that wrap multiple data keys. This creates a hierarchy where a branch key wraps multiple data keys and facilitates caching. These branch keys are generated using the [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) in Hierarchy Version `v1` or [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) in Hierarchy Version `v2`. -By creating and persisting a data key to an accesbile medium, +By creating and persisting a data key to an accessible medium, such as a DynamoDb table, distributed cryptographic agents can use a common, coordinated, cryptographic materials. This prevents distributed cryptographic agents from independently generating unique data keys that COULD BE coordinated, which leads to poor caching performance at decryption, -as each unqiue encrypting agent had a unqiue data key. +as each unique encrypting agent had a unique data key. This Keystore interface defines operations that any implementation of its specification must support and implement. -## Definitions +### Definitions - [Branch Key(s)](../structures.md#branch-key): Data keys that are reused to wrap unique data keys for envelope encryption. For security considerations on when to rotate the branch key, refer to [Appendix B](aws-kms/aws-kms-hierarchical-keyring.md#appendix-b-security-considerations-for-branch-key-rotation). @@ -329,7 +329,7 @@ This operation MUST create a [branch key](structures.md#branch-key) and a [beaco the [Branch Key and Beacon Key Creation](#branch-key-and-beacon-key-creation) section. If creation of the keys are successful, -the operation MUST call Amazon DynamoDB TransactWriteItems according to the [write key material](#writing-branch-key-and-beacon-key-to-keystore) section. +the operation MUST call Amazon DynamoDB TransactWriteItems according to the [write key material](#writing-branch-key-and-beacon-key-to-branch-key-store-table) section. If writing to the keystore succeeds, the operation MUST return the branch-key-id that maps to both @@ -373,10 +373,10 @@ the operation MUST use the `CiphertextBlob` as the wrapped Beacon Key. ##### Wrapped Beacon Key Creation `v2` The operation MUST create a map of strings, -the [branch key context for beacon keys](#beacon-key-branch-key-context). +the [branch key context for beacon keys](#beacon-branch-key-context). The operation MUST calculate the **SHA-384 Digest for the beacon key** -by [serializing](../structures.md#serialization) the [branch key context for beacon keys](#beacon-key-branch-key-context); +by [serializing](../structures.md#serialization) the [branch key context for beacon keys](#beacon-branch-key-context); the serialization MUST be done according to the [encryption context serialization specification](../structures.md#serialization). The operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). @@ -658,7 +658,7 @@ This operation MUST call AWS DDB `GetItem`. Every attribute except `enc` on the AWS DDB response item MUST be converted to a set of key value pairs (a Map) which is the [branch key context](#branch-key-context). Every key in the constructed branch key context except tableName MUST exist as a string attribute in the AWS DDB response item. -The [AWS KMS Encryption Context](#aws-kms-encryption-context) MUST be the [encryption context](#encryption-context), which is built from the branch key context by extracting the keys with prefix `aws-crypto-ec:` and then dropping the prefix. See [Encryption Context From Authenticated Branch Key Context](#encryption-context-from-authenticated-branch-key-context). +The [AWS KMS Encryption Context](#aws-kms-encryption-context) MUST be the [encryption context](./structures.md##encryption-context), which is built from the branch key context by extracting the keys with prefix `aws-crypto-ec:` and then dropping the prefix. See [Encryption Context From Authenticated Branch Key Context](#encryption-context-from-authenticated-branch-key-context). The operation MUST follow [AWS KMS Branch Key Decryption](#aws-kms-branch-key-decryption) to decrypt and authentication the branch key context. @@ -757,7 +757,7 @@ The Branch Key Context: - MUST have a `kms-arn` key who's value is valid KMS ARN - MUST have a `hierarchy-version` key who's value is either "1" or "2" - MUST NOT have a `enc` key -- MAY have one or more keys prefixed with `aws-crypto-ec:` which is the encyption context send by the customer. +- MAY have one or more keys prefixed with `aws-crypto-ec:` which is the encryption context send by the customer. The `aws-crypto-ec:` prefix is prepended by the library - MUST NOT have any other keys apart from the ones mentioned above if `hierarchy-version` is "2" diff --git a/framework/structures.md b/framework/structures.md index 5ce1610f..05d240e0 100644 --- a/framework/structures.md +++ b/framework/structures.md @@ -149,12 +149,12 @@ take the following form: | [Key Value Pair Count](#key-value-pair-count) | 2 | UInt16 | | [Key Value Pair Entries](#key-value-pair-entries) | Variable. Determined by the count and length of each key-value pair. | [Key Value Pair Entries](#key-value-pair-entries) | -###### Key Value Pair Count +##### Key Value Pair Count The number of key-value pairs within the [Key Value Pair Entries](#key-value-pair-entries) field. The value of this field MUST be greater than 0. -###### Key Value Pair Entries +##### Key Value Pair Entries A sequence of one or more key-value pair entries. @@ -430,12 +430,12 @@ Timestamp in ISO 8601 format in UTC, to microsecond precision, of when the mater ## Beacon Key Materials -#### Implementations +### Implementations | Language | Confirmed Compatible with Spec Version | Minimum Version Confirmed | Implementation | | -------- | -------------------------------------- | ------------------------- | -------------- | -#### Structure +### Structure Beacon Key materials are a structure containing materials that are used in structured encryption. @@ -455,7 +455,7 @@ This structure MAY include the following fields: - [Beacon Key](#beacon-key) - [HMAC Keys](#hmac-keys) -##### Beacon Key +#### Beacon Key The Beacon Key that is stored in the [Keystore](branch-key-store.md). @@ -465,28 +465,28 @@ because the beacon key is used to derive [HMAC Keys](#hmac-keys). Once this has been complete, the beacon key can be discarded. -##### Encryption Context +#### Encryption Context The [encryption context](./structures.md#encryption-context) is a key-value pair provided by users and is associated with the beacon key. -##### KMS ARN +#### KMS ARN The AWS KMS Key ARN used to protect these materials. -##### Create Time +#### Create Time Timestamp in ISO 8601 format in UTC, to microsecond precision, that the Material was generated. -##### Hierarchy Version +#### Hierarchy Version [Schema Version of the Branch Key](branch-key-store.md#hierarchy-version). -##### Beacon Key Id +#### Beacon Key Id The Beacon key id that was used to obtain the beacon key from a [Keystore](branch-key-store.md) -##### HMAC Keys +#### HMAC Keys A key-value mapping of arbitrary strings to bytes. From 10327a3e7bda59e2fc56d80bab564dd8660992b1 Mon Sep 17 00:00:00 2001 From: Andy Jewell Date: Wed, 6 Aug 2025 10:03:37 -0700 Subject: [PATCH 100/116] m --- framework/branch-key-store.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 150f70e7..5eebb9fe 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -580,8 +580,12 @@ The `kms-arn` stored in the DDB table MUST NOT change as a result of this operat even if the KeyStore is configured with a `KMS MRKey ARN` that does not exactly match the stored ARN. If such were allowed, clients using non-MRK KeyStores might suddenly stop working. -The values on the AWS DDB response item -MUST be authenticated according to [authenticating a keystore item for item with hierarchy version v1](#authenticating-a-branch-keystore-item-for-item-with-hierarchy-version-v1) or [authenticating a keystore item for item with hierarchy version v2](#authenticating-a-branch-keystore-item-for-item-with-hierarchy-version-v2) based on schema version of the branch key item. +If the `hierarchy-version` is `v1`, the values on the AWS DDB response item MUST be authenticated according to +[authenticating a keystore item for item with hierarchy version v1](#authenticating-a-branch-keystore-item-for-item-with-hierarchy-version-v1). + +If the `hierarchy-version` is `v2`, the values on the AWS DDB response item MUST be authenticated according to +[authenticating a keystore item for item with hierarchy version v2](#authenticating-a-branch-keystore-item-for-item-with-hierarchy-version-v2). + If the item fails to authenticate this operation MUST fail. If the `hierarchy-version` is `v1`, @@ -756,7 +760,7 @@ The Branch Key Context: - MUST have a `tablename` key who's value is the logicalKeyStoreName - MUST have a `kms-arn` key who's value is valid KMS ARN - MUST have a `hierarchy-version` key who's value is either "1" or "2" -- MUST NOT have a `enc` key +- MUST NOT have an `enc` key - MAY have one or more keys prefixed with `aws-crypto-ec:` which is the encryption context send by the customer. The `aws-crypto-ec:` prefix is prepended by the library - MUST NOT have any other keys apart from the ones mentioned above if `hierarchy-version` is "2" From c282b601f9fe3be4d175daae9be4bc39d2137de4 Mon Sep 17 00:00:00 2001 From: Andy Jewell Date: Wed, 13 Aug 2025 11:52:03 -0400 Subject: [PATCH 101/116] m --- framework/branch-key-store.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 5eebb9fe..304d8bbd 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -349,7 +349,8 @@ If the `hierarchy-version` is `v1`, the wrapped beacon key MUST be created according to [Wrapped Beacon Key Creation `v1`](#wrapped-beacon-key-creation-v1) and the wrapped branch keys MUST be created according to [Wrapped Branch Key Creation `v1`](#wrapped-branch-key-creation-v1); -else the `hierarchy-version` MUST be `v2`, + +If the `hierarchy-version` is be `v2`, the wrapped beacon Key MUST be created according to [Wrapped Beacon Key Creation `v2`](#wrapped-beacon-key-creation-v2) and the wrapped branch keys MUST be created according to [Wrapped Branch Key Creation `v2`](#wrapped-branch-key-creation-v2). @@ -399,10 +400,10 @@ creating the **beacon plain-text tuple**. 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` Must be the **beacon plain-text tuple** +- `Plaintext` MUST be the **beacon plain-text tuple**. - `KeyId` MUST be the `kms-arn`. - `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -- `EncryptionContext` MUST be the `encryption-context` +- `EncryptionContext` MUST be the `encryption-context`. If the call to AWS KMS Encrypt succeeds, the operation MUST use the Encrypt result `CiphertextBlob` @@ -787,7 +788,7 @@ The `type` value MUST store the branch key version formatted like `"branch:versi In addition to the [branch key context](#branch-key-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 include a key `type` and the value MUST be `"beacon:ACTIVE"`. The Beacon key branch key context MUST NOT have a `version` key. ## AWS KMS Encryption Context From 4ff85810b1103d79140b0044886d64ff2069a7ef Mon Sep 17 00:00:00 2001 From: Andy Jewell Date: Thu, 14 Aug 2025 12:54:53 -0400 Subject: [PATCH 102/116] m --- framework/branch-key-store.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 304d8bbd..f503a655 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -377,8 +377,8 @@ The operation MUST create a map of strings, the [branch key context for beacon keys](#beacon-branch-key-context). The operation MUST calculate the **SHA-384 Digest for the beacon key** -by [serializing](../structures.md#serialization) the [branch key context for beacon keys](#beacon-branch-key-context); -the serialization MUST be done according to the [encryption context serialization specification](../structures.md#serialization). +by [serializing](../structures.md#serialization) the [branch key context for beacon keys](#beacon-branch-key-context), +according to the [encryption context serialization specification](../structures.md#serialization). The operation MUST call [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). The call to AWS KMS GenerateDataKey MUST use the configured AWS KMS client to make the call. @@ -479,13 +479,13 @@ The operation MUST concatenate the **SHA-384 Digest for the `DECRYPT_ONLY`** with the plain-text Branch Key, creating the **`DECRYPT_ONLY` plain-text tuple**. -The operation MUST call [AWS KMS API Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) +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` **the `DECRYPT_ONLY` plain-text tuple** +- `Plaintext` MUST be **the `DECRYPT_ONLY` plain-text tuple**. - `KeyId` MUST be the `kms-arn`. -- `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -- `EncryptionContext` MUST be the `encryption-context` +- `GrantTokens` MUST be the [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token) of this keystore. +- `EncryptionContext` MUST be the `encryption-context`. If the call to AWS KMS Encrypt succeeds, the operation MUST use the Encrypt result `CiphertextBlob` @@ -498,10 +498,10 @@ creating the **the `ACTIVE` plain-text tuple**. 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` **the `ACTIVE` plain-text tuple** +- `Plaintext` MUST be **the `ACTIVE` plain-text tuple**. - `KeyId` MUST be the `kms-arn`. -- `GrantTokens` MUST be this keystore's [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token). -- `EncryptionContext` MUST be the `encryption-context` +- `GrantTokens` MUST be the [grant tokens](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#grant_token) of this keystore. +- `EncryptionContext` MUST be the `encryption-context`. If the call to AWS KMS Encrypt succeeds, the operation MUST use the Encrypt result `CiphertextBlob` From 1c1ebce5a178b9bb1090108861b07772fce2c891 Mon Sep 17 00:00:00 2001 From: Andy Jewell Date: Mon, 18 Aug 2025 10:30:04 -0400 Subject: [PATCH 103/116] m --- framework/branch-key-store.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index f503a655..f8dda179 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -590,8 +590,10 @@ If the `hierarchy-version` is `v2`, the values on the AWS DDB response item MUST If the item fails to authenticate this operation MUST fail. If the `hierarchy-version` is `v1`, -the wrapped Branch Keys, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Beacon Key Creation `v1`](#wrapped-beacon-key-creation-v1); -else the `hierarchy-version` MUST be `v2`, +the wrapped Branch Keys, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Beacon Key Creation `v1`](#wrapped-beacon-key-creation-v1). + +If the `hierarchy-version` is `v2`, +the wrapped Branch Keys, DECRYPT_ONLY and ACTIVE, MUST be created according to [Wrapped Branch Key Creation `v2`](#wrapped-branch-key-creation-v2). To add the new branch key to the keystore, From 01a3bc4c12b65461da5d402c8900c70c22a18520 Mon Sep 17 00:00:00 2001 From: Andy Jewell Date: Tue, 19 Aug 2025 15:17:53 -0400 Subject: [PATCH 104/116] m --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index f8dda179..28a4cd08 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -624,7 +624,7 @@ List of TransactWriteItem: - “hierarchy-version” (N): either `1` or `2`, depending on the `hierarchy-version` - Every key-value pair in the [encryption context](./structures.md#encryption-context) provided by users and is associated with the branch key MUST be added with an Attribute Name of `aws-crypto-ec:` + the Key and Attribute Value (S) of the value. - - ConditionExpression: `attribute_exists(branch-key-id) AND enc = :encOld` + - ConditionExpression: `enc = :encOld` - ExpressionAttributeValues: `{":encOld" := DDB.AttributeValue.B(oldCiphertextBlob)}` - TableName: the configured Table Name From cbe0acedd75ef5e8100261f1334ab26056c82abf Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Mon, 25 Aug 2025 11:46:49 -0700 Subject: [PATCH 105/116] Un-modeled Branch Key Context Key Values --- .../protect_branch_key_without_kms_ec.md | 2 + ...n-modeled_branch_key_context_key_values.md | 69 +++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md diff --git a/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md b/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md index 5c30682a..4c382f4a 100644 --- a/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md +++ b/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md @@ -39,6 +39,8 @@ an actor cannot modify the **Branch Key Context Digest**. 1.5 considers a local HMAC operation, with the plain-text AES-256 being the key. +See [Un-modeled Branch Key Context Key Values](./un-modeled_branch_key_context_key_values.md) for what did we do about un-prefixed context of a Branch Key. + ## 1.2 Getting Branch Keys The Branch Key Item is read from DDB table; diff --git a/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md b/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md new file mode 100644 index 00000000..d3725ed4 --- /dev/null +++ b/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md @@ -0,0 +1,69 @@ +[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved." +[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0" + +# Un-modeled Branch Key Context Key Values + +# Definitions/Background + +See [background](./background.md) for an introduction to Hierarchy Version 2 (HV-2). + +## Problem + +The issue at hand is what to do about un-prefixed context of a Branch Key. + +These are any members of the Branch Key's Context who's key is not prefixed by aws-crypto-ec: OR another reserved Branch Key Context Key Name, such as kms-arn or hierarchy-version. +Such Key-Value pairs were NOT added to a Branch Key Item by a Crypto Tools product. +But they could have been added by an MPL Consumer manually. +As long as this is done properly, the AWS KMS Hierarchical Keyring will use these manually modified Branch Keys. + +# Observations + +### HV-2 Obs 1: Digest makes out-of-library changes more difficult + +Hierarchy Version 2 makes out-of-library changes more difficult, as the Branch Key Context is not protected by KMS Encryption Context, but by a Digest on a canonicalization of the Branch Key Context. +Thus, changing an HV-2 Branch Key can only be done by using the library or a specification compliant implementation. + +### HV-2 Obs 2: No prefix to KMS removes an incentive + +The only motivation for such out-of-library modifications was for customers who needed to call KMS without the aws-crypto-ec: prefix, such that they can call KMS with the same Encryption Context as their other integrations. +(For example, the KMS Keyring, as compared the Hierarchical Keyring.) +Hierarchy Version 2 does not call KMS with this prefix; thus, this motivation is no longer valid. + +# Options + +## Option 1: Entirely Prevent this in HV-2 + +Hierarchy Version 2 addresses a strong motivation for MPL Consumers to remove the prefix; while there might be other motivations (for example, GSI in DDB), Crypto Tools is un-aware of them. +Thus, it seems reasonable for Hierarchy Version 2 to have a much stricter data model than Hierarchy Version 1. +This data model would ensure that every Branch Key Context Key Name of a Branch Key Item is either: + +- a reserved key name +- prefixed with aws-crypto-ec: + +However, when/if a feature to mutate the branch key scheme ever exists then this means that Hierarchy Version 1 Branch Keys that were modified outside of the library cannot be "Mutated" to Hierarchy Version 2 unless the modification is reverted. + +Risk: +Crypto Tools (CT) knows that at least one CT customer are pursuing out-of-library changes. If CT goes with this option, CT SHOULD clearly document: + +1. HV-2 has a stricter data model +2. In general, CT products do not support out-of-library behavior + +Despite the risk, the author considers this Option the best path forward, and will ensure its implementation unless someone objects. + +## Option 2: Prevent but preserve + +If a feature to mutate the branch key schema ever exists, mutations to HV-2 could preserve the un-prefixed context, if they were present on the HV-1 Branch Key. +However, there is no way for MPL Consumers to modify this un-prefixed context, as the relatively simple kms:ReEncrypt pattern to make the out-of-library change will not update the digest in HV-2, and therefore Branch Key modified this way will be considered by the library to be invalid. +The way HV-2 puts encryption context In Digest also advocates for not maintaining an out-of-library change. +As such, CT should implement Option 1. + +## Option 3: Reverse the prefix + +Crypto Tools could "flip" the prefix; prefixing the reserved context instead of the Encryption Context. However, this is a breaking change, as two members of the reserved context are the partition key (branch-key-id) and the sort key (type) of the DynamoDB table. +Thus, it would have to be an optional behavior, and it would be challenging to operate in a mixed state, as that would likely involve two DynamoDB indexes (either via two DynamoDB tables or one with table a GSI). +If Crypto Tools' customers asked for no-prefixing in the DynamoDB, or a reversing of the prefix, Crypto Tools could implement a different feature for that (or the customers could write a custom keyring; though those are currently difficult with DB-ESDK because of a quite breaking change in the keyring interface). +Thus, for now, Crypto Tools should not pick up reversing the prefix; changing the data model was correctly labeled out of scope in the beginning and we should stick to that. + +# Conclusion + +The team decided to go with option 1. From 3825803e88faf513ff689c205117bf894d93ee73 Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 28 Aug 2025 10:44:36 -0700 Subject: [PATCH 106/116] auto commit --- .../un-modeled_branch_key_context_key_values.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md b/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md index d3725ed4..f001b68e 100644 --- a/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md +++ b/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md @@ -11,7 +11,7 @@ See [background](./background.md) for an introduction to Hierarchy Version 2 (HV The issue at hand is what to do about un-prefixed context of a Branch Key. -These are any members of the Branch Key's Context who's key is not prefixed by aws-crypto-ec: OR another reserved Branch Key Context Key Name, such as kms-arn or hierarchy-version. +These are any members of the Branch Key's Context whose key is not prefixed by aws-crypto-ec: OR another reserved Branch Key Context Key Name, such as kms-arn or hierarchy-version. Such Key-Value pairs were NOT added to a Branch Key Item by a Crypto Tools product. But they could have been added by an MPL Consumer manually. As long as this is done properly, the AWS KMS Hierarchical Keyring will use these manually modified Branch Keys. @@ -20,7 +20,7 @@ As long as this is done properly, the AWS KMS Hierarchical Keyring will use thes ### HV-2 Obs 1: Digest makes out-of-library changes more difficult -Hierarchy Version 2 makes out-of-library changes more difficult, as the Branch Key Context is not protected by KMS Encryption Context, but by a Digest on a canonicalization of the Branch Key Context. +Hierarchy Version 2 makes out-of-library changes more difficult, as the Branch Key Context is not protected by KMS Encryption Context, but by a digest on a canonicalization of the Branch Key Context. Thus, changing an HV-2 Branch Key can only be done by using the library or a specification compliant implementation. ### HV-2 Obs 2: No prefix to KMS removes an incentive @@ -33,7 +33,7 @@ Hierarchy Version 2 does not call KMS with this prefix; thus, this motivation is ## Option 1: Entirely Prevent this in HV-2 -Hierarchy Version 2 addresses a strong motivation for MPL Consumers to remove the prefix; while there might be other motivations (for example, GSI in DDB), Crypto Tools is un-aware of them. +Hierarchy Version 2 addresses a strong motivation for MPL Consumers to remove the prefix; while there might be other motivations (for example, GSI in DDB), Crypto Tools is unaware of them. Thus, it seems reasonable for Hierarchy Version 2 to have a much stricter data model than Hierarchy Version 1. This data model would ensure that every Branch Key Context Key Name of a Branch Key Item is either: From f0fe48f6629c90b0faa46edfed7f3499c951309e Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 28 Aug 2025 10:50:07 -0700 Subject: [PATCH 107/116] auto commit --- ...un-modeled_branch_key_context_key_values.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md b/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md index f001b68e..9b8a51c1 100644 --- a/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md +++ b/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md @@ -11,9 +11,9 @@ See [background](./background.md) for an introduction to Hierarchy Version 2 (HV The issue at hand is what to do about un-prefixed context of a Branch Key. -These are any members of the Branch Key's Context whose key is not prefixed by aws-crypto-ec: OR another reserved Branch Key Context Key Name, such as kms-arn or hierarchy-version. +These are any members of the Branch Key's Context whose key is not prefixed by `aws-crypto-ec:` OR another reserved Branch Key Context Key Name, such as `kms-arn` or `hierarchy-version`. Such Key-Value pairs were NOT added to a Branch Key Item by a Crypto Tools product. -But they could have been added by an MPL Consumer manually. +But they could have been added by an AWS Cryptographic Material Providers Library (MPL) Consumer manually. As long as this is done properly, the AWS KMS Hierarchical Keyring will use these manually modified Branch Keys. # Observations @@ -25,7 +25,7 @@ Thus, changing an HV-2 Branch Key can only be done by using the library or a spe ### HV-2 Obs 2: No prefix to KMS removes an incentive -The only motivation for such out-of-library modifications was for customers who needed to call KMS without the aws-crypto-ec: prefix, such that they can call KMS with the same Encryption Context as their other integrations. +The only motivation for such out-of-library modifications was for customers who needed to call KMS without the `aws-crypto-ec:` prefix, such that they can call KMS with the same Encryption Context as their other integrations. (For example, the KMS Keyring, as compared the Hierarchical Keyring.) Hierarchy Version 2 does not call KMS with this prefix; thus, this motivation is no longer valid. @@ -33,14 +33,14 @@ Hierarchy Version 2 does not call KMS with this prefix; thus, this motivation is ## Option 1: Entirely Prevent this in HV-2 -Hierarchy Version 2 addresses a strong motivation for MPL Consumers to remove the prefix; while there might be other motivations (for example, GSI in DDB), Crypto Tools is unaware of them. +Hierarchy Version 2 addresses a strong motivation for MPL Consumers to remove the prefix; while there might be other motivations (for example, Global Secondary Index (GSI) in Amazon DynamoDB), Crypto Tools is unaware of them. Thus, it seems reasonable for Hierarchy Version 2 to have a much stricter data model than Hierarchy Version 1. This data model would ensure that every Branch Key Context Key Name of a Branch Key Item is either: - a reserved key name -- prefixed with aws-crypto-ec: +- prefixed with `aws-crypto-ec:` -However, when/if a feature to mutate the branch key scheme ever exists then this means that Hierarchy Version 1 Branch Keys that were modified outside of the library cannot be "Mutated" to Hierarchy Version 2 unless the modification is reverted. +However, when/if a feature to mutate the Branch Key scheme ever exists then this means that Hierarchy Version 1 Branch Keys that were modified outside of the library cannot be "Mutated" to Hierarchy Version 2 unless the modification is reverted. Risk: Crypto Tools (CT) knows that at least one CT customer are pursuing out-of-library changes. If CT goes with this option, CT SHOULD clearly document: @@ -52,15 +52,17 @@ Despite the risk, the author considers this Option the best path forward, and wi ## Option 2: Prevent but preserve -If a feature to mutate the branch key schema ever exists, mutations to HV-2 could preserve the un-prefixed context, if they were present on the HV-1 Branch Key. +If a feature to mutate the Branch Key schema ever exists, mutations to HV-2 could preserve the un-prefixed context, if they were present on the HV-1 Branch Key. However, there is no way for MPL Consumers to modify this un-prefixed context, as the relatively simple kms:ReEncrypt pattern to make the out-of-library change will not update the digest in HV-2, and therefore Branch Key modified this way will be considered by the library to be invalid. -The way HV-2 puts encryption context In Digest also advocates for not maintaining an out-of-library change. + +The way HV-2 puts Encryption Context In Digest also advocates for not maintaining an out-of-library change. As such, CT should implement Option 1. ## Option 3: Reverse the prefix Crypto Tools could "flip" the prefix; prefixing the reserved context instead of the Encryption Context. However, this is a breaking change, as two members of the reserved context are the partition key (branch-key-id) and the sort key (type) of the DynamoDB table. Thus, it would have to be an optional behavior, and it would be challenging to operate in a mixed state, as that would likely involve two DynamoDB indexes (either via two DynamoDB tables or one with table a GSI). + If Crypto Tools' customers asked for no-prefixing in the DynamoDB, or a reversing of the prefix, Crypto Tools could implement a different feature for that (or the customers could write a custom keyring; though those are currently difficult with DB-ESDK because of a quite breaking change in the keyring interface). Thus, for now, Crypto Tools should not pick up reversing the prefix; changing the data model was correctly labeled out of scope in the beginning and we should stick to that. From fb3cf07f7c560d8d474093639e390a031cc066bb Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 28 Aug 2025 10:53:28 -0700 Subject: [PATCH 108/116] auto commit --- .../un-modeled_branch_key_context_key_values.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md b/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md index 9b8a51c1..34d03938 100644 --- a/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md +++ b/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md @@ -43,7 +43,7 @@ This data model would ensure that every Branch Key Context Key Name of a Branch However, when/if a feature to mutate the Branch Key scheme ever exists then this means that Hierarchy Version 1 Branch Keys that were modified outside of the library cannot be "Mutated" to Hierarchy Version 2 unless the modification is reverted. Risk: -Crypto Tools (CT) knows that at least one CT customer are pursuing out-of-library changes. If CT goes with this option, CT SHOULD clearly document: +Crypto Tools (CT) knows that at least one CT customer is pursuing out-of-library changes. If CT goes with this option, CT SHOULD clearly document: 1. HV-2 has a stricter data model 2. In general, CT products do not support out-of-library behavior @@ -53,7 +53,7 @@ Despite the risk, the author considers this Option the best path forward, and wi ## Option 2: Prevent but preserve If a feature to mutate the Branch Key schema ever exists, mutations to HV-2 could preserve the un-prefixed context, if they were present on the HV-1 Branch Key. -However, there is no way for MPL Consumers to modify this un-prefixed context, as the relatively simple kms:ReEncrypt pattern to make the out-of-library change will not update the digest in HV-2, and therefore Branch Key modified this way will be considered by the library to be invalid. +However, there is no way for MPL Consumers to modify this un-prefixed context, as the relatively simple `kms:ReEncrypt` pattern to make the out-of-library change will not update the digest in HV-2, and therefore Branch Key modified this way will be considered by the library to be invalid. The way HV-2 puts Encryption Context In Digest also advocates for not maintaining an out-of-library change. As such, CT should implement Option 1. From edbd2622fb21c0609e430fb78270d0089f7a01bb Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Thu, 28 Aug 2025 10:54:21 -0700 Subject: [PATCH 109/116] auto commit --- .../un-modeled_branch_key_context_key_values.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md b/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md index 34d03938..879da722 100644 --- a/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md +++ b/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md @@ -55,7 +55,7 @@ Despite the risk, the author considers this Option the best path forward, and wi If a feature to mutate the Branch Key schema ever exists, mutations to HV-2 could preserve the un-prefixed context, if they were present on the HV-1 Branch Key. However, there is no way for MPL Consumers to modify this un-prefixed context, as the relatively simple `kms:ReEncrypt` pattern to make the out-of-library change will not update the digest in HV-2, and therefore Branch Key modified this way will be considered by the library to be invalid. -The way HV-2 puts Encryption Context In Digest also advocates for not maintaining an out-of-library change. +The way HV-2 puts Encryption Context in digest also advocates for not maintaining an out-of-library change. As such, CT should implement Option 1. ## Option 3: Reverse the prefix From 10edc73fc5d10b60ec28f19eb1cb694a80afb924 Mon Sep 17 00:00:00 2001 From: seebees Date: Thu, 28 Aug 2025 13:26:21 -0700 Subject: [PATCH 110/116] Update changes/2025-06-30_branch_keys_version_2/background.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/background.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index ab3d1dd7..2b71f776 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -138,8 +138,8 @@ KMS Key Grants can have restricted but unique conditions. Many potential Branch Key Customers are prevented from using the Hierarchy Keyring, as they have pre-existing Key Policies with their tenants -that cannot be met if the KMS Encryption Context is populated -by the Branch Key's Context. +that cannot be met if the KMS Encryption Context is transformed +by the Branch Key Store. # Requirements From 39b1cb38cc804d41ddfc660ff43282218f2d2e5c Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Thu, 28 Aug 2025 15:42:14 -0700 Subject: [PATCH 111/116] Update framework/branch-key-store.md Co-authored-by: Lucas McDonald --- framework/branch-key-store.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/branch-key-store.md b/framework/branch-key-store.md index 28a4cd08..3c4b4c51 100644 --- a/framework/branch-key-store.md +++ b/framework/branch-key-store.md @@ -45,7 +45,7 @@ A Keystore persists hierarchical data that allows customers to call AWS KMS less often. The Keystore persists branch keys in DynamoDb that wrap multiple data keys. This creates a hierarchy where a branch key wraps multiple data keys and facilitates caching. -These branch keys are generated using the [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) in Hierarchy Version `v1` or [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) in Hierarchy Version `v2`. +These branch keys are generated using the [AWS KMS API GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) in Hierarchy Version `v1` and [AWS KMS API GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) in Hierarchy Version `v2`. By creating and persisting a data key to an accessible medium, such as a DynamoDb table, From 966b22c4f247d9343d5cd86a52ba7838290ae031 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Thu, 28 Aug 2025 15:42:52 -0700 Subject: [PATCH 112/116] Update changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md --- .../protect_branch_key_without_kms_ec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md b/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md index 4c382f4a..9bb71116 100644 --- a/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md +++ b/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md @@ -9,7 +9,7 @@ See [Definitions](./background.md#definitions). # 1 Plain-text Commitment instead of KMS Encryption Context -The KMS RSA Keyring has already solved the need +The KMS RSA Keyring and ECDH Keyrings has already solved the need to substitute KMS Encryption Context; we need only adapt that solution and apply it here. From c26bf4b8131960d0f4bc95db88c202d539958acf Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Thu, 28 Aug 2025 15:43:09 -0700 Subject: [PATCH 113/116] Update changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- .../un-modeled_branch_key_context_key_values.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md b/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md index 879da722..99d821c9 100644 --- a/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md +++ b/changes/2025-06-30_branch_keys_version_2/un-modeled_branch_key_context_key_values.md @@ -11,7 +11,7 @@ See [background](./background.md) for an introduction to Hierarchy Version 2 (HV The issue at hand is what to do about un-prefixed context of a Branch Key. -These are any members of the Branch Key's Context whose key is not prefixed by `aws-crypto-ec:` OR another reserved Branch Key Context Key Name, such as `kms-arn` or `hierarchy-version`. +These are any members of the Branch Key's Context whose key is not prefixed by `aws-crypto-ec:` OR not another reserved Branch Key Context Key Name, such as `kms-arn` or `hierarchy-version`. Such Key-Value pairs were NOT added to a Branch Key Item by a Crypto Tools product. But they could have been added by an AWS Cryptographic Material Providers Library (MPL) Consumer manually. As long as this is done properly, the AWS KMS Hierarchical Keyring will use these manually modified Branch Keys. From 8c23b6199a254e9c5ee728bfe2eb5bd716525eb6 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Thu, 28 Aug 2025 15:43:27 -0700 Subject: [PATCH 114/116] Update changes/2025-06-30_branch_keys_version_2/background.md Co-authored-by: Tony Knapp <5892063+texastony@users.noreply.github.com> --- changes/2025-06-30_branch_keys_version_2/background.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index 2b71f776..d3573e7f 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -17,7 +17,7 @@ The Branch Key Store's Branch Keys are designated as `"hierarchy-version" : "1"` This document proposes changes to theses Branch Keys; when HV-1 is written, -we mean a Branch Key Item written by the Branch Key Store v0.2.0 to v0.7.0. +we mean a Branch Key Item written by the Branch Key Store prior to this change, which will always describe it's self as `"hierarchy-version" : "1"`. ## Branch Key's Cryptographic Material From db09f47a159682d1bb1a52fa4e0036c309d61ef9 Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Thu, 28 Aug 2025 15:43:38 -0700 Subject: [PATCH 115/116] Update changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: José Corella <39066999+josecorella@users.noreply.github.com> --- .../protect_branch_key_without_kms_ec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md b/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md index 9bb71116..bbc03b13 100644 --- a/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md +++ b/changes/2025-06-30_branch_keys_version_2/protect_branch_key_without_kms_ec.md @@ -39,7 +39,7 @@ an actor cannot modify the **Branch Key Context Digest**. 1.5 considers a local HMAC operation, with the plain-text AES-256 being the key. -See [Un-modeled Branch Key Context Key Values](./un-modeled_branch_key_context_key_values.md) for what did we do about un-prefixed context of a Branch Key. +See [Un-modeled Branch Key Context Key Values](./un-modeled_branch_key_context_key_values.md) for what we did about un-prefixed context of a Branch Key. ## 1.2 Getting Branch Keys From fc08e883a77d1e4b12646c9191d42f75e9c2ed8a Mon Sep 17 00:00:00 2001 From: rishav-karanjit Date: Fri, 29 Aug 2025 09:26:38 -0700 Subject: [PATCH 116/116] formatting --- changes/2025-06-30_branch_keys_version_2/background.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/2025-06-30_branch_keys_version_2/background.md b/changes/2025-06-30_branch_keys_version_2/background.md index d3573e7f..c70bb935 100644 --- a/changes/2025-06-30_branch_keys_version_2/background.md +++ b/changes/2025-06-30_branch_keys_version_2/background.md @@ -17,7 +17,7 @@ The Branch Key Store's Branch Keys are designated as `"hierarchy-version" : "1"` This document proposes changes to theses Branch Keys; when HV-1 is written, -we mean a Branch Key Item written by the Branch Key Store prior to this change, which will always describe it's self as `"hierarchy-version" : "1"`. +we mean a Branch Key Item written by the Branch Key Store prior to this change, which will always describe it's self as `"hierarchy-version" : "1"`. ## Branch Key's Cryptographic Material