適用於 JavaScript 的 AWS Encryption SDK 範例 - AWS Encryption SDK
使用 AWS KMS 鍵控加密資料使用 AWS KMS 鍵控解密資料

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

適用於 JavaScript 的 AWS Encryption SDK 範例

以下範例說明如何使用 適用於 JavaScript 的 AWS Encryption SDK 來加密和解密資料。

您可以在 的儲存aws-encryption-sdk-javascript庫 適用於 JavaScript 的 AWS Encryption SDK 中，尋找更多使用 的範例節點和範例瀏覽器模組的範例 GitHub。當您安裝 client-browser 或 client-node 模組時，不會安裝這些範例模組。

請參閱完整的程式碼範例：節點：kms_simple.ts，瀏覽器：kms_simple.ts

使用 AWS KMS 鍵控加密資料

下列範例示範如何使用 適用於 JavaScript 的 AWS Encryption SDK 來加密和解密短字串或位元組陣列。

此範例具有 AWS KMS 鍵環 ，這是一種使用 AWS KMS key 來產生和加密資料金鑰的鍵環類型。如需建立 的說明 AWS KMS key，請參閱 AWS Key Management Service 開發人員指南 中的建立金鑰。如需識別 AWS KMS 金鑰環 AWS KMS keys 中 的協助，請參閱 在鍵環 AWS KMS keys 中 AWS KMS 識別

步驟 1：設定承諾政策。

從 1.7.x 版開始 適用於 JavaScript 的 AWS Encryption SDK，您可以在呼叫可實例化 AWS Encryption SDK 用戶端的新buildClient函數時設定承諾政策。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 在 中指定加密金鑰控制的 適用於 JavaScript 的 AWS Encryption SDK，您可以使用任何支援的 AWS KMS 金鑰識別符 。此範例使用由別名 ARN識別的產生器金鑰，以及由金鑰 識別的另一個金鑰ARN。

注意

如果您打算重複使用 AWS KMS 鍵環進行解密，則必須使用 鍵ARNs來識別 鍵環 AWS KMS keys 中的 。

執行此程式碼之前，請將範例 AWS KMS key 識別碼取代為有效的識別碼。您必須具有在 keyring 中使用 AWS KMS keys所需的許可。

JavaScript Browser

首先提供您的登入資料給瀏覽器。這些 適用於 JavaScript 的 AWS Encryption SDK 範例使用 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 鍵控解密資料

您可以使用 適用於 JavaScript 的 AWS Encryption SDK 解密加密的訊息並復原原始資料。

在此範例中，我們會解密我們在 使用 AWS KMS 鍵控加密資料 範例中加密的資料。

步驟 1：設定承諾政策。

從 1.7.x 版開始 適用於 JavaScript 的 AWS Encryption SDK，您可以在呼叫可實例化 AWS Encryption SDK 用戶端的新buildClient函數時設定承諾政策。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 金鑰輸入。您可以使用用來加密資料或不同 keyring 的相同 keyring。若要成功，解密鍵控 AWS KMS key 中至少有一個必須能夠解密加密訊息中的其中一個加密資料金鑰。由於不會產生任何資料金鑰，您不需要在解密 keyring 中指定產生器金鑰。如果您這麼做，則會以相同方式處理產生器金鑰和額外金鑰。

若要 AWS KMS key 在 中指定解密金鑰控制的 適用於 JavaScript 的 AWS Encryption SDK，您必須使用金鑰 ARN。否則， AWS KMS key 就無法辨識。如需在 AWS KMS 金鑰環 AWS KMS keys 中識別 的說明，請參閱 在鍵環 AWS KMS keys 中 AWS KMS 識別

注意

如果您使用相同的鍵環進行加密和解密，請使用 鍵ARNs來識別鍵環 AWS KMS keys 中的 。

在此範例中，我們建立的金鑰環僅包含加密金鑰環 AWS KMS keys 中的其中一個 。在執行此程式碼之前，請將範例金鑰取代ARN為有效的金鑰。您必須具有 AWS KMS key上的 kms:Decrypt 許可。

JavaScript Browser

首先提供您的登入資料給瀏覽器。這些 適用於 JavaScript 的 AWS Encryption SDK 範例使用 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')
})

如果加密內容檢查成功，您可以傳回純文字資料。