feat(cryptographic-materials-cache): add support for branch key materials (#596)

* support branch key materials

support branch key materials

reinstall uuidv4

* reinstall uuidv4 within specific modules

* install util package

* uninstall uuidv4 package from code that may run in browser runtimes

* generate uuid v4's using uuid package instead of uuidv4

* manually validate uuid v4's

* install uuid package

* remove uuidv4 regex validation

* remove version lowercasing

* add tests for v3 & v5

Author: seebees

modules/cache-material/package.json

@@ -22,7 +22,8 @@
     "@aws-crypto/serialize": "file:../serialize",
     "@types/lru-cache": "^5.1.0",
     "lru-cache": "^6.0.0",
-    "tslib": "^2.2.0"
+    "tslib": "^2.2.0",
+    "util": "^0.12.5"
   },
   "sideEffects": false,
   "main": "./build/main/src/index.js",

modules/cache-material/src/cryptographic_materials_cache.ts

@@ -5,6 +5,7 @@ import {
   EncryptionMaterial,
   DecryptionMaterial,
   SupportedAlgorithmSuites,
+  BranchKeyMaterial,
 } from '@aws-crypto/material-management'
 
 export interface CryptographicMaterialsCache<
@@ -16,16 +17,30 @@ export interface CryptographicMaterialsCache<
     plaintextLength: number,
     maxAge?: number
   ): void
+
   putDecryptionMaterial(
     key: string,
     response: DecryptionMaterial<S>,
     maxAge?: number
   ): void
+
+  // a put operation to support branch key material
+  putBranchKeyMaterial(
+    key: string,
+    response: BranchKeyMaterial,
+    maxAge?: number
+  ): void
+
   getEncryptionMaterial(
     key: string,
     plaintextLength: number
   ): EncryptionMaterialEntry<S> | false
+
   getDecryptionMaterial(key: string): DecryptionMaterialEntry<S> | false
+
+  // a get operation to support branch key material
+  getBranchKeyMaterial(key: string): BranchKeyMaterialEntry | false
+
   del(key: string): void
 }
 
@@ -45,3 +60,7 @@ export interface DecryptionMaterialEntry<S extends SupportedAlgorithmSuites>
   extends Entry<S> {
   readonly response: DecryptionMaterial<S>
 }
+
+export interface BranchKeyMaterialEntry {
+  readonly response: BranchKeyMaterial
+}

modules/cache-material/src/get_local_cryptographic_materials_cache.ts

@@ -9,22 +9,31 @@ import {
   needs,
   isEncryptionMaterial,
   isDecryptionMaterial,
+  BranchKeyMaterial,
+  isBranchKeyMaterial,
 } from '@aws-crypto/material-management'
 
 import {
   CryptographicMaterialsCache,
   Entry,
   EncryptionMaterialEntry,
   DecryptionMaterialEntry,
+  BranchKeyMaterialEntry,
 } from './cryptographic_materials_cache'
 
