feat: Support AWS SDK v3

To support AWS SDK v3,
there needs to be a single interface
between AWS SDK v2 and v3
for the AWS KMS Client.
The `AwsEsdkKMSInterface` is a close copy
that needs to be shared between `kms-keyring`,
`kms-keyring-node, and `kms-keyring-browser`.

Adding `@aws-sdk/client-kms` as a devDependencies
tests have been added for v2 and v3
for every AWS KMS keyring.

Two additional changes were required.

First, getting the `region` value
from an AWS SDK v3 client is an `async` function,
rather than a string property.
This means that the `AwsKmsMrkAwareSymmetricDiscoveryKeyring`
needs to be able to handle this.
The constructor, a syncronus function
needs to store enugh state
that the _OnDecrypt function
can await the setting of the region value.

Second in setting this value `readOnlyProperty`
was updated to explictly set `writable: false`.
This allows this helper to update a property
and set this updated value to read only.

Author: seebees

modules/kms-keyring-browser/src/kms_keyring_browser.ts

@@ -10,6 +10,7 @@ import {
   limitRegions,
   excludeRegions,
   cacheClients,
+  AwsEsdkKMSInterface,
 } from '@aws-crypto/kms-keyring'
 import {
   WebCryptoAlgorithmSuite,
@@ -29,16 +30,16 @@ const getKmsClient = getClient(KMS, {
 })
 const cacheKmsClients = cacheClients(getKmsClient)
 
-export type KmsKeyringWebCryptoInput = Partial<KmsKeyringInput<KMS>>
+export type KmsKeyringWebCryptoInput = Partial<KmsKeyringInput<AwsEsdkKMSInterface>>
 export type KMSWebCryptoConstructible = KMSConstructible<
   KMS,
   KMS.ClientConfiguration
 >
-export type KmsWebCryptoClientSupplier = KmsClientSupplier<KMS>
+export type KmsWebCryptoClientSupplier = KmsClientSupplier<AwsEsdkKMSInterface>
 
 export class KmsKeyringBrowser extends KmsKeyringClass<
   WebCryptoAlgorithmSuite,
-  KMS
+  AwsEsdkKMSInterface
 >(KeyringWebCrypto as Newable<KeyringWebCrypto>) {
   constructor({
     clientProvider = cacheKmsClients,

modules/kms-keyring-browser/src/kms_mrk_discovery_keyring_browser.ts

@@ -4,6 +4,7 @@
 import {
   AwsKmsMrkAwareSymmetricDiscoveryKeyringClass,
   AwsKmsMrkAwareSymmetricDiscoveryKeyringInput,
+  AwsEsdkKMSInterface,
 } from '@aws-crypto/kms-keyring'
 import {
   WebCryptoAlgorithmSuite,
@@ -16,16 +17,15 @@ import {
   KeyringWebCrypto,
   Newable,
 } from '@aws-crypto/material-management-browser'
-import { KMS } from 'aws-sdk'
 
 export type AwsKmsMrkAwareSymmetricDiscoveryKeyringWebCryptoInput =
-  AwsKmsMrkAwareSymmetricDiscoveryKeyringInput<KMS>
+  AwsKmsMrkAwareSymmetricDiscoveryKeyringInput<AwsEsdkKMSInterface>
 
 export class AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser extends AwsKmsMrkAwareSymmetricDiscoveryKeyringClass<
   WebCryptoAlgorithmSuite,
-  KMS
+  AwsEsdkKMSInterface
 >(KeyringWebCrypto as Newable<KeyringWebCrypto>) {
-  declare client: KMS
+  declare client: AwsEsdkKMSInterface
 
   constructor({
     client,

modules/kms-keyring-browser/src/kms_mrk_discovery_multi_keyring_browser.ts

@@ -1,17 +1,16 @@
 // Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { getAwsKmsMrkAwareDiscoveryMultiKeyringBuilder } from '@aws-crypto/kms-keyring'
+import { getAwsKmsMrkAwareDiscoveryMultiKeyringBuilder, AwsEsdkKMSInterface } from '@aws-crypto/kms-keyring'
 import {
   MultiKeyringWebCrypto,
   WebCryptoAlgorithmSuite,
 } from '@aws-crypto/material-management-browser'
 import { getKmsClient } from '.'
 import { AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser } from './kms_mrk_discovery_keyring_browser'
-import { KMS } from 'aws-sdk'
 
 export const buildAwsKmsMrkAwareDiscoveryMultiKeyringBrowser =
-  getAwsKmsMrkAwareDiscoveryMultiKeyringBuilder<WebCryptoAlgorithmSuite, KMS>(
+  getAwsKmsMrkAwareDiscoveryMultiKeyringBuilder<WebCryptoAlgorithmSuite, AwsEsdkKMSInterface>(
     AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser,
     MultiKeyringWebCrypto,
     getKmsClient

modules/kms-keyring-browser/src/kms_mrk_keyring_browser.ts

@@ -4,6 +4,7 @@
 import {
   AwsKmsMrkAwareSymmetricKeyringClass,
   AwsKmsMrkAwareSymmetricKeyringInput,
+  AwsEsdkKMSInterface,
 } from '@aws-crypto/kms-keyring'
 import {
   WebCryptoAlgorithmSuite,
@@ -16,16 +17,15 @@ import {
   KeyringWebCrypto,
   Newable,
 } from '@aws-crypto/material-management-browser'
-import { KMS } from 'aws-sdk'
 
 export type AwsKmsMrkAwareSymmetricKeyringWebCryptoInput =
-  AwsKmsMrkAwareSymmetricKeyringInput<KMS>
+  AwsKmsMrkAwareSymmetricKeyringInput<AwsEsdkKMSInterface>
 
 export class AwsKmsMrkAwareSymmetricKeyringBrowser extends AwsKmsMrkAwareSymmetricKeyringClass<
   WebCryptoAlgorithmSuite,
-  KMS
+  AwsEsdkKMSInterface
 >(KeyringWebCrypto as Newable<KeyringWebCrypto>) {
-  declare client: KMS
+  declare client: AwsEsdkKMSInterface
   declare keyId: string
   declare grantTokens?: string[]
 

modules/kms-keyring-browser/src/kms_mrk_strict_multi_keyring_browser.ts

@@ -1,17 +1,16 @@
 // Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { getAwsKmsMrkAwareStrictMultiKeyringBuilder } from '@aws-crypto/kms-keyring'
+import { getAwsKmsMrkAwareStrictMultiKeyringBuilder, AwsEsdkKMSInterface } from '@aws-crypto/kms-keyring'
 import {
   MultiKeyringWebCrypto,
   WebCryptoAlgorithmSuite,
 } from '@aws-crypto/material-management-browser'
 import { getKmsClient } from '.'
 import { AwsKmsMrkAwareSymmetricKeyringBrowser } from './kms_mrk_keyring_browser'
-import { KMS } from 'aws-sdk'
 
 export const buildAwsKmsMrkAwareStrictMultiKeyringBrowser =
-  getAwsKmsMrkAwareStrictMultiKeyringBuilder<WebCryptoAlgorithmSuite, KMS>(
+  getAwsKmsMrkAwareStrictMultiKeyringBuilder<WebCryptoAlgorithmSuite, AwsEsdkKMSInterface>(
     AwsKmsMrkAwareSymmetricKeyringBrowser,
     MultiKeyringWebCrypto,
     getKmsClient

modules/kms-keyring-browser/test/kms_keyring_browser.test.ts

@@ -5,7 +5,9 @@
 
 import * as chai from 'chai'
 import chaiAsPromised from 'chai-as-promised'
-import { KmsKeyringBrowser, getClient, KMS } from '../src/index'
+import { KmsKeyringBrowser, getClient } from '../src/index'
+import { KMS as V2KMS } from 'aws-sdk'
+import { KMS as V3KMS } from '@aws-sdk/client-kms'
 import {
   KeyringWebCrypto,
   WebCryptoEncryptionMaterial,
@@ -28,7 +30,7 @@ describe('KmsKeyringBrowser::constructor', () => {
     const keyArn =
       'arn:aws:kms:us-west-2:658956600833:key/b3537ef1-d8dc-4780-9f5a-55776cbb2f7f'
     const keyIds = [keyArn]
-    const clientProvider = getClient(KMS, { credentials })
+    const clientProvider = getClient(V2KMS, { credentials })
 
     const test = new KmsKeyringBrowser({
       clientProvider,
@@ -49,13 +51,13 @@ describe('KmsKeyringBrowser::constructor', () => {
   })
 })
 
-describe('KmsKeyringBrowser encrypt/decrypt', () => {
+describe('KmsKeyringBrowser can encrypt/decrypt with AWS SDK v2 client', () => {
   const generatorKeyId =
     'arn:aws:kms:us-west-2:658956600833:alias/EncryptDecrypt'
   const keyArn =
     'arn:aws:kms:us-west-2:658956600833:key/b3537ef1-d8dc-4780-9f5a-55776cbb2f7f'
   const keyIds = [keyArn]
-  const clientProvider = getClient(KMS, { credentials })
+  const clientProvider = getClient(V2KMS, { credentials })
   const keyring = new KmsKeyringBrowser({
     clientProvider,
     generatorKeyId,
@@ -88,3 +90,44 @@ describe('KmsKeyringBrowser encrypt/decrypt', () => {
     expect(() => test.getUnencryptedDataKey()).to.throw()
   })
 })
+
+
+describe('KmsKeyringBrowser can encrypt/decrypt with AWS SDK v3 client', () => {
+  const generatorKeyId =
+    'arn:aws:kms:us-west-2:658956600833:alias/EncryptDecrypt'
+  const keyArn =
+    'arn:aws:kms:us-west-2:658956600833:key/b3537ef1-d8dc-4780-9f5a-55776cbb2f7f'
+  const keyIds = [keyArn]
+  const clientProvider = getClient(V3KMS, { credentials })
+  const keyring = new KmsKeyringBrowser({
+    clientProvider,
+    generatorKeyId,
+    keyIds,
+  })
+  let encryptedDataKey: EncryptedDataKey
+
+  it('can encrypt and create unencrypted data key', async () => {
+    const suite = new WebCryptoAlgorithmSuite(
+      AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA256
+    )
+    const material = new WebCryptoEncryptionMaterial(suite, {})
+    const test = await keyring.onEncrypt(material)
+    expect(test.hasValidKey()).to.equal(true)
+    const udk = test.getUnencryptedDataKey()
+    expect(udk).to.have.lengthOf(suite.keyLengthBytes)
+    expect(test.encryptedDataKeys).to.have.lengthOf(2)
+    const [edk] = test.encryptedDataKeys
+    encryptedDataKey = edk
+  })
+
+  it('can decrypt an EncryptedDataKey', async () => {
+    const suite = new WebCryptoAlgorithmSuite(
+      AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA256
+    )
+    const material = new WebCryptoDecryptionMaterial(suite, {})
+    const test = await keyring.onDecrypt(material, [encryptedDataKey])
+    expect(test.hasValidKey()).to.equal(true)
+    // The UnencryptedDataKey should be zeroed, because the cryptoKey has been set
+    expect(() => test.getUnencryptedDataKey()).to.throw()
+  })
+})

modules/kms-keyring-browser/test/kms_mrk_discovery_keyring_browser.test.ts

@@ -16,7 +16,8 @@ import {
   AlgorithmSuiteIdentifier,
   WebCryptoDecryptionMaterial,
 } from '@aws-crypto/material-management-browser'
-import { KMS } from 'aws-sdk'
+import { KMS as V2KMS } from 'aws-sdk'
+import { KMS as V3KMS } from '@aws-sdk/client-kms'
 
 chai.use(chaiAsPromised)
 const { expect } = chai
@@ -56,7 +57,7 @@ describe('AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser::constructor', () => {
 /* Injected from @aws-sdk/karma-credential-loader. */
 declare const credentials: any
 
-describe('AwsKmsMrkAwareSymmetricKeyringBrowser encrypt/decrypt', () => {
+describe('AwsKmsMrkAwareSymmetricKeyringBrowser can encrypt/decrypt with AWS SDK v2 client', () => {
   const discoveryFilter = { accountIDs: ['658956600833'], partition: 'aws' }
 
   const eastKeyId =
@@ -69,7 +70,7 @@ describe('AwsKmsMrkAwareSymmetricKeyringBrowser encrypt/decrypt', () => {
 
   const keyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser({
     // Note the difference in the region from the keyId
-    client: new KMS({ region: 'us-west-2', credentials }),
+    client: new V2KMS({ region: 'us-west-2', credentials }),
     discoveryFilter,
     grantTokens,
   })
@@ -84,7 +85,55 @@ describe('AwsKmsMrkAwareSymmetricKeyringBrowser encrypt/decrypt', () => {
 
   it('can decrypt an EncryptedDataKey', async () => {
     const encryptKeyring = new AwsKmsMrkAwareSymmetricKeyringBrowser({
-      client: new KMS({ region: 'us-east-1', credentials }),
+      client: new V2KMS({ region: 'us-east-1', credentials }),
+      keyId: eastKeyId,
+      grantTokens,
+    })
+    const encryptMaterial = await encryptKeyring.onEncrypt(
+      new WebCryptoEncryptionMaterial(suite, encryptionContext)
+    )
+    const [edk] = encryptMaterial.encryptedDataKeys
+
+    const material = await keyring.onDecrypt(
+      new WebCryptoDecryptionMaterial(suite, encryptionContext),
+      [edk]
+    )
+    const test = await keyring.onDecrypt(material, [edk])
+    expect(test.hasValidKey()).to.equal(true)
+    // The UnencryptedDataKey should be zeroed, because the cryptoKey has been set
+    expect(() => test.getUnencryptedDataKey()).to.throw()
+  })
+})
+
+describe('AwsKmsMrkAwareSymmetricKeyringBrowser can encrypt/decrypt with AWS SDK v3 client', () => {
+  const discoveryFilter = { accountIDs: ['658956600833'], partition: 'aws' }
+
+  const eastKeyId =
+    'arn:aws:kms:us-east-1:658956600833:key/mrk-80bd8ecdcd4342aebd84b7dc9da498a7'
+  const grantTokens = ['grant']
+  const encryptionContext = { some: 'context' }
+  const suite = new WebCryptoAlgorithmSuite(
+    AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA256
+  )
+
+  const keyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser({
+    // Note the difference in the region from the keyId
+    client: new V3KMS({ region: 'us-west-2', credentials }),
+    discoveryFilter,
+    grantTokens,
+  })
+
+  it('throws an error on encrypt', async () => {
+    const material = new WebCryptoEncryptionMaterial(suite, encryptionContext)
+    return expect(keyring.onEncrypt(material)).to.rejectedWith(
+      Error,
+      'AwsKmsMrkAwareSymmetricDiscoveryKeyring cannot be used to encrypt'
+    )
+  })
+
+  it('can decrypt an EncryptedDataKey', async () => {
+    const encryptKeyring = new AwsKmsMrkAwareSymmetricKeyringBrowser({
+      client: new V3KMS({ region: 'us-east-1', credentials }),
       keyId: eastKeyId,
       grantTokens,
     })

modules/kms-keyring-browser/test/kms_mrk_keyring_browser.test.ts

@@ -15,7 +15,8 @@ import {
   WebCryptoDecryptionMaterial,
   KeyringTraceFlag,
 } from '@aws-crypto/material-management-browser'
-import { KMS } from 'aws-sdk'
+import { KMS as V2KMS } from 'aws-sdk'
+import { KMS as V3KMS } from '@aws-sdk/client-kms'
 
 chai.use(chaiAsPromised)
 const { expect } = chai
@@ -50,7 +51,7 @@ describe('AwsKmsMrkAwareSymmetricKeyringBrowser::constructor', () => {
 /* Injected from @aws-sdk/karma-credential-loader. */
 declare const credentials: any
 
-describe('AwsKmsMrkAwareSymmetricKeyringBrowser encrypt/decrypt', () => {
+describe('AwsKmsMrkAwareSymmetricKeyringBrowser can encrypt/decrypt with AWS SDK v2 client', () => {
   const westKeyId =
     'arn:aws:kms:us-west-2:658956600833:key/mrk-80bd8ecdcd4342aebd84b7dc9da498a7'
   const eastKeyId =
@@ -62,12 +63,12 @@ describe('AwsKmsMrkAwareSymmetricKeyringBrowser encrypt/decrypt', () => {
   )
 
   const encryptKeyring = new AwsKmsMrkAwareSymmetricKeyringBrowser({
-    client: new KMS({ region: 'us-west-2', credentials }),
+    client: new V2KMS({ region: 'us-west-2', credentials }),
     keyId: westKeyId,
     grantTokens,
   })
   const decryptKeyring = new AwsKmsMrkAwareSymmetricKeyringBrowser({
-    client: new KMS({ region: 'us-east-1', credentials }),
+    client: new V2KMS({ region: 'us-east-1', credentials }),
     keyId: eastKeyId,
     grantTokens,
   })
@@ -112,3 +113,66 @@ describe('AwsKmsMrkAwareSymmetricKeyringBrowser encrypt/decrypt', () => {
     expect(() => test.getUnencryptedDataKey()).to.throw()
   })
 })
+
+describe('AwsKmsMrkAwareSymmetricKeyringBrowser can encrypt/decrypt with AWS SDK v3 client', () => {
+  const westKeyId =
+    'arn:aws:kms:us-west-2:658956600833:key/mrk-80bd8ecdcd4342aebd84b7dc9da498a7'
+  const eastKeyId =
+    'arn:aws:kms:us-east-1:658956600833:key/mrk-80bd8ecdcd4342aebd84b7dc9da498a7'
+  const grantTokens = ['grant']
+  const encryptionContext = { some: 'context' }
+  const suite = new WebCryptoAlgorithmSuite(
+    AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA256
+  )
+
+  const encryptKeyring = new AwsKmsMrkAwareSymmetricKeyringBrowser({
+    client: new V3KMS({ region: 'us-west-2', credentials }),
+    keyId: westKeyId,
+    grantTokens,
+  })
+  const decryptKeyring = new AwsKmsMrkAwareSymmetricKeyringBrowser({
+    client: new V3KMS({ region: 'us-east-1', credentials }),
+    keyId: eastKeyId,
+    grantTokens,
+  })
+  let encryptedDataKey: EncryptedDataKey
+
+  it('can encrypt and create unencrypted data key', async () => {
+    const material = new WebCryptoEncryptionMaterial(suite, encryptionContext)
+    const test = await encryptKeyring.onEncrypt(material)
+    expect(test.hasValidKey()).to.equal(true)
+    const udk = test.getUnencryptedDataKey()
+    expect(udk).to.have.lengthOf(suite.keyLengthBytes)
+    expect(test.encryptedDataKeys).to.have.lengthOf(1)
+    const [edk] = test.encryptedDataKeys
+    encryptedDataKey = edk
+  })
+
+  it('can encrypt a pre-existing plaintext data key', async () => {
+    const seedMaterial = new WebCryptoEncryptionMaterial(
+      suite,
+      encryptionContext
+    ).setUnencryptedDataKey(new Uint8Array(suite.keyLengthBytes), {
+      keyName: 'keyName',
+      keyNamespace: 'keyNamespace',
+      flags: KeyringTraceFlag.WRAPPING_KEY_GENERATED_DATA_KEY,
+    })
+    const encryptTest = await encryptKeyring.onEncrypt(seedMaterial)
+    expect(encryptTest.hasValidKey()).to.equal(true)
+    expect(encryptTest.encryptedDataKeys).to.have.lengthOf(1)
+    const [kmsEDK] = encryptTest.encryptedDataKeys
+    expect(kmsEDK.providerId).to.equal('aws-kms')
+    expect(kmsEDK.providerInfo).to.equal(westKeyId)
+  })
+
+  it('can decrypt an EncryptedDataKey', async () => {
+    const suite = new WebCryptoAlgorithmSuite(
+      AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA256
+    )
+    const material = new WebCryptoDecryptionMaterial(suite, encryptionContext)
+    const test = await decryptKeyring.onDecrypt(material, [encryptedDataKey])
+    expect(test.hasValidKey()).to.equal(true)
+    // The UnencryptedDataKey should be zeroed, because the cryptoKey has been set
+    expect(() => test.getUnencryptedDataKey()).to.throw()
+  })
+})