AWS Encryption SDK for JavaScript 例子 - AWS Encryption SDK
使用密钥环加密 AWS KMS 数据使用密钥环解密数据 AWS KMS

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

AWS Encryption SDK for JavaScript 例子

以下示例演示了如何使用 AWS Encryption SDK for JavaScript 加密和解密数据。

你可以在上的 e xample-node 和 example- browser 模块中找到更多使用示例。 AWS Encryption SDK for JavaScript aws-encryption-sdk-javascript GitHub在安装 client-browser 或 client-node 模块时，不会安装这些示例模块。

请参阅完整的代码示例：节点：kms_simple.ts，浏览器：kms_simple.ts

使用密钥环加密 AWS KMS 数据

以下示例说明如何使用 AWS Encryption SDK for JavaScript 来加密和解密短字符串或字节数组。

此示例以AWS KMS 密钥环为特色，这是一种使用生成和加密数据密钥 AWS KMS key 的密钥环。有关创建的帮助 AWS KMS key，请参阅《AWS Key Management Service 开发者指南》中的创建密钥。如需帮助识别 AWS KMS 钥匙圈 AWS KMS keys 中的内容，请参阅 在 AWS KMS 钥匙圈 AWS KMS keys 中识别

步骤 1：设置承诺政策。

从 1.7 版本开始。 x 中 AWS Encryption SDK for JavaScript，您可以在调用实例化客户端的新buildClient函数时设置承诺策略。 AWS Encryption SDK buildClient 函数需要表示承诺策略的枚举值。进行加密和解密时，该函数会返回强制执行您的承诺策略的已更新 encrypt 和 decrypt 函数。

以下示例使用buildClient函数来指定默认的承诺策略REQUIRE_ENCRYPT_REQUIRE_DECRYPT。您也可以使用buildClient来限制加密消息中加密数据密钥的数量。有关更多信息，请参阅 限制加密数据密钥。

JavaScript Browser
import {
  KmsKeyringBrowser,
  KMS,
  getClient,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-browser'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
JavaScript Node.js
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 密钥标识符。此示例使用一个由其别名ARN标识的生成器密钥和一个由密钥标识的附加密钥ARN。

注意

如果您打算重复使用密 AWS KMS 钥环进行解密，则必须使用密钥ARNs来识别密钥环 AWS KMS keys 中的密钥。

在运行此代码之前，请将示例标 AWS KMS key 识符替换为有效的标识符。您必须具有在密钥环中使用 AWS KMS keys所需的权限。

JavaScript Browser

首先，向浏览器提供您的凭证。这些 AWS Encryption SDK for JavaScript 示例使用 webpack。 DefinePlugin，它会将凭证常量替换为您的实际证书。但是，您可以使用任何方法以提供凭证。然后，使用凭据创建 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 })
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 })
步骤 3：设置加密上下文。

加密上下文是任意的非机密其他经过身份验证的数据。当您提供有关加密的加密上下文时，会 AWS Encryption SDK 以加密方式将加密上下文绑定到密文，因此解密数据需要相同的加密上下文。使用加密上下文是可选的，但作为一项最佳实践，建议您提供加密上下文。

创建一个包含加密上下文对的简单对象。每对中的键和值必须是一个字符串。

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'
}
步骤 4：加密数据。

要加密明文数据，请调用 encrypt 函数。传入 AWS KMS 密钥环、纯文本数据和加密上下文。

encrypt 函数返回加密的消息 (result)，其中包含加密的数据、加密的数据密钥和重要元数据，包括加密上下文和签名。

您可以对任何支持的编程语言使用来解密此加密消息。 AWS Encryption SDK

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 })

使用密钥环解密数据 AWS KMS

您可以使用 AWS Encryption SDK for JavaScript 来解密加密的邮件并恢复原始数据。

在该示例中，我们解密在使用密钥环加密 AWS KMS 数据示例中加密的数据。

步骤 1：设置承诺政策。

