本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AWS Encryption SDK for JavaScript 例子
以下示例演示了如何使用 AWS Encryption SDK for JavaScript 加密和解密数据。
你可以在上的 e [xample-node 和 example-](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) [browser 模块中找到更多使用示例](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser)。 AWS Encryption SDK for JavaScript [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) GitHub在安装 `client-browser` 或 `client-node` 模块时，不会安装这些示例模块。
请**参阅完整的代码示例**：节点：[kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_simple.ts)，浏览器：[kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/kms_simple.ts)
**Topics**
+ [使用密钥环加密 AWS KMS 数据](#javascript-example-encrypt)
+ [使用密钥环解密数据 AWS KMS](#javascript-example-decrypt)
## 使用密钥环加密 AWS KMS 数据
以下示例说明如何使用 AWS Encryption SDK for JavaScript 来加密和解密短字符串或字节数组。
此示例以[AWS KMS 密钥环](use-kms-keyring.md)为特色，这是一种使用生成和加密数据密钥 AWS KMS key 的密钥环。有关创建的帮助 AWS KMS key，请参阅《*AWS Key Management Service 开发者指南》*中的[创建密钥](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)。如需帮助识别 AWS KMS 钥匙圈 AWS KMS keys 中的内容，请参阅 [在 AWS KMS 钥匙圈 AWS KMS keys 中识别](use-kms-keyring.md#kms-keyring-id)
步骤 1：设置承诺政策。
从 1.7 版本开始。 *x* 中 AWS Encryption SDK for JavaScript，您可以在调用实例化客户端的新`buildClient`函数时设置承诺策略。 AWS Encryption SDK `buildClient` 函数需要表示承诺策略的枚举值。进行加密和解密时，该函数会返回强制执行您的承诺策略的已更新 `encrypt` 和 `decrypt` 函数。
以下示例使用`buildClient`函数来指定[默认的承诺策略](migrate-commitment-policy.md)`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。您也可以使用`buildClient`来限制加密消息中加密数据密钥的数量。有关更多信息，请参阅 [限制加密数据密钥](configure.md#config-limit-keys)。
```
import {
KmsKeyringBrowser,
KMS,
getClient,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
步骤 2：构造密钥环。
创建用于加密的 AWS KMS 密钥环。
使用密 AWS KMS 钥环加密时，必须指定*生成器密钥*，即用于生成纯文本数据密钥并对其进行加密的生成器密钥。 AWS KMS key 您还可以指定零个或更多*附加密钥*，以加密相同的明文数据密钥。密钥环返回密钥环中每个 AWS KMS key 密钥的纯文本数据密钥和该数据密钥的一个加密副本，包括生成器密钥。要解密数据，您需要解密任一加密数据密钥。
要在中 AWS KMS keys 为加密密钥环指定 AWS Encryption SDK for JavaScript，您可以使用[任何支持的 AWS KMS 密钥标识符](use-kms-keyring.md#kms-keyring-id)。该示例使用一个生成器密钥（由其[别名 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN) 标识）和一个附加密钥（由[密钥 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) 标识）。
如果您打算重复使用密 AWS KMS 钥环进行解密，则必须使用密钥 ARNs 来识别密钥环 AWS KMS keys 中的密钥。
在运行此代码之前，请将示例标 AWS KMS key 识符替换为有效的标识符。您必须具有在密钥环中[使用 AWS KMS keys所需的权限](use-kms-keyring.md#kms-keyring-permissions)。
首先，向浏览器提供您的凭证。这些 AWS Encryption SDK for JavaScript 示例使用 [webpack。 DefinePlugin](https://webpack.js.org/plugins/define-plugin/)，它会将凭证常量替换为您的实际证书。但是，您可以使用任何方法以提供凭证。然后，使用凭据创建 AWS KMS 客户端。
```
declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }
const clientProvider = getClient(KMS, {
credentials: {
accessKeyId,
secretAccessKey,
sessionToken
}
})
```
接下来， AWS KMS keys 为生成器密钥和其他密钥指定。然后，使用 AWS KMS 客户端和创建 AWS KMS 密钥环。 AWS KMS keys
```
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 })
```
```
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 })
```
步骤 3：设置加密上下文。
[加密上下文](concepts.md#encryption-context)是任意的非机密其他经过身份验证的数据。当您提供有关加密的加密上下文时，会 AWS Encryption SDK 以加密方式将加密上下文绑定到密文，因此解密数据需要相同的加密上下文。使用加密上下文是可选的，但作为一项最佳实践，建议您提供加密上下文。
创建一个包含加密上下文对的简单对象。每对中的键和值必须是一个字符串。
```
const context = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2'
}
```
```
const context = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2'
}
```
步骤 4：加密数据。
要加密明文数据，请调用 `encrypt` 函数。传入 AWS KMS 密钥环、纯文本数据和加密上下文。
`encrypt` 函数返回[加密的消息](concepts.md#message) (`result`)，其中包含加密的数据、加密的数据密钥和重要元数据，包括加密上下文和签名。
您可以对任何支持的编程语言使用来[解密此加密消息](#javascript-example-decrypt)。 AWS Encryption SDK
```
const plaintext = new Uint8Array([1, 2, 3, 4, 5])
const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
```
```
const plaintext = 'asdf'
const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
```
## 使用密钥环解密数据 AWS KMS
您可以使用 AWS Encryption SDK for JavaScript 来解密加密的邮件并恢复原始数据。
在该示例中，我们解密在[使用密钥环加密 AWS KMS 数据](#javascript-example-encrypt)示例中加密的数据。
步骤 1：设置承诺政策。
从 1.7 版本开始。 *x* 中 AWS Encryption SDK for JavaScript，您可以在调用实例化客户端的新`buildClient`函数时设置承诺策略。 AWS Encryption SDK `buildClient` 函数需要表示承诺策略的枚举值。进行加密和解密时，该函数会返回强制执行您的承诺策略的已更新 `encrypt` 和 `decrypt` 函数。
以下示例使用`buildClient`函数来指定[默认的承诺策略](migrate-commitment-policy.md)`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。您也可以使用`buildClient`来限制加密消息中加密数据密钥的数量。有关更多信息，请参阅 [限制加密数据密钥](configure.md#config-limit-keys)。
```
import {
KmsKeyringBrowser,
KMS,
getClient,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
步骤 2：构造密钥环。
要解密数据，请传入 `encrypt` 函数返回的[加密消息](concepts.md#message) (`result`)。加密的消息包括加密的数据、加密的数据密钥和重要元数据，包括加密上下文和签名。
在解密时，您还必须指定一个 [AWS KMS 密钥环](use-kms-keyring.md)。您可以使用用于加密数据的相同密钥环，或者使用不同的密钥环。要成功，解密密钥环 AWS KMS key 中必须至少有一个能够解密加密消息中的一个加密数据密钥。由于没有生成任何数据密钥，您不需要在解密密钥环中指定生成器密钥。如果这样做，将按相同的方式处理生成器密钥和附加密钥。
[要在中 AWS KMS key 为解密密钥环指定一个 AWS Encryption SDK for JavaScript，必须使用密钥 ARN。](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)否则 AWS KMS key ，将无法识别。如需帮助识别 AWS KMS 钥匙圈 AWS KMS keys 中的内容，请参阅 [在 AWS KMS 钥匙圈 AWS KMS keys 中识别](use-kms-keyring.md#kms-keyring-id)
如果您使用相同的密钥环进行加密和解密，请使用密钥 ARNs 来识别密钥环中的 AWS KMS keys 密钥。
在此示例中，我们创建了一个仅包含加密密钥环 AWS KMS keys 中的一个的密钥环。在运行该代码之前，请将示例密钥 ARN 替换为有效 ARN。您必须具有 AWS KMS key的 `kms:Decrypt` 权限。
首先，向浏览器提供您的凭证。这些 AWS Encryption SDK for JavaScript 示例使用 [webpack。 DefinePlugin](https://webpack.js.org/plugins/define-plugin/)，它会将凭证常量替换为您的实际证书。但是，您可以使用任何方法以提供凭证。然后，使用凭据创建 AWS KMS 客户端。
```
declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }
const clientProvider = getClient(KMS, {
credentials: {
accessKeyId,
secretAccessKey,
sessionToken
}
})
```
接下来，使用 AWS KMS 客户端创建 AWS KMS 密钥环。此示例仅使用加密密钥环 AWS KMS keys 中的一个。
```
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringBrowser({ clientProvider, keyIds })
```
```
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ keyIds })
```
步骤 3：解密数据。
接下来，调用 `decrypt` 函数。传入您刚刚创建的解密密钥环 (`keyring`) 和 `encrypt` 函数返回的[加密消息](concepts.md#message) (`result`)。 AWS Encryption SDK 使用密钥环解密其中一个加密的数据密钥。然后，它使用明文数据密钥以解密数据。
如果调用成功，则 `plaintext` 字段包含明文（已解密）数据。`messageHeader` 字段包含有关解密过程的元数据，包括用于解密数据的加密上下文。
```
const { plaintext, messageHeader } = await decrypt(keyring, result)
```
```
const { plaintext, messageHeader } = await decrypt(keyring, result)
```
步骤 4：验证加密上下文。
用于解密数据的[加密上下文](concepts.md#encryption-context)包含在 `decrypt` 函数返回的消息标头 (`messageHeader`) 中。在应用程序返回明文数据之前，请验证在解密时使用的加密上下文中是否包含在加密时提供的加密上下文。如果不匹配，则可能表明数据被篡改，或者您没有解密正确的密文。
在验证加密上下文时，不需要完全匹配。在将加密算法与签名一起使用时，[加密材料管理器](concepts.md#crypt-materials-manager) (CMM) 在加密消息之前将公有签名密钥添加到加密上下文中。但是，您提交的所有加密上下文对应包含在返回的加密上下文中。
首先，从消息标头中获取加密上下文。然后，验证原始加密上下文 (`context`) 中的每个键值对与返回的加密上下文 (`encryptionContext`) 中的键值对是否匹配。
```
const { encryptionContext } = messageHeader
Object
.entries(context)
.forEach(([key, value]) => {
if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})
```
```
const { encryptionContext } = messageHeader
Object
.entries(context)
.forEach(([key, value]) => {
if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})
```
如果加密上下文检查成功，您可以返回明文数据。