comment the demo code

Author: nvobilis

modules/example-node/hkr-demo/hkr.ts

@@ -1,3 +1,6 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
 import {
   buildClient,
   CommitmentPolicy,
@@ -19,12 +22,14 @@ const YELLO_LOG = '\x1b[33m%s\x1b[0m'
 const GREEN_LOG = '\x1b[32m%s\x1b[0m'
 const RED_LOG = '\x1b[31m%s\x1b[0m'
 
+// function to generate a random string
 export function generateRandomString(minLength: number, maxLength: number) {
   const randomLength =
     Math.floor(Math.random() * (maxLength - minLength + 1)) + minLength
   return randomBytes(randomLength).toString('hex').slice(0, randomLength)
 }
 
+// function to encrypt, decrypt, and verify
 export async function roundtrip(
   keyring: KeyringNode,
   context: EncryptionContext,
@@ -47,10 +52,12 @@ export async function roundtrip(
   return { plaintext, result, cleartext, messageHeader }
 }
 
+// run the roundtrips on the specified keyring
 export async function runRoundTrips(
   keyring: KeyringNode,
   numRoundTrips: number
 ) {
+  // set up spies to monitor network call volume
   const kmsSpy = sinon.spy(KMSClient.prototype, 'send')
   const ddbSpy = sinon.spy(DynamoDBClient.prototype, 'send')
   const padding = String(numRoundTrips).length
@@ -60,15 +67,19 @@ export async function runRoundTrips(
   console.log(YELLO_LOG, `${keyring.constructor.name} Roundtrips`) // Print constructor name in yellow
   console.time('Total runtime') // Start the timer
 
+  // for each roundtrip
   for (let i = 0; i < numRoundTrips; i++) {
+    // create an encryption context
     const encryptionContext = {
       roundtrip: i.toString(),
     }
+    // generate a random string
     const encryptionInput = generateRandomString(
       MIN_INPUT_LENGTH,
       MAX_INPUT_LENGTH
     )
 
+    // try to do the roundtrip. If any error arises, log it properly
     let decryptionOutput: string
     try {
       const { plaintext } = await roundtrip(
@@ -88,21 +99,24 @@ export async function runRoundTrips(
       MAX_INPUT_LENGTH - decryptionOutput.length
     )
 
+    // log message
     const logMessage = `Roundtrip ${String(i + 1).padStart(
       padding,
       ' '
     )}: ${encryptionInput}${encryptionInputPadding} ----encrypt & decrypt----> ${decryptionOutput}${decryptionOutputPadding}`
 
+    // print the log green if successful. Otherwise, red
     let logColor: string
     if (encryptionInput === decryptionOutput) {
       logColor = GREEN_LOG
       successes += 1
     } else {
       logColor = RED_LOG
     }
-    console.log(logColor, logMessage) // Print log message in green
+    console.log(logColor, logMessage)
   }
 
+  // print metrics for runtime and call volume
   console.log()
   console.log(YELLO_LOG, `${keyring.constructor.name} metrics`) // Print constructor name in yellow
   console.timeEnd('Total runtime')

modules/example-node/hkr-demo/hkr_vs_regular.demo.ts

@@ -1,4 +1,6 @@
-// import chalk from 'chalk'
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
 import {
   BranchKeyStoreNode,
   SrkCompatibilityKmsConfig,
@@ -8,9 +10,11 @@ import {
 import { runRoundTrips } from './hkr'
 import minimist from 'minimist'
 
+// get cli args
 const args = minimist(process.argv.slice(2))
 const NUM_ROUNDTRIPS = args.numRoundTrips || 10
 
+// function to run the KMS keyring roundtrips
 async function runKmsKeyring() {
   const generatorKeyId =
     'arn:aws:kms:us-west-2:658956600833:key/b3537ef1-d8dc-4780-9f5a-55776cbb2f7f'
@@ -19,6 +23,7 @@ async function runKmsKeyring() {
   await runRoundTrips(keyring, NUM_ROUNDTRIPS)
 }
 
+// function to run the H-keyring roundtrips
 async function runKmsHkrKeyring() {
   const branchKeyArn =
     'arn:aws:kms:us-west-2:370957321024:key/9d989aa2-2f9c-438c-a745-cc57d3ad0126'

modules/example-node/hkr-demo/interop.demo.ts

@@ -1,3 +1,6 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
 import * as fs from 'fs'
 import {
   BranchKeyStoreNode,
@@ -12,6 +15,7 @@ const { encrypt, decrypt } = buildClient(
   CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
 )
 
+// create H-Keyring
 const branchKeyArn =
   'arn:aws:kms:us-west-2:370957321024:key/9d989aa2-2f9c-438c-a745-cc57d3ad0126'
 const branchKeyId = '38853b56-19c6-4345-9cb5-afc2a25dcdd1'
@@ -28,6 +32,7 @@ const keyring = new KmsHierarchicalKeyRingNode({
   cacheLimitTtl: 60,
 })
 
+// function to decrypt with H-Keyring
 async function decryptEncryptedData(encryptedData: Buffer) {
   const { plaintext: decryptedData, messageHeader } = await decrypt(
     keyring,
@@ -45,6 +50,7 @@ async function decryptEncryptedData(encryptedData: Buffer) {
   return decryptedData
 }
 
+// function to encrypt with H-Keyring
 async function encryptData(data: Buffer) {
   const { result } = await encrypt(keyring, data, {
     encryptionContext: { successful: 'demo' },
@@ -54,11 +60,13 @@ async function encryptData(data: Buffer) {
 }
 
 async function main() {
+  // read CLI args
   const args = process.argv.slice(2)
   const operation = args[0]
   const inFile = args[1]
   const outFile = args[2]
 
+  // read from input file
   let inData = Buffer.alloc(0)
   try {
     inData = fs.readFileSync(inFile)
@@ -67,6 +75,7 @@ async function main() {
     exit(1)
   }
 
+  // encrypt/decrypt input file
   let outData: Buffer
   let msg: string
   if (operation === 'encrypt') {
@@ -79,13 +88,15 @@ async function main() {
     msg = 'JS has completed decryption'
   }
 
+  // write to output file
   try {
     fs.writeFileSync(outFile, outData)
   } catch (err) {
     console.error(err)
     exit(1)
   }
 
+  // log completion message
   console.log(msg)
 }
 

modules/example-node/hkr-demo/multi_tenant.demo.ts

@@ -1,3 +1,6 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
 import {
   KmsHierarchicalKeyRingNode,
   BranchKeyStoreNode,
@@ -12,13 +15,16 @@ import minimist from 'minimist'
 import * as fs from 'fs'
 import { exit } from 'process'
 
+// read CLI args
 const args = minimist(process.argv.slice(2))
 
+// map A and B to respective branch IDs
 const tenantMap: { [key: string]: string } = {
   A: '38853b56-19c6-4345-9cb5-afc2a25dcdd1',
   B: '2c583585-5770-467d-8f59-b346d0ed1994',
 }
 
+// preprocess CLI args and return them under an object with named fields
 function getCliArgs() {
   const operation = args.operation
   if (!operation) {
@@ -45,12 +51,15 @@ function getCliArgs() {
   return { operation, inFile, outFile, tenant }
 }
 
+// a dummy branch key id supplier which looks for a field with key "branchKeyId"
+// inside the EC
 class ExampleBranchKeyIdSupplier implements BranchKeyIdSupplier {
   getBranchKeyId(encryptionContext: EncryptionContext): string {
     return encryptionContext.branchKeyId
   }
 }
 
+// configure the keystore
 const branchKeyArn =
   'arn:aws:kms:us-west-2:370957321024:key/9d989aa2-2f9c-438c-a745-cc57d3ad0126'
 
@@ -60,6 +69,7 @@ const keyStore = new BranchKeyStoreNode({
   kmsConfiguration: new SrkCompatibilityKmsConfig(branchKeyArn),
 })
 
+// function to read input from a file
 function readInputData(inFile: string) {
   let inData = Buffer.alloc(0)
   try {
@@ -72,6 +82,7 @@ function readInputData(inFile: string) {
   return inData
 }
 
+// a function to write output to a file
 function dumpOutputData(outFile: string, outData: Buffer) {
   try {
     fs.writeFileSync(outFile, outData)
@@ -85,6 +96,7 @@ const { encrypt, decrypt } = buildClient(
   CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
 )
 
+// function to decrypt with the H-keyring
 async function decryptEncryptedData(
   encryptedData: Buffer,
   keyring: KeyringNode
@@ -105,6 +117,7 @@ async function decryptEncryptedData(
   return decryptedData
 }
 
+// function to encrypt with the H-Keyring
 async function encryptData(
   data: Buffer,
   keyring: KeyringNode,
@@ -115,13 +128,18 @@ async function encryptData(
 }
 
 async function main() {
+  // read cli args
   const { operation, inFile, outFile, tenant } = getCliArgs()
+  // based on CLI tenant arg, find the branch key id
   const branchKeyId: string = tenantMap[tenant]
+  // read input from input file
   const inData = readInputData(inFile)
 
   let outData: Buffer = Buffer.alloc(0)
   let msg: string
+  // if cli arg operation field is encrypt
   if (operation === 'encrypt') {
+    // create a dynamic keyring and encrypt
     const keyring = new KmsHierarchicalKeyRingNode({
       branchKeyIdSupplier: new ExampleBranchKeyIdSupplier(),
       keyStore,
@@ -131,6 +149,7 @@ async function main() {
     outData = await encryptData(data, keyring, { branchKeyId })
     msg = `Tenant ${tenant} has completed encryption`
   } else {
+    // otherwise, create a static keyring and decrypt
     const keyring = new KmsHierarchicalKeyRingNode({
       branchKeyId,
       keyStore,
@@ -147,6 +166,7 @@ async function main() {
     msg = `Tenant ${tenant} has completed decryption`
   }
 
+  // write output to output file
   dumpOutputData(outFile, outData)
   console.log(msg)
 }