in modules/example-browser/src/multi_keyring.ts [46:198]
export async function testMultiKeyringExample() {
/* A KMS CMK is required to generate the data key.
* You need kms:GenerateDataKey permission on the CMK in generatorKeyId.
*/
const generatorKeyId =
'arn:aws:kms:us-west-2:658956600833:alias/EncryptDecrypt'
/* Adding alternate KMS keys that can decrypt.
* Access to kms:Encrypt is required for every CMK in keyIds.
* You might list several keys in different AWS Regions.
* This allows you to decrypt the data in any of the represented Regions.
* In this example, I am using the same CMK.
* This is *only* to demonstrate how the CMK ARNs are configured.
*/
const keyIds = [
'arn:aws:kms:us-west-2:658956600833:key/b3537ef1-d8dc-4780-9f5a-55776cbb2f7f',
]
/* Need a client provider that will inject correct credentials.
* The credentials here are injected by webpack
* from your environment when the bundle is created.
* The credential values are pulled using @aws-sdk/credential-provider-node.
* See kms.webpack.config
* You should inject your credentials into the browser in a secure manner
* that works with your application.
*/
const { accessKeyId, secretAccessKey, sessionToken } = credentials
/* getClient takes a KMS client constructor
* and optional configuration values.
* The credentials can be injected here,
* because browser does not have a standard credential discover process
* the way Node.js does.
*/
const clientProvider = getClient(KMS, {
credentials: {
accessKeyId,
secretAccessKey,
sessionToken,
},
})
/* The KMS keyring must be configured with the desired CMKs */
const kmsKeyring = new KmsKeyringBrowser({
clientProvider,
generatorKeyId,
keyIds,
})
/* You need to specify a name
* and a namespace for raw encryption key providers.
* The name and namespace that you use in the decryption keyring *must* be an exact,
* *case-sensitive* match for the name and namespace in the encryption keyring.
*/
const keyName = 'aes-name'
const keyNamespace = 'aes-namespace'
/* The wrapping suite defines the AES-GCM algorithm suite to use. */
const wrappingSuite =
RawAesWrappingSuiteIdentifier.AES256_GCM_IV12_TAG16_NO_PADDING
// Get your plaintext master key from its storage location.
const unencryptedMasterKey = synchronousRandomValues(32)
/* The plaintext master key must be imported into a WebCrypto CryptoKey. */
const masterKey = await RawAesKeyringWebCrypto.importCryptoKey(
unencryptedMasterKey,
wrappingSuite
)
/* Configure the Raw AES keyring. */
const aesKeyring = new RawAesKeyringWebCrypto({
keyName,
keyNamespace,
wrappingSuite,
masterKey,
})
/* Combine the two keyrings into a multi-keyring. */
const keyring = new MultiKeyringWebCrypto({
generator: kmsKeyring,
children: [aesKeyring],
})
/* Encryption context is a *very* powerful tool for controlling and managing access.
* It is ***not*** secret!
* Encrypted data is opaque.
* You can use an encryption context to assert things about the encrypted data.
* Just because you can decrypt something does not mean it is what you expect.
* For example, if you are are only expecting data from 'us-west-2',
* the origin can identify a malicious actor.
* See: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
*/
const context = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2',
}
/* Find data to encrypt. */
const plainText = new Uint8Array([1, 2, 3, 4, 5])
/* Encrypt the data. */
const { result } = await encrypt(keyring, plainText, {
encryptionContext: context,
})
/* Log the plain text
* only for testing and to show that it works.
*/
console.log('plainText:', plainText)
document.write('</br>plainText:' + plainText + '</br>')
/* Log the base64-encoded result
* so that you can try decrypting it with another AWS Encryption SDK implementation.
*/
const resultBase64 = toBase64(result)
console.log(resultBase64)
document.write(resultBase64)
/* Decrypt the data.
* This decrypt call could be done with **any** of the 3 keyrings.
* Here we use the multi-keyring, but
* decrypt(kmsKeyring, result)
* decrypt(aesKeyring, result)
* would both work as well.
*/
const { plaintext, messageHeader } = await decrypt(keyring, result)
/* Grab the encryption context so you can verify it. */
const { encryptionContext } = messageHeader
/* Verify the encryption context.
* If you use an algorithm suite with signing,
* the Encryption SDK adds a name-value pair to the encryption context that contains the public key.
* Because the encryption context might contain additional key-value pairs,
* do not add a test that requires that all key-value pairs match.
* Instead, verify that the key-value pairs you expect match.
*/
Object.entries(context).forEach(([key, value]) => {
if (encryptionContext[key] !== value)
throw new Error('Encryption Context does not match expected values')
})
/* Log the clear message
* only for testing and to show that it works.
*/
document.write('</br>plaintext:' + plaintext)
console.log(plaintext)
/* Return the values to make testing easy. */
return { plainText, plaintext }
}