+// define a broader type for local CMC entries that encompass BranchKeyMaterial
+// entries as well
+type LocalCmcEntry<S extends SupportedAlgorithmSuites> =
+  | BranchKeyMaterialEntry
+  | Entry<S>
+
 export function getLocalCryptographicMaterialsCache<
   S extends SupportedAlgorithmSuites
 >(
   capacity: number,
   proactiveFrequency: number = 1000 * 60
 ): CryptographicMaterialsCache<S> {
-  const cache = new LRU<string, Entry<S>>({
+  const cache = new LRU<string, LocalCmcEntry<S>>({
     max: capacity,
     dispose(_key, value) {
       /* Zero out the unencrypted dataKey, when the material is removed from the cache. */
@@ -82,6 +91,7 @@ export function getLocalCryptographicMaterialsCache<
 
       cache.set(key, entry, maxAge)
     },
+
     putDecryptionMaterial(
       key: string,
       material: DecryptionMaterial<S>,
@@ -100,6 +110,22 @@ export function getLocalCryptographicMaterialsCache<
 
       cache.set(key, entry, maxAge)
     },
+
+    putBranchKeyMaterial(
+      key: string,
+      material: BranchKeyMaterial,
+      maxAge?: number
+    ): void {
+      /* Precondition: Only cache BranchKeyMaterial */
+      needs(isBranchKeyMaterial(material), 'Malformed response.')
+
+      const entry = Object.seal({
+        response: material,
+      })
+
+      cache.set(key, entry, maxAge)
+    },
+
     getEncryptionMaterial(key: string, plaintextLength: number) {
       /* Precondition: plaintextLength can not be negative. */
       needs(plaintextLength >= 0, 'Malformed plaintextLength')
@@ -109,11 +135,13 @@ export function getLocalCryptographicMaterialsCache<
       /* Postcondition: Only return EncryptionMaterial. */
       needs(isEncryptionMaterial(entry.response), 'Malformed response.')
 
-      entry.bytesEncrypted += plaintextLength
-      entry.messagesEncrypted += 1
+      const encryptionMaterialEntry = entry as EncryptionMaterialEntry<S>
+      encryptionMaterialEntry.bytesEncrypted += plaintextLength
+      encryptionMaterialEntry.messagesEncrypted += 1
 
       return entry as EncryptionMaterialEntry<S>
     },
+
     getDecryptionMaterial(key: string) {
       const entry = cache.get(key)
       /* Check for early return (Postcondition): If this key does not have a DecryptionMaterial, return false. */
@@ -123,6 +151,18 @@ export function getLocalCryptographicMaterialsCache<
 
       return entry as DecryptionMaterialEntry<S>
     },
+
+    getBranchKeyMaterial(key: string): BranchKeyMaterialEntry | false {
+      const entry = cache.get(key)
+
+      /* Postcondition: If this key does not have a BranchKeyMaterial, return false */
+      if (!entry) return false
+
+      /* Postcondition: Only return BranchKeyMaterial */
+      needs(isBranchKeyMaterial(entry.response), 'Malformed response.')
+      return entry as BranchKeyMaterialEntry
+    },
+
     del(key: string) {
       cache.del(key)
     },

modules/cache-material/test/get_local_cryptographic_materials_cache.test.ts

@@ -10,23 +10,67 @@ import {
   NodeEncryptionMaterial,
   NodeDecryptionMaterial,
   AlgorithmSuiteIdentifier,
+  NodeBranchKeyMaterial,
 } from '@aws-crypto/material-management'
+import { v4 } from 'uuid'
 
 const nodeSuite = new NodeAlgorithmSuite(
   AlgorithmSuiteIdentifier.ALG_AES128_GCM_IV12_TAG16_HKDF_SHA256
 )
 const encryptionMaterial = new NodeEncryptionMaterial(nodeSuite, {})
 const decryptionMaterial = new NodeDecryptionMaterial(nodeSuite, {})
+const branchKeyMaterial = new NodeBranchKeyMaterial(
+  Buffer.alloc(32),
+  'id',
+  v4(),
+  {}
+)
 
 describe('getLocalCryptographicMaterialsCache', () => {
   const {
     getEncryptionMaterial,
     getDecryptionMaterial,
+    getBranchKeyMaterial,
     del,
     putEncryptionMaterial,
     putDecryptionMaterial,
+    putBranchKeyMaterial,
   } = getLocalCryptographicMaterialsCache(100)
 
+  it('putBranchKeyMaterial', () => {
+    const key = 'some encryption key'
+    const response: any = branchKeyMaterial
+
+    putBranchKeyMaterial(key, response)
+    const test = getBranchKeyMaterial(key)
+    if (!test) throw new Error('never')
+    expect(test.response === response).to.equal(true)
+    expect(Object.isFrozen(test.response)).to.equal(true)
+  })
+
+  it('Precondition: Only cache BranchKeyMaterial', () => {
+    const key = 'some decryption key'
+    const response: any = 'not material'
+
+    expect(() => putBranchKeyMaterial(key, response)).to.throw()
+  })
+
+  it('Postcondition: If this key does not have a BranchKeyMaterial, return false', () => {
+    const test = getBranchKeyMaterial('does-not-exist')
+    expect(test).to.equal(false)
+  })
+
+  it('Postcondition: Only return BranchKeyMaterial', () => {
+    putDecryptionMaterial('key1', decryptionMaterial)
+    putEncryptionMaterial('key2', encryptionMaterial, 1)
+
+    expect(() => getBranchKeyMaterial('key1')).to.throw()
+    expect(() => getBranchKeyMaterial('key2')).to.throw()
+
+    putBranchKeyMaterial('key3', branchKeyMaterial)
+    expect(() => getBranchKeyMaterial('key3'))
+  })
+
   it('putEncryptionMaterial', () => {
     const key = 'some encryption key'
     const response: any = encryptionMaterial
@@ -151,6 +195,52 @@ describe('getLocalCryptographicMaterialsCache', () => {
 })
 
 describe('cache eviction', () => {
+  it('putBranchKeyMaterial can exceed capacity', () => {
+    const { getBranchKeyMaterial, putBranchKeyMaterial } =
+      getLocalCryptographicMaterialsCache(1)
+
+    const key1 = 'key lost'
+    const key2 = 'key replace'
+    const response: any = branchKeyMaterial
+
+    putBranchKeyMaterial(key1, response)
+    putBranchKeyMaterial(key2, response)
+    const lost = getBranchKeyMaterial(key1)
+    const found = getBranchKeyMaterial(key2)
+    expect(lost).to.equal(false)
+    expect(found).to.not.equal(false)
+  })
+
+  it('putBranchKeyMaterial can be deleted', () => {
+    const { getBranchKeyMaterial, putBranchKeyMaterial, del } =
+      getLocalCryptographicMaterialsCache(1)
+
+    const key = 'key deleted'
+    const response: any = branchKeyMaterial
+
+    putBranchKeyMaterial(key, response)
+    del(key)
+    const lost = getBranchKeyMaterial(key)
+    expect(lost).to.equal(false)
+  })
+
+  it('putBranchKeyMaterial can be garbage collected', async () => {
+    const { getBranchKeyMaterial, putBranchKeyMaterial } =
+      // set TTL to 10 ms so that our branch key material entry is evicted between the
+      // put and get operation (which have a 20 ms gap). This will simulate a
+      // case where we try to query our branch key material but it was already
+      // garbage collected
+      getLocalCryptographicMaterialsCache(1, 10)
+
+    const key = 'key lost'
+    const response: any = branchKeyMaterial
+
+    putBranchKeyMaterial(key, response, 1)
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    const lost = getBranchKeyMaterial(key)
+    expect(lost).to.equal(false)
+  })
+
   it('putDecryptionMaterial can exceed capacity', () => {
     const { getDecryptionMaterial, putDecryptionMaterial } =
       getLocalCryptographicMaterialsCache(1)

modules/material-management/package.json

@@ -20,7 +20,8 @@
   "dependencies": {
     "asn1.js": "^5.3.0",
     "bn.js": "^5.1.1",
-    "tslib": "^2.2.0"
+    "tslib": "^2.2.0",
+    "util": "^0.12.5"
   },
   "sideEffects": false,
   "main": "./build/main/src/index.js",

modules/material-management/src/cryptographic_material.ts

@@ -17,6 +17,7 @@ import { KeyringTrace, KeyringTraceFlag } from './keyring_trace'
 import { NodeAlgorithmSuite } from './node_algorithms'
 import { WebCryptoAlgorithmSuite } from './web_crypto_algorithms'
 import { needs } from './needs'
+import { validate, version } from 'uuid'
 
 /* KeyObject were introduced in v11.
  * They protect the data key better than a Buffer.
@@ -115,6 +116,91 @@ export interface CryptographicMaterial<T extends CryptographicMaterial<T>> {
   encryptionContext: Readonly<EncryptionContext>
 }
 
+//= aws-encryption-sdk-specification/framework/structures.md#structure-3
+//# This structure MUST include all of the following fields:
+//#
+//# - [Branch Key](#branch-key)
+//# - [Branch Key Id](#branch-key-id)
+//# - [Branch Key Version](#branch-key-version)
+//# - [Encryption Context](#encryption-context-3)
+// structure is based on https://github.com/aws/aws-cryptographic-material-providers-library/blob/main/AwsCryptographicMaterialProviders/dafny/AwsCryptographyKeyStore/Model/KeyStore.smithy#L323
+export interface BranchKeyMaterial {
+  branchKey(): Readonly<Buffer>
+  branchKeyIdentifier: string
+  branchKeyVersion: Readonly<Buffer>
+  encryptionContext: Readonly<EncryptionContext>
+}
+
+export class NodeBranchKeyMaterial implements BranchKeyMaterial {
+  // all attributes are readonly so they are accessible outside the class but
+  // they cannot be modified
+
+  // since all fields are objects, keep them immutable from external changes via
+  // shared memory
+
+  // we want the branch key to be mutable within the class but immutable outside
+  // the class
+  private _branchKey: Buffer
+  declare readonly branchKeyIdentifier: string
+  declare readonly branchKeyVersion: Readonly<Buffer>
+  declare readonly encryptionContext: Readonly<EncryptionContext>
+
+  constructor(
+    branchKey: Buffer,
+    branchKeyIdentifier: string,
+    branchKeyVersion: string,
+    encryptionContext: EncryptionContext
+  ) {
+    /* Precondition: branchKey must be a 32 byte-long buffer */
+    needs(branchKey.length === 32, 'Branch key must be 32 bytes long')
+
+    /* Precondition: encryptionContext must be an object, even if it is empty */
+    needs(
+      encryptionContext && typeof encryptionContext === 'object',
+      'Encryption context must be set'
+    )
+
+    /* Precondition: branch key ID is required */
+    needs(branchKeyIdentifier, 'Empty branch key ID')
+
+    /* Precondition: branch key version must be valid version 4 uuid */
+    needs(
+      validate(branchKeyVersion) && version(branchKeyVersion) === 4,
+      'Branch key version must be valid version 4 uuid'
+    )
+
+    /* Postcondition: branch key is immutable */
+    this._branchKey = Buffer.from(branchKey)
+
+    /* Postconditon: encryption context is immutable */
+    this.encryptionContext = Object.freeze({ ...encryptionContext })
+
+    this.branchKeyIdentifier = branchKeyIdentifier
+
+    this.branchKeyVersion = Buffer.from(branchKeyVersion, 'utf-8')
+
+    Object.setPrototypeOf(this, NodeBranchKeyMaterial.prototype)
+    /* Postcondition: instance is frozen */
+    // preventing any modifications to its properties or methods.
+    Object.freeze(this)
+  }
+
+  // makes the branch key public to users wrapped in immutable access
+  branchKey(): Readonly<Buffer> {
+    return this._branchKey
+  }
+
+  // this capability is not required of branch key materials according to the
+  // specification. Using this is a good security practice so that the data
+  // key's bytes are not preserved even in free memory
+  zeroUnencryptedDataKey(): BranchKeyMaterial {
+    this._branchKey.fill(0)
+    return this
+  }
+}
+// make the class immutable
+frozenClass(NodeBranchKeyMaterial)
+
 export interface EncryptionMaterial<T extends CryptographicMaterial<T>>
   extends CryptographicMaterial<T> {
   encryptedDataKeys: EncryptedDataKey[]
@@ -372,6 +458,10 @@ export function isDecryptionMaterial(
   )
 }
 
+export function isBranchKeyMaterial(obj: any): obj is NodeBranchKeyMaterial {
+  return obj instanceof NodeBranchKeyMaterial
+}
+
 export function decorateCryptographicMaterial<
   T extends CryptographicMaterial<T>
 >(material: T, setFlag: KeyringTraceFlag) {