从 1.7 版本开始。 x 中 AWS Encryption SDK for JavaScript，您可以在调用实例化客户端的新buildClient函数时设置承诺策略。 AWS Encryption SDK buildClient 函数需要表示承诺策略的枚举值。进行加密和解密时，该函数会返回强制执行您的承诺策略的已更新 encrypt 和 decrypt 函数。

以下示例使用buildClient函数来指定默认的承诺策略REQUIRE_ENCRYPT_REQUIRE_DECRYPT。您也可以使用buildClient来限制加密消息中加密数据密钥的数量。有关更多信息，请参阅 限制加密数据密钥。

JavaScript Browser
import {
  KmsKeyringBrowser,
  KMS,
  getClient,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-browser'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
JavaScript Node.js
import {
  KmsKeyringNode,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-node'
                                
const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
步骤 2：构造密钥环。

要解密数据，请传入 encrypt 函数返回的加密消息 (result)。加密的消息包括加密的数据、加密的数据密钥和重要元数据，包括加密上下文和签名。

在解密时，您还必须指定一个 AWS KMS 密钥环。您可以使用用于加密数据的相同密钥环，或者使用不同的密钥环。要成功，解密密钥环 AWS KMS key 中必须至少有一个能够解密加密消息中的一个加密数据密钥。由于没有生成任何数据密钥，您不需要在解密密钥环中指定生成器密钥。如果这样做，将按相同的方式处理生成器密钥和附加密钥。

要在中 AWS KMS key 为解密密钥环指定一个 AWS Encryption SDK for JavaScript，必须使用该密钥。ARN否则 AWS KMS key ，将无法识别。如需帮助识别 AWS KMS 钥匙圈 AWS KMS keys 中的内容，请参阅 在 AWS KMS 钥匙圈 AWS KMS keys 中识别

注意

如果您使用相同的密钥环进行加密和解密，请使用密钥ARNs来识别密钥环中的 AWS KMS keys 密钥。

在此示例中，我们创建了一个仅包含加密密钥环 AWS KMS keys 中的一个的密钥环。在运行此代码之前，请将示例密钥ARN替换为有效的密钥。您必须具有 AWS KMS key的 kms:Decrypt 权限。

JavaScript Browser

首先，向浏览器提供您的凭证。这些 AWS Encryption SDK for JavaScript 示例使用 webpack。 DefinePlugin，它会将凭证常量替换为您的实际证书。但是，您可以使用任何方法以提供凭证。然后，使用凭据创建 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 })
JavaScript Node.js
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']

const keyring = new KmsKeyringNode({ keyIds })
步骤 3：解密数据。

接下来，调用 decrypt 函数。传入您刚刚创建的解密密钥环 (keyring) 和 encrypt 函数返回的加密消息 (result)。 AWS Encryption SDK 使用密钥环解密其中一个加密的数据密钥。然后，它使用明文数据密钥以解密数据。

如果调用成功，则 plaintext 字段包含明文（已解密）数据。messageHeader 字段包含有关解密过程的元数据，包括用于解密数据的加密上下文。

JavaScript Browser
const { plaintext, messageHeader } = await decrypt(keyring, result)
JavaScript Node.js
const { plaintext, messageHeader } = await decrypt(keyring, result)
步骤 4：验证加密上下文。

用于解密数据的加密上下文包含在 decrypt 函数返回的消息标头 (messageHeader) 中。在应用程序返回明文数据之前，请验证在解密时使用的加密上下文中是否包含在加密时提供的加密上下文。如果不匹配，则可能表明数据被篡改，或者您没有解密正确的密文。

在验证加密上下文时，不需要完全匹配。当您使用加密算法进行签名时，加密材料管理器 (CMM) 会在加密邮件之前将公共签名密钥添加到加密上下文中。但是，您提交的所有加密上下文对应包含在返回的加密上下文中。

首先，从消息标头中获取加密上下文。然后，验证原始加密上下文 (context) 中的每个键值对与返回的加密上下文 (encryptionContext) 中的键值对是否匹配。

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')
})

如果加密上下文检查成功，您可以返回明文数据。