From 8db68554ef9075c7f0af0bdd0f6b573d99178c6f Mon Sep 17 00:00:00 2001 From: Rishav karanjit Date: Wed, 25 Jun 2025 10:19:31 -0700 Subject: [PATCH 01/96] 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 02/96] 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 03/96] 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 04/96] 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 05/96] 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 06/96] 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 07/96] 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 08/96] 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 09/96] 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 10/96] 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 11/96] 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 12/96] 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 13/96] 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 14/96] 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 15/96] 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 16/96] 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 17/96] 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 18/96] 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 19/96] 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 20/96] 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 21/96] 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 22/96] 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 23/96] 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 24/96] 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 25/96] 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 26/96] 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 27/96] 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 28/96] 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 29/96] 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 30/96] 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 31/96] 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 32/96] 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 33/96] 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 34/96] 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 35/96] 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 36/96] 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 37/96] 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 38/96] 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 39/96] 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 40/96] 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 41/96] 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 42/96] 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 43/96] 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 44/96] 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 45/96] 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 46/96] 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 47/96] 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 48/96] 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 49/96] 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 50/96] 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 51/96] 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 52/96] 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 53/96] 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 54/96] 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 55/96] 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 56/96] 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 57/96] 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 58/96] 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 59/96] 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 60/96] 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 61/96] 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 62/96] 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 63/96] 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 64/96] 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 65/96] 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 66/96] 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 67/96] 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 68/96] 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 69/96] 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 70/96] 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 71/96] 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 72/96] 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 73/96] 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 74/96] 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 75/96] 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 76/96] 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 77/96] 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 78/96] 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 79/96] 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 80/96] 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 81/96] 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 82/96] 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 83/96] 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 84/96] 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 85/96] 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 86/96] 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 87/96] 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 88/96] 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 89/96] 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 90/96] 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 91/96] 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 92/96] 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 93/96] 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 94/96] 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 95/96] 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 96/96] 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