本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 適用於 JavaScript 的 AWS Encryption SDK 適用於 JavaScript 的 AWS Encryption SDK 旨在為在 JavaScript 中撰寫 Web 瀏覽器應用程式的開發人員或在 Node.js 中撰寫 Web 伺服器應用程式的開發人員提供用戶端加密程式庫。 與 的所有實作一樣 AWS Encryption SDK， 適用於 JavaScript 的 AWS Encryption SDK 提供進階資料保護功能。這些功能包括[信封加密](concepts.md#envelope-encryption)、額外的驗證資料 (AAD) 以及安全、已認證的對稱金鑰[演算法套件](concepts.md#crypto-algorithm)，例如 256 位元 AES-GCM 搭配金鑰衍生和簽署。 根據語言的限制， 的所有特定語言實作 AWS Encryption SDK 都設計為可互通。如需 JavaScript 語言限制的詳細資訊，請參閱 [的相容性 適用於 JavaScript 的 AWS Encryption SDK](javascript-compatibility.md)。 **進一步了解** + 如需使用 進行程式設計的詳細資訊 適用於 JavaScript 的 AWS Encryption SDK，請參閱 GitHub 上的 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) 儲存庫。 + 如需程式設計範例，請參閱 [適用於 JavaScript 的 AWS Encryption SDK 範例](js-examples.md)和 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) 儲存庫中的 [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) 和 [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) 模組。 + 如需使用 適用於 JavaScript 的 AWS Encryption SDK 在 Web 應用程式中加密資料的真實範例，請參閱 AWS 安全部落格中的[如何使用 適用於 JavaScript 的 AWS Encryption SDK 和 Node.js 在瀏覽器中啟用加密](https://aws.amazon.com/blogs/security/how-to-enable-encryption-browser-aws-encryption-sdk-javascript-node-js/)。 **Topics** + [相容性](javascript-compatibility.md) + [安裝](javascript-installation.md) + [模組](javascript-modules.md) + [範例](js-examples.md) # 的相容性 適用於 JavaScript 的 AWS Encryption SDK 適用於 JavaScript 的 AWS Encryption SDK 旨在與 的其他語言實作互通 AWS Encryption SDK。在大多數情況下，您可以使用 加密資料 適用於 JavaScript 的 AWS Encryption SDK ，並使用任何其他語言實作解密資料，包括 [AWS Encryption SDK 命令列界面](crypto-cli.md)。您也可以使用 適用於 JavaScript 的 AWS Encryption SDK 來解密 其他語言實作所產生的[加密訊息](concepts.md#message) AWS Encryption SDK。 不過，當您使用 時 適用於 JavaScript 的 AWS Encryption SDK，您需要注意 JavaScript 語言實作和 Web 瀏覽器中的一些相容性問題。 此外，使用不同的語言實作時，請務必設定相容的主金鑰提供者、主金鑰和 keyring。如需詳細資訊，請參閱[Keyring 相容性](choose-keyring.md#keyring-compatibility)。 ## 適用於 JavaScript 的 AWS Encryption SDK 相容性 的 JavaScript 實作與其他語言實作 AWS Encryption SDK 不同，方式如下： + 的加密操作 適用於 JavaScript 的 AWS Encryption SDK 不會傳回非影格加密文字。不過， 適用於 JavaScript 的 AWS Encryption SDK 會解密 其他語言實作傳回的框架和非框架加密文字 AWS Encryption SDK。 + 從 Node.js 版本 12.9.0 開始，Node.js 支援以下 RSA 金鑰包裝選項： + 具有 SHA1、SHA256、SHA384 或 SHA512 的 OAEP + 具有 SHA1 的 OAEP 和具有 SHA1 的 MGF1 + PKCS1v15 + 在版本 12.9.0 之前，Node.js 僅支援以下 RSA 金鑰包裝選項： + 具有 SHA1 的 OAEP 和具有 SHA1 的 MGF1 + PKCS1v15 ## 瀏覽器相容性 某些 Web 瀏覽器不支援 適用於 JavaScript 的 AWS Encryption SDK 所需的基本密碼編譯操作。您可以透過瀏覽器實作的 WebCrypto API 設定備用來彌補部分遺漏的操作。 **Web 瀏覽器限制** 下列限制為所有 Web 瀏覽器通用： + WebCrypto API 不支援 PKCS1v15 金鑰包裝。 + 瀏覽器不支援 192 位元金鑰。 **必要的密碼編譯操作** 在 Web 瀏覽器中， 適用於 JavaScript 的 AWS Encryption SDK 需要下列操作。如果瀏覽器不支援這些操作，則它與 適用於 JavaScript 的 AWS Encryption SDK相容。 + 瀏覽器必須包含 `crypto.getRandomValues()`，這是一種以密碼編譯方式產生隨機值的方法。如需支援 `crypto.getRandomValues()` 之 Web 瀏覽器版本的相關資訊，請參閱[我可以使用 crypto.getRandomValues() 嗎？](https://caniuse.com/#feat=getrandomvalues)。 **必要的備用** 適用於 JavaScript 的 AWS Encryption SDK 需要在 Web 瀏覽器中執行下列程式庫和操作。如果您支援不符合這些需求的 Web 瀏覽器，則必須設定備用。否則，嘗試 適用於 JavaScript 的 AWS Encryption SDK 搭配瀏覽器使用 將會失敗。 + 會在 Web 應用程式中執行基本密碼編譯操作的 WebCrypto API，並非可在所有瀏覽器上使用。如需支援 Web 密碼編譯的 Web 瀏覽器版本的相關資訊，請參閱[我可以使用 Web 密碼編譯嗎？](https://caniuse.com/#feat=cryptography)。 + Safari Web 瀏覽器的現代版本不支援 AWS Encryption SDK 所需的零位元組 AES-GCM 加密。如果瀏覽器實作 WebCrypto API，但無法使用 AES-GCM 加密零位元組，則 只會 適用於 JavaScript 的 AWS Encryption SDK 使用備用程式庫進行零位元組加密。它會使用 WebCrypto API 進行所有其他操作。 若要設定任一限制的備用，請將下列陳述式新增至您的程式碼。在 [configureFallback](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/web-crypto-backend/src/backend-factory.ts#L78) 函數中，指定支援遺漏功能的程式庫。下列範例會使用 Microsoft Research JavaScript Cryptography Library (`msrcrypto`)，但是您可以以相容的程式庫取代它。如需完整範例，請參閱 [fallback.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/fallback.ts)。 ``` import { configureFallback } from '@aws-crypto/client-browser' configureFallback(msrCrypto) ``` # 安裝 適用於 JavaScript 的 AWS Encryption SDK 適用於 JavaScript 的 AWS Encryption SDK 包含相互依存模組的集合。模組中的數個只是設計要一起運作的模組集合。部分模組是專為獨立運作而設計。一些模組為所有實作所需；一些模組則僅用於特殊情況。如需有關 AWS Encryption SDK 適用於 JavaScript 的 中模組的資訊，請參閱 [中的模組 適用於 JavaScript 的 AWS Encryption SDK](javascript-modules.md)和 GitHub 上 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules) 儲存庫中每個模組中的 `README.md` 檔案。 **注意** 所有 適用於 JavaScript 的 AWS Encryption SDK 早於 2.0.0 的 版本都處於[end-of-support階段](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)。 您可以從 2.0.*x* 版和更新版本安全地更新至最新版本的 ， 適用於 JavaScript 的 AWS Encryption SDK 而不需要變更任何程式碼或資料。不過，2.0.*x* 版中引進[的新安全功能](about-versions.md#version-2)無法回溯相容。若要從 1.7.*x* 之前的版本更新至 2.0.*x* 及更新版本，您必須先更新至最新的 1 適用於 JavaScript 的 AWS Encryption SDK.*x* 版本。如需詳細資訊，請參閱[遷移您的 AWS Encryption SDK](migration.md)。 若要安裝模組，請使用 [npm 套件管理工具](https://www.npmjs.com/get-npm)。 例如，若要安裝`client-node`模組，其中包含使用 Node.js 適用於 JavaScript 的 AWS Encryption SDK 中的 進行程式設計所需的所有模組，請使用下列命令。 ``` npm install @aws-crypto/client-node ``` 若要安裝`client-browser`模組，其中包含在瀏覽器 適用於 JavaScript 的 AWS Encryption SDK 中使用 進行程式設計所需的所有模組，請使用下列命令。 ``` npm install @aws-crypto/client-browser ``` 如需如何使用 的工作範例 適用於 JavaScript 的 AWS Encryption SDK，請參閱 GitHub 上 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) 儲存庫中 `example-node`和 `example-browser`模組中的範例。 # 中的模組 適用於 JavaScript 的 AWS Encryption SDK 中的模組 適用於 JavaScript 的 AWS Encryption SDK 可讓您輕鬆地安裝專案所需的程式碼。 ## JavaScript Node.js 的模組 [client-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-node) 包含使用 Node.js 適用於 JavaScript 的 AWS Encryption SDK 中的 進行程式設計所需的所有模組。 [caching-materials-manager-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-node) 匯出支援 Node 適用於 JavaScript 的 AWS Encryption SDK .js 中 [資料金鑰快取](data-key-caching.md)功能的函數。 [decrypt-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-node) 匯出會解密並驗證代表資料和資料流的加密訊息的函數。包含在 `client-node` 模組中。 [encrypt-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-node) 匯出加密和簽署不同類型資料的函數。包含在 `client-node` 模組中。 [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) 在 Node.js 適用於 JavaScript 的 AWS Encryption SDK 中使用 匯出程式設計的工作範例。包括不同類型的 keyring 和不同類型資料的範例。 [hkdf-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/hkdf-node) 匯出 Node.js 適用於 JavaScript 的 AWS Encryption SDK 中 在特定演算法套件中使用的 [HMAC 型金鑰衍生函數](https://en.wikipedia.org/wiki/HKDF) (HKDF)。瀏覽器 適用於 JavaScript 的 AWS Encryption SDK 中的 使用 WebCrypto API 中的原生 HKDF 函數。 [integration-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-node) 定義測試，以驗證 Node.js 適用於 JavaScript 的 AWS Encryption SDK 中的 是否與 的其他語言實作相容 AWS Encryption SDK。 [kms-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-node) 匯出支援 Node.js 中 AWS KMS keyring 的函數。 [raw-aes-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-node) 匯出在 Node.js 中支援[原始 AES keyring](use-raw-aes-keyring.md) 的函數。 [raw-rsa-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-node) 匯出在 Node.js 中支援[原始 RSA keyring](use-raw-rsa-keyring.md) 的函數。 ## JavaScript 瀏覽器的模組 [client-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-browser) 包括您在瀏覽器 適用於 JavaScript 的 AWS Encryption SDK 中使用 進行程式設計所需的所有模組。 [caching-materials-manager-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-browser) 匯出支援瀏覽器中 JavaScript [資料金鑰快取](data-key-caching.md)功能的函數。 [decrypt-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-browser) 匯出會解密並驗證代表資料和資料流的加密訊息的函數。 [encrypt-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-browser) 匯出加密和簽署不同類型資料的函數。 [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) 在瀏覽器 適用於 JavaScript 的 AWS Encryption SDK 中使用 進行程式設計的工作範例。包括不同類型的 keyring 和不同類型資料的範例。 [integration-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-browser) 定義測試，以驗證瀏覽器中的 適用於 JAVA 的 AWS Encryption SDK指令碼是否與 的其他語言實作相容 AWS Encryption SDK。 [kms-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-browser) 匯出在瀏覽器中支援 [AWS KMS keyring ](use-kms-keyring.md)的函數。 [raw-aes-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-browser) 匯出在瀏覽器中支援[原始 AES keyring](use-raw-aes-keyring.md) 的函數。 [raw-rsa-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-browser) 匯出在瀏覽器中支援[原始 RSA keyring](use-raw-rsa-keyring.md) 的函數。 ## 適用於所有實作的模組 [cache-material](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/cache-material) 支援[資料金鑰快取](data-key-caching.md)功能。提供用於組合隨每個資料金鑰快取的密碼編譯資料的程式碼。 [kms-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring) 匯出支援 [KMS keyring](use-kms-keyring.md) 的函數。 [material-management](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/material-management) 實作[密碼編譯資料管理員](concepts.md#crypt-materials-manager) (CMM)。 [raw-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-keyring) 匯出原始 AES 和 RSA keyring 所需的函數。 [serialize](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/serialize) 匯出 SDK 用來序列化其輸出的函數。 [web-crypto-backend](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/web-crypto-backend) 匯出在瀏覽器的 中使用 WebCrypto API 適用於 JavaScript 的 AWS Encryption SDK 的函數。 # 適用於 JavaScript 的 AWS Encryption SDK 範例 以下範例說明如何使用 適用於 JavaScript 的 AWS Encryption SDK 來加密和解密資料。 您可以在 GitHub 適用於 JavaScript 的 AWS Encryption SDK 的 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) 儲存庫的 [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) 和 [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) 模組中找到更多使用 的範例。當您安裝 `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 keyring 加密資料 ](#javascript-example-encrypt) + [ ## 使用 AWS KMS keyring 解密資料 ](#javascript-example-decrypt) ## 使用 AWS KMS keyring 加密資料 下列範例示範如何使用 適用於 JavaScript 的 AWS Encryption SDK 來加密和解密短字串或位元組陣列。 此範例具有 [AWS KMS keyring](use-kms-keyring.md)，這是一種 keyring，使用 AWS KMS key 來產生和加密資料金鑰。如需建立 的說明 AWS KMS key，請參閱《 *AWS Key Management Service 開發人員指南*》中的[建立金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)。如需在 AWS KMS keyring AWS KMS keys 中識別 的說明，請參閱 [在 AWS KMS keyring AWS KMS keys 中識別](use-kms-keyring.md#kms-keyring-id) 步驟 1：設定承諾政策。 從 1.7.*x* 版開始 適用於 JavaScript 的 AWS Encryption SDK，您可以在呼叫執行個體化 AWS Encryption SDK 用戶端的新 `buildClient`函數時設定承諾政策。`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：建構 keyring。 建立用於加密的 AWS KMS keyring。 使用 AWS KMS keyring 加密時，您必須指定*產生器金鑰*，也就是 AWS KMS key 用來產生純文字資料金鑰並將其加密的 。您也可以指定零個或多個*額外的金鑰*來加密相同的純文字資料金鑰。keyring 會針對 keyring AWS KMS key 中的每個 傳回純文字資料金鑰和該資料金鑰的加密複本，包括產生器金鑰。若要解密資料，您需要解密任何一個加密的資料金鑰。 若要在 中指定加密 keyring AWS KMS keys 的 適用於 JavaScript 的 AWS Encryption SDK，您可以使用[任何支援的 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 keyring 進行解密，則必須使用金鑰 ARNs 來識別 keyring AWS KMS keys 中的 。 執行此程式碼之前，請將範例 AWS KMS key 識別符取代為有效的識別符。您必須具有在 keyring 中[使用 AWS KMS keys所需的許可](use-kms-keyring.md#kms-keyring-permissions)。 首先提供您的登入資料給瀏覽器。 適用於 JavaScript 的 AWS Encryption SDK 範例會使用 [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 keyring 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 keyring、純文字資料和加密內容。 `encrypt` 函數會傳回[加密訊息](concepts.md#message) (`result`)，其中包含加密的資料、加密的資料金鑰和重要的中繼資料，包括加密內容和簽章。 您可以使用任何支援的程式設計語言 AWS Encryption SDK 的 [來解密此加密訊息](#javascript-example-decrypt)。 ``` 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 keyring 解密資料 您可以使用 適用於 JavaScript 的 AWS Encryption SDK 解密加密的訊息並復原原始資料。 在此範例中，我們會解密我們在 [使用 AWS KMS keyring 加密資料](#javascript-example-encrypt) 範例中加密的資料。 步驟 1：設定承諾政策。 從 1.7.*x* 版開始 適用於 JavaScript 的 AWS Encryption SDK，您可以在呼叫執行個體化 AWS Encryption SDK 用戶端的新 `buildClient`函數時設定承諾政策。`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：建構 keyring。 若要解密資料，請傳入`encrypt`函數傳回的[加密訊息](concepts.md#message) (`result`)。加密的訊息包括加密的資料、加密的資料金鑰和重要的中繼資料，包括加密內容和簽章。 解密時，您還必須指定 [AWS KMS keyring](use-kms-keyring.md)。您可以使用用來加密資料或不同 keyring 的相同 keyring。若要成功，解密 keyring AWS KMS key 中至少有一個必須能夠解密加密訊息中的其中一個加密資料金鑰。由於不會產生任何資料金鑰，您不需要在解密 keyring 中指定產生器金鑰。如果您這麼做，則會以相同方式處理產生器金鑰和額外金鑰。 若要在 中指定解密 keyring AWS KMS key 的 適用於 JavaScript 的 AWS Encryption SDK，您必須使用[金鑰 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)。否則， AWS KMS key 就無法辨識 。如需在 AWS KMS keyring AWS KMS keys 中識別 的說明，請參閱 [在 AWS KMS keyring AWS KMS keys 中識別](use-kms-keyring.md#kms-keyring-id) 如果您使用相同的 keyring 來加密和解密，請使用金鑰 ARNs 來識別 keyring AWS KMS keys 中的 。 在此範例中，我們建立的 keyring 只包含加密 keyring AWS KMS keys 中的其中一個 。執行此程式碼之前，請將範例金鑰 ARN 換成有效的金鑰 ARN。您必須具有 AWS KMS key上的 `kms:Decrypt` 許可。 首先提供您的登入資料給瀏覽器。 適用於 JavaScript 的 AWS Encryption SDK 範例會使用 [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 keyring。此範例僅使用 AWS KMS keys 來自加密 keyring 的其中一個 。 ``` 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 (`keyring`) 和`encrypt`函數傳回的[加密訊息](concepts.md#message) (`result`)。 AWS Encryption SDK 使用 keyring 來解密其中一個加密的資料金鑰。然後它會使用純文字資料金鑰來解密資料。 如果呼叫成功，`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') }) ``` 如果加密內容檢查成功，您可以傳回純文字資料。