本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 適用於 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')
})
```
如果加密內容檢查成功，您可以傳回純文字資料。