feat(kms-keyring-node): add AWS KMS Hierarchical keyring (#632)

* hkr

* remove timeouts

* fix test timeout issues

* add an additional verification check

* set up mocking

* document mock mechanism

* hkr

* remove timeouts

* fix test timeout issues

* add an additional verification check

* set up mocking

* document mock mechanism

* added runtime type checks to constructor

* try fixing dep errors

* fixes

* add notice

* renaming and modified preconditions

Number attributes like TTL and max cache size can only be stored with precision if they are under JavaScript's Number.MAX_SAFE_INTEGER.

In the MPL, TTL can be a non-negative signed 64-bit integer. However, JavaScript numbers cannot safely store integers beyond Number.MAX_SAFE_INTEGER. Thus, we will cap TTL in seconds such that TTL in ms is <= Number.MAX_SAFE_INTEGER. TTL could be a JS BigInt type but this would require casting back to a number in order to configure the CMC (which only deals with number types not BigInt), which leads to a lossy conversion. This same reasoning is applied to max cache size. Preconditions and tests for these preconditions are updated.

* change in wrapping AAD logic

* Update modules/kms-keyring-node/src/constants.ts

add comment about encrypted key length in the ciphertext

Co-authored-by: Rishav karanjit <karanjitrishav4@gmail.com>

* update constants

change name of the kdf digest algorithm constant to specify sha256. Increases readability

* update constants

change provider id constant name to specify hierarchy

---------

Co-authored-by: Rishav karanjit <karanjitrishav4@gmail.com>

Author: seebees

modules/kms-keyring-node/package.json

@@ -19,9 +19,15 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
+    "@aws-crypto/branch-keystore-node": "file:../branch-keystore-node",
+    "@aws-crypto/cache-material": "file:../cache-material",
+    "@aws-crypto/kdf-ctr-mode-node": "file:../kdf-ctr-mode-node",
     "@aws-crypto/kms-keyring": "file:../kms-keyring",
     "@aws-crypto/material-management-node": "file:../material-management-node",
+    "@aws-crypto/serialize": "file:../serialize",
+    "@aws-sdk/client-dynamodb": "^3.621.0",
     "@aws-sdk/client-kms": "^3.362.0",
+    "sinon": "^18.0.0",
     "tslib": "^2.2.0"
   },
   "sideEffects": false,

modules/kms-keyring-node/src/constants.ts

@@ -0,0 +1,29 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { KeyringTraceFlag } from '@aws-crypto/material-management'
+
+export const ACTIVE_AS_BYTES = Buffer.from('ACTIVE', 'utf-8')
+export const CACHE_ENTRY_ID_DIGEST_ALGORITHM = 'sha512'
+export const KDF_DIGEST_ALGORITHM_SHA_256 = 'sha256'
+export const ENCRYPT_FLAGS =
+  KeyringTraceFlag.WRAPPING_KEY_ENCRYPTED_DATA_KEY |
+  KeyringTraceFlag.WRAPPING_KEY_SIGNED_ENC_CTX
+export const DECRYPT_FLAGS =
+  KeyringTraceFlag.WRAPPING_KEY_DECRYPTED_DATA_KEY |
+  KeyringTraceFlag.WRAPPING_KEY_VERIFIED_ENC_CTX
+export const PROVIDER_ID_HIERARCHY = 'aws-kms-hierarchy'
+export const PROVIDER_ID_HIERARCHY_AS_BYTES = Buffer.from(
+  PROVIDER_ID_HIERARCHY,
+  'utf-8'
+)
+export const DERIVED_BRANCH_KEY_LENGTH = 32
+export const CACHE_ENTRY_ID_LENGTH = 32
+export const KEY_DERIVATION_LABEL = Buffer.from(PROVIDER_ID_HIERARCHY, 'utf-8')
+export const CIPHERTEXT_STRUCTURE = {
+  saltLength: 16,
+  ivLength: 12,
+  branchKeyVersionCompressedLength: 16,
+  // Encrypted Key is of variable length
+  authTagLength: 16,
+}

modules/kms-keyring-node/src/index.ts

@@ -6,3 +6,4 @@ export * from './kms_mrk_keyring_node'
 export * from './kms_mrk_discovery_keyring_node'
 export * from './kms_mrk_strict_multi_keyring_node'
 export * from './kms_mrk_discovery_multi_keyring_node'
+export * from './kms_hkeyring_node'