適用於 JavaScript 的 AWS Encryption SDK 範例

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

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

查看完整的程式碼範例：節點：千米簡單。，瀏覽器：千米簡單。

使用 加密資料AWS KMSKeyring

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

此示例的特點是AWS KMSKeyring，一種密鑰環，使用AWS KMS key生成和加密數據密鑰。有關創建AWS KMS key，請參建立金鑰中的AWS Key Management Service開發人員指南。有關識別AWS KMS keys在AWS KMSkeyring，請參在 AWS KMS 鑰匙圈 AWS KMS keys 中識別

步驟 1：建構 keyring。

建立AWS KMS用於加密的金鑰。

當使用AWS KMS密鑰環，則必須指定產生器金鑰，也就是説，一個AWS KMS key，用來產生純文字資料金鑰並加密它。您也可以指定零個或多個額外的金鑰來加密相同的純文字資料金鑰。keyring 會傳回 keyring 中每個 AWS KMS key 金鑰 (包括產生器金鑰) 的純文字資料金鑰，以及該資料金鑰的一個加密副本。若要解密資料，您需要解密任何一個加密的資料金鑰。

若要在 適用於 JavaScript 的 AWS Encryption SDK 中指定加密 keyring 的 AWS KMS keys，您可以使用任何支援的 AWS KMS 金鑰識別符。此範例會使用產生器金鑰 (依別名 ARN 識別)，以及一個額外的金鑰 (依金鑰 ARN 識別)。

注意

如果您計劃重複使用AWS KMS金鑰環進行解密，您必須使用金鑰 ARN 標識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使用 keyringAWS 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 })

步驟 2：設定加密內容。

加密內容是一種任意、非私密額外驗證資料。在加密時提供加密內容時，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'
}

步驟 3：加密數據。

若要加密純文字資料，請呼叫 encrypt 函數。傳入AWS KMSkeyring、純文字資料和加密內容。

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 KMSKeyring

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

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

步驟 1：建構 keyring。

若要解密資料，請傳入已加密訊息(result），該encrypt函數返回。加密的訊息包括加密的資料、加密的資料金鑰和重要的中繼資料，包括加密內容和簽章。

您還必須指定AWS KMSKeyring解密時。您可以使用用來加密資料或不同 keyring 的相同 keyring。若要成功，解密 keyring 中至少有一個 AWS KMS key 可以解密加密訊息中其中一個加密的資料金鑰。由於不會產生任何資料金鑰，您不需要在解密 keyring 中指定產生器金鑰。如果您這麼做，則會以相同方式處理產生器金鑰和額外金鑰。

要指定AWS KMS key中的解密密鑰環適用於 JavaScript 的 AWS Encryption SDK，您必須使用金鑰 ARN。否則，將無法辨識 AWS KMS key。有關識別AWS KMS keys在AWS KMSkeyring，請參在 AWS KMS 鑰匙圈 AWS KMS keys 中識別

注意

如果您使用相同的 keyring 進行加密和解密，請使用金鑰 ARN 來識別 keyring 中的 AWS KMS keys。

在此範例中，我們會建立只包含加密 keyring 中其中一個 AWS KMS keys 的 keyring。執行此程式碼之前，請將範例金鑰 ARN 換成有效的金鑰 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使用 keyringAWS KMS客户端。此範例只使用來自加密 keyring 的其中一個 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 })

步驟 2：解密資料。

接下來，呼叫 decrypt 函數。傳入剛剛創建的解密密鑰環（keyring）和已加密訊息認為encrypt函數返回 (result。AWS Encryption SDK 使用 keyring 來解密其中一個加密的資料金鑰。然後它會使用純文字資料金鑰來解密資料。

如果呼叫成功，plaintext 欄位會包含純文字 (已解密) 資料。messageHeader 欄位包含有關解密程序的中繼資料，包括用來解密資料的加密內容。

JavaScript Browser

const { plaintext, messageHeader } = await decrypt(keyring, result)

JavaScript Node.js

const { plaintext, messageHeader } = await decrypt(keyring, result)

步驟 3：驗證加密內容。

用來解密資料的加密內容包含在 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')
})

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