Skip to content

Commit e5b6c47

Browse files
seebeesseebees
committed
adding duvet anotations
1 parent 78396d7 commit e5b6c47

File tree

3 files changed

+122
-8
lines changed

3 files changed

+122
-8
lines changed

‎modules/branch-keystore-node/src/branch_keystore_helpers.ts

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,6 @@ export async function getBranchKeyItem(
5454
partitionValue: string,
5555
sortValue: string
5656
): Promise<BranchKeyItem> {
57-
process.env
5857
// create a getItem command with the querying partition and sort keys
5958
// send the query for DDB to run
6059
// get the response
@@ -97,8 +96,8 @@ export async function getBranchKeyItem(
9796
* if there are additional fields within the response item that
9897
* don't follow the proper custom encryption context key naming convention
9998
*/
100-
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedactivebranchkey
101-
//# The AWS DDB response MUST contain the fields defined in the [branch keystore record format](#record-format).
99+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#record-format
100+
//# A branch key record MUST include the following key-value pairs:
102101
export function validateBranchKeyRecord(item: BranchKeyItem): BranchKeyRecord {
103102
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#record-format
104103
//# 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)
@@ -192,6 +191,9 @@ export function validateBranchKeyRecord(item: BranchKeyItem): BranchKeyRecord {
192191
* @returns authenticated encryption context
193192
*/
194193
export function constructAuthenticatedEncryptionContext(
194+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#logical-keystore-name
195+
//# It is not stored on the items in the so it MUST be added
196+
//# to items retrieved from the table.
195197
{ logicalKeyStoreName }: { logicalKeyStoreName: string },
196198
branchKeyRecord: BranchKeyRecord
197199
): BranchKeyEncryptionContext {

‎modules/branch-keystore-node/src/dynamodb_key_storage.ts

Lines changed: 100 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
11
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
22
// SPDX-License-Identifier: Apache-2.0
33

4-
import { IBranchKeyStorage, EncryptedHierarchicalKey } from './types'
4+
import {
5+
IBranchKeyStorage,
6+
EncryptedHierarchicalKey,
7+
ActiveHierarchicalSymmetricVersion,
8+
HierarchicalSymmetricVersion,
9+
} from './types'
510
import { DynamoDBClient } from '@aws-sdk/client-dynamodb'
611
import {
712
getBranchKeyItem,
@@ -32,6 +37,9 @@ export interface DynamoDBKeyStorageInput {
3237
ddbClient: DynamoDBClient
3338
}
3439

40+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#operations
41+
//= type=implication
42+
//# The Dynamodb Key Storage Interface MUST implement the [key storage interface](./key-storage.md#interface).
3543
export class DynamoDBKeyStorage implements IBranchKeyStorage {
3644
public declare readonly ddbTableName: string
3745
public declare readonly logicalKeyStoreName: string
@@ -70,52 +78,140 @@ export class DynamoDBKeyStorage implements IBranchKeyStorage {
7078
public async getEncryptedActiveBranchKey(
7179
branchKeyId: string
7280
): Promise<EncryptedHierarchicalKey> {
81+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedactivebranchkey
82+
//# To get the active version for the branch key id from the keystore
83+
//# this operation MUST call AWS DDB `GetItem`
84+
//# using the `branch-key-id` as the Partition Key and `"branch:ACTIVE"` value as the Sort Key.
85+
7386
// get the ddb response item using the partition & sort keys
7487
const ddbBranchKeyItem = await getBranchKeyItem(
7588
this,
7689
branchKeyId,
7790
BRANCH_KEY_ACTIVE_TYPE
7891
)
7992
// validate and form the branch key record
93+
94+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedactivebranchkey
95+
//# If the record does not contain the defined fields, this operation MUST fail.
96+
97+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedactivebranchkey
98+
//# The AWS DDB response MUST contain the fields defined in the [branch keystore record format](#record-format).
8099
const ddbBranchKeyRecord = validateBranchKeyRecord(ddbBranchKeyItem)
81100
// construct an encryption context from the record
82101
const authenticatedEncryptionContext =
83102
constructAuthenticatedEncryptionContext(this, ddbBranchKeyRecord)
84103

85-
return new EncryptedHierarchicalKey(
104+
const encrypted = new EncryptedHierarchicalKey(
86105
authenticatedEncryptionContext,
87106
ddbBranchKeyRecord[BRANCH_KEY_FIELD]
88107
)
108+
109+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedactivebranchkey
110+
//# The returned EncryptedHierarchicalKey MUST have the same identifier as the input.
111+
needs(encrypted.branchKeyId == branchKeyId, 'Unexpected branch key id.')
112+
113+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedactivebranchkey
114+
//# The returned EncryptedHierarchicalKey MUST have a type of ActiveHierarchicalSymmetricVersion.
115+
needs(
116+
encrypted.type instanceof ActiveHierarchicalSymmetricVersion,
117+
'Unexpected type. Not an active record.'
118+
)
119+
120+
return encrypted
89121
}
90122

91123
public async getEncryptedBranchKeyVersion(
92124
branchKeyId: string,
93125
branchKeyVersion: string
94126
): Promise<EncryptedHierarchicalKey> {
127+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedbranchkeyversion
128+
//# To get a branch key from the keystore this operation MUST call AWS DDB `GetItem`
129+
//# using the `branch-key-id` as the Partition Key and "branch:version:" + `branchKeyVersion` value as the Sort Key.
130+
95131
// get the ddb response item using the partition & sort keys
96132
const ddbBranchKeyItem = await getBranchKeyItem(
97133
this,
98134
branchKeyId,
99135
BRANCH_KEY_TYPE_PREFIX + branchKeyVersion
100136
)
137+
138+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedbranchkeyversion
139+
//# If the record does not contain the defined fields, this operation MUST fail.
140+
141+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedbranchkeyversion
142+
//# The AWS DDB response MUST contain the fields defined in the [branch keystore record format](#record-format).
143+
101144
// validate and form the branch key record
102145
const ddbBranchKeyRecord = validateBranchKeyRecord(ddbBranchKeyItem)
103146
// construct an encryption context from the record
104147
const authenticatedEncryptionContext =
105148
constructAuthenticatedEncryptionContext(this, ddbBranchKeyRecord)
106149

107-
return new EncryptedHierarchicalKey(
150+
const encrypted = new EncryptedHierarchicalKey(
108151
authenticatedEncryptionContext,
109152
ddbBranchKeyRecord[BRANCH_KEY_FIELD]
110153
)
154+
155+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedbranchkeyversion
156+
//# The returned EncryptedHierarchicalKey MUST have the same identifier as the input.
157+
needs(encrypted.branchKeyId == branchKeyId, 'Unexpected branch key id.')
158+
159+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedbranchkeyversion
160+
//# The returned EncryptedHierarchicalKey MUST have the same version as the input.
161+
needs(
162+
encrypted.type.version == branchKeyVersion,
163+
'Unexpected branch key version.'
164+
)
165+
166+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedbranchkeyversion
167+
//# The returned EncryptedHierarchicalKey MUST have a type of HierarchicalSymmetricVersion.
168+
needs(
169+
encrypted.type instanceof HierarchicalSymmetricVersion,
170+
'Unexpected type. Not an version record.'
171+
)
172+
173+
return encrypted
111174
}
112175

113176
getKeyStorageInfo() {
114177
return {
115178
name: this.ddbTableName,
116-
logicalName: this.logicalKeyStoreName
179+
logicalName: this.logicalKeyStoreName,
117180
}
118181
}
119182
}
120183

121184
immutableClass(DynamoDBKeyStorage)
185+
186+
// This is a limited release for JS only.
187+
// The full Key Store operations are available
188+
// in the AWS Cryptographic Material Providers library
189+
// in various languages (Java, .Net, Python, Rust...)
190+
191+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#writenewencryptedbranchkey
192+
//= type=exception
193+
//# To add the branch keys and a beacon key to the keystore the
194+
//# operation MUST call [Amazon DynamoDB API TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html).
195+
//# The call to Amazon DynamoDB TransactWriteItems MUST use the configured Amazon DynamoDB Client to make the call.
196+
//# The operation MUST call Amazon DynamoDB TransactWriteItems with a request constructed as follows:
197+
198+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#writenewencryptedbranchkey
199+
//= type=exception
200+
//# If DDB TransactWriteItems is successful, this operation MUST return a successful response containing no additional data.
201+
//# Otherwise, this operation MUST yield an error.
202+
203+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#writenewencryptedbranchkeyversion
204+
//= type=exception
205+
//# To add the new branch key to the keystore,
206+
//# the operation MUST call [Amazon DynamoDB API TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html).
207+
//# The call to Amazon DynamoDB TransactWriteItems MUST use the configured Amazon DynamoDB Client to make the call.
208+
//# The operation MUST call Amazon DynamoDB TransactWriteItems with a request constructed as follows:
209+
210+
//= aws-encryption-sdk-specification/framework/key-store/dynamodb-key-storage.md#getencryptedbeaconkey
211+
//= type=exception
212+
//# To get a branch key from the keystore this operation MUST call AWS DDB `GetItem`
213+
//# using the `branch-key-id` as the Partition Key and "beacon:ACTIVE" value as the Sort Key.
214+
//# The AWS DDB response MUST contain the fields defined in the [branch keystore record format](#record-format).
215+
//# The returned EncryptedHierarchicalKey MUST have the same identifier as the input.
216+
//# The returned EncryptedHierarchicalKey MUST have a type of ActiveHierarchicalSymmetricBeacon.
217+
//# If the record does not contain the defined fields, this operation MUST fail.

‎modules/branch-keystore-node/src/types.ts

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,9 @@ export interface IBranchKeyStorage {
186186
//= type=implication
187187
//# - [GetKeyStorageInfo](#getkeystorageinfo)
188188

189+
//= aws-encryption-sdk-specification/framework/key-store/key-storage.md#getkeystorageinfo
190+
//= type=implication
191+
//# It MUST return the physical table name.
189192
getKeyStorageInfo(): { name: string, logicalName: string }
190193
}
191194

@@ -253,4 +256,17 @@ export interface BranchKeyStoreNodeInput {
253256

254257
//= aws-encryption-sdk-specification/framework/key-store/key-storage.md#interface
255258
//= type=exception
256-
//# - [GetEncryptedBeaconKey](#getencryptedbeaconkey)
259+
//# - [GetEncryptedBeaconKey](#getencryptedbeaconkey)
260+
261+
//= aws-encryption-sdk-specification/framework/key-store/key-storage.md#writenewencryptedbranchkey
262+
//= type=exception
263+
//# The WriteNewEncryptedBranchKey caller MUST provide:
264+
265+
//= aws-encryption-sdk-specification/framework/key-store/key-storage.md#writenewencryptedbranchkeyversion
266+
//= type=exception
267+
//# The WriteNewEncryptedBranchKeyVersion caller MUST provide:
268+
269+
//= aws-encryption-sdk-specification/framework/key-store/key-storage.md#getencryptedbeaconkey
270+
//= type=exception
271+
//# The GetEncryptedBeaconKey caller MUST provide the same inputs as the [GetBeaconKey](../branch-key-store.md#getbeaconkey) operation.
272+
//# It MUST return an [EncryptedHierarchicalKey](#encryptedhierarchicalkey).

0 commit comments

Comments
 (0)