feat(keystore): Re-add mitigate version race condition in branch key store (#301)

Author: rishav-karanjit

changes/2025-01-16_key-store-mitigate-update-race/background.md

@@ -1,7 +1,7 @@
 [//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
 [//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
 
-# Mitigate Update Race in Branch Key Store
+# Mitigate Version Race Condition in Branch Key Store
 
 # Definitions
 
@@ -18,11 +18,9 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
 # Background
 
 The [branch key store](../../framework/branch-key-store.md) needs to persist branch key versions.
-DynamoDB was selected as an easy-to-use option,
-with an interface later introduced to allow customers
-to implement other storage options.
+As of July 22, 2025, DynamoDB is the only option of storage for branch key storage.
 
-The behavior of the `WriteNewEncryptedBranchKeyVersion` operation
+The behavior of the `VersionKey` operation
 leaves open a possibility for a normally benign overwrite
 of the cipher-text of a Branch Key,
 should two or more agents a Version a Branch Key simultaneously.
@@ -96,8 +94,6 @@ on the old cipher-text value.
 This refactors:
 
 - The [Branch Key Store's VersionKey](../../framework/branch-key-store.md#versionkey)
-- The [Key Storage's WriteNewEncryptedBranchKeyVersion](../../framework/key-store/key-storage.md#writenewencryptedbranchkeyversion)
-- The [Dynamodb Key Storage's WriteNewEncryptedBranchKeyVersion](../../framework/key-store/dynamodb-key-storage.md#writenewencryptedbranchkeyversion)
 
 These refactors are to use the old Active's cipher-text
 as the optimistic lock.

framework/branch-key-store.md

@@ -5,10 +5,12 @@
 
 ## Version
 
-0.8.0
+0.9.0
 
 ### Changelog
 
+- 0.9.0
+  - Re-add [Mitigate Version Race Condition in the Branch Key Store](../changes/2025-01-16_key-store-mitigate-update-race/background.md) with DynamoDB as the only branch key storage option
 - 0.8.0
   - Revert Key store storage option. This reverts changes in 0.6.0 and 0.7.0
 - 0.7.1
@@ -476,7 +478,8 @@ List of TransactWriteItem:
     - “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)`
+  - ConditionExpression: `attribute_exists(branch-key-id) AND enc = :encOld`
+  - ExpressionAttributeValues: `{":encOld" := DDB.AttributeValue.B(oldCiphertextBlob)}`
   - TableName: the configured Table Name
 
 TransactWriteItemRequest:
@@ -486,6 +489,10 @@ TransactWriteItemRequest:
 If DDB TransactWriteItems is successful, this operation MUST return a successful response containing no additional data.
 Otherwise, this operation MUST yield an error.
 
+The condition expression for the Active Input ensures
+the Active Item in DynamoDB has not changed since it was read.
+This prevents overwrites due to a race in updating the Active Item.
+
 #### Authenticating a Keystore item
 
 The operation MUST use the configured `KMS SDK Client` to authenticate the value of the keystore item.