AWS Encryption SDK
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

AWS Encryption SDK for JavaScript Examples

The following examples show you how to use the AWS Encryption SDK for JavaScript to encrypt and decrypt data.

You can find more examples of using the AWS Encryption SDK for JavaScript in the example-node and example-browser modules in the aws-encryption-sdk-javascript repository on GitHub. These example modules are not installed when you install the client-browser or client-node modules.

See the complete code samples: Node: kms_simple.ts, Browser: kms_simple.ts

Encrypting Data with a KMS Keyring

The following example shows you how to use the AWS Encryption SDK for JavaScript to encrypt and decrypt a short string or byte array.

This example features a KMS keyring, a type of keyring that uses an AWS Key Management Service (AWS KMS) customer master key (CMK) to generate and encrypt data keys. For help creating a CMK, see Creating Keys in the AWS Key Management Service Developer Guide. For help finding the Amazon Resource Name (ARN) of an existing CMK, see Finding the Key ID and ARN in the AWS Key Management Service Developer Guide.

Step 1: Construct the keyring.

Create a KMS keyring for encryption.

When encrypting with a KMS keyring, you must specify a generator key, that is, an AWS KMS CMK that is used to generate the plaintext data key and encrypt it. You can also specify zero or more additional keys that encrypt the same plaintext data key. The keyring returns the plaintext data key and one encrypted copy of that data key for each CMK in the keyring, including the generator key. To decrypt the data, you need to decrypt any one of the encrypted data keys.

When you specify the CMKs for an encryption keyring in the AWS Encryption SDK for JavaScript, you can use any valid CMK identifier: a key ID, alias name, key ARN, or alias ARN. This example uses a generator key, which is identified by its alias ARN, and one additional key, which is identified by a key ARN.

Note

If you plan to reuse your KMS keyring for decrypting, you must use key ARNs to identify the CMKs in the keyring.

Before running this code, replace the example CMK identifiers with valid identifiers. You must have the permissions required to use the CMKs in the keyring.

JavaScript BrowserJavaScript Node.js
JavaScript Browser

Begin by providing your credentials to the browser. The AWS Encryption SDK for JavaScript examples use the webpack.DefinePlugin, which replaces the credential constants with your actual credentials. But you can use any method to provide your credentials. Then, use the credentials to create an AWS KMS client.

declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string } const clientProvider = getClient(KMS, { credentials: { accessKeyId, secretAccessKey, sessionToken } })

Next, specify the AWS KMS CMKs for the generator key and additional key. Then, create a KMS keyring using the AWS KMS client and the CMKs.

const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt' const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringBrowser({ clientProvider, generatorKeyId, keyIds })
JavaScript Node.js
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt' const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
Step 2: Set the encryption context.

An encryption context is arbitrary, non-secret additional authenticated data. When you provide an encryption context on encrypt, the AWS Encryption SDK cryptographically binds the encryption context to the ciphertext so that the same encryption context is required to decrypt the data. Using an encryption context is optional, but we recommend it as a best practice.

Create a simple object that includes the encryption context pairs. The key and value in each pair must be a string.

JavaScript BrowserJavaScript Node.js
JavaScript Browser
const context = { stage: 'demo', purpose: 'simple demonstration app', origin: 'us-west-2' }
JavaScript Node.js
const context = { stage: 'demo', purpose: 'simple demonstration app', origin: 'us-west-2' }
Step 3: Encrypt the data.

To encrypt the plaintext data, call the encrypt function. Pass in the KMS keyring, the plaintext data, and the encryption context.

The encrypt function returns an encrypted message (result) that contains the encrypted data, the encrypted data keys, and important metadata, including the encryption context and signature.

You can decrypt this encrypted message by using the AWS Encryption SDK for any supported programming language.

JavaScript BrowserJavaScript Node.js
JavaScript Browser
const plaintext = new Uint8Array([1, 2, 3, 4, 5]) const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
JavaScript Node.js
const plaintext = 'asdf' const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })

Decrypting Data with a KMS Keyring

You can use the AWS Encryption SDK for JavaScript to decrypt the encrypted message and recover the original data.

In this example, we decrypt the data that we encrypted in the Encrypting Data with a KMS Keyring example.

Step 1: Construct the keyring.

To decrypt the data, pass in the encrypted message (result) that the encrypt function returned. The encrypted message includes the encrypted data, the encrypted data keys, and important metadata, including the encryption context and signature.

You must also specify a KMS keyring when decrypting. You can use the same keyring that was used to encrypt the data or a different keyring. To succeed, at least one CMK in the decryption keyring must be able to decrypt one of the encrypted data keys in the encrypted message. Because no data keys are generated, you do not need to specify a generator key in a decryption keyring. If you do, the generator key and additional keys are treated the same way.

To specify a CMK for a decryption keyring in the AWS Encryption SDK for JavaScript, you must use the key ARN. Otherwise, the CMK is not recognized. For help finding the key ARN, see Finding the Key ID and ARN in the AWS Key Management Service Developer Guide.

Note

If you reuse an encryption keyring for decrypting, be sure that the CMKs in the keyring are identified by their key ARNs.

In this example, we create a keyring that includes only one of the CMKs in the encryption keyring. Before running this code, replace the example CMK ARN with a valid one. You must have kms:Decrypt permission on the CMK.

JavaScript BrowserJavaScript Node.js
JavaScript Browser

Begin by providing your credentials to the browser. The AWS Encryption SDK for JavaScript examples use the webpack.DefinePlugin, which replaces the credential constants with your actual credentials. But you can use any method to provide your credentials. Then, use the credentials to create an AWS KMS client.

declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string } const clientProvider = getClient(KMS, { credentials: { accessKeyId, secretAccessKey, sessionToken } })

Next, create a KMS keyring using the AWS KMS client. This example uses just one of the CMKs from the encryption keyring.

const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringBrowser({ clientProvider, keyIds })
JavaScript Node.js
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringNode({ keyIds })
Step 2: Decrypt the data.

Next, call the decrypt function. Pass in the decryption keyring that you just created (keyring) and the encrypted message that the encrypt function returned (result). The AWS Encryption SDK uses the keyring to decrypt one of the encrypted data keys. Then it uses the plaintext data key to decrypt the data.

If the call succeeds, the plaintext field contains the plaintext (decrypted) data. The messageHeader field contains metadata about the decryption process, including the encryption context that was used to decrypt the data.

JavaScript BrowserJavaScript Node.js
JavaScript Browser
const { plaintext, messageHeader } = await decrypt(keyring, result)
JavaScript Node.js
const { plaintext, messageHeader } = await decrypt(keyring, result)
Step 3: Verify the encryption context.

The encryption context that was used to decrypt the data is included in the message header (messageHeader) that the decrypt function returns. Before your application returns the plaintext data, verify that the encryption context that you provided when encrypting is included in the encryption context that was used when decrypting. A mismatch might indicate that the data was tampered with, or that you didn't decrypt the right ciphertext.

When verifying the encryption context, do not require an exact match. When you use an encryption algorithm with signing, the cryptographic materials manager (CMM) adds the public signing key to the encryption context before encrypting the message. But all of the encryption context pairs that you submitted should be included in the encryption context that was returned.

First, get the encryption context from the message header. Then, verify that each key-value pair in the original encryption context (context) matches a key-value pair in the returned encryption context (encryptionContext).

JavaScript BrowserJavaScript Node.js
JavaScript Browser
const { encryptionContext } = messageHeader Object .entries(context) .forEach(([key, value]) => { if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values') })
JavaScript Node.js
const { encryptionContext } = messageHeader Object .entries(context) .forEach(([key, value]) => { if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values') })

If the encryption context check succeeds, you can return the plaintext data.