選擇一種編程語言選擇包裝鍵使用多地區 AWS KMS keys 選擇演算法套件限制加密的資料金鑰建立探索篩選器設定承諾產品原則使用串流資料快取資料金鑰

配置 AWS Encryption SDK

設計 AWS Encryption SDK 為易於使用。雖然 AWS Encryption SDK 有數個組態選項，但預設值是經過仔細選擇，以便在大多數應用程式中實用且安全。不過，您可能需要調整組態以改善效能，或在設計中包含自訂功能。

設定實作時，請檢閱最 AWS Encryption SDK 佳做法並儘可能多地實作。

主題

選擇一種編程語言
選擇包裝鍵
使用多地區 AWS KMS keys
選擇演算法套件
限制加密的資料金鑰
建立探索篩選器
設定承諾產品原則
使用串流資料
快取資料金鑰

選擇一種編程語言

提供多種程式設計語言版本 AWS Encryption SDK 。語言實現被設計為完全可互操作，並提供相同的功能，儘管它們可能以不同的方式實現。一般而言，您會使用與應用程式相容的程式庫。不過，您可以為特定實作選取程式設計語言。例如，如果您偏好使用金鑰圈，您可以選擇適用於 C 的 AWS Encryption SDK 或。適用於 JavaScript 的 AWS Encryption SDK

選擇包裝鍵

會 AWS Encryption SDK 產生唯一的對稱資料金鑰來加密每則訊息。除非您使用資料金鑰快取，否則您不需要設定、管理或使用資料金鑰。 AWS Encryption SDK 它為你做。

但是，您必須選取一或多個包裝金鑰來加密每個資料金鑰。 AWS Encryption SDK 支援不同大小的AES對RSA稱金鑰和非對稱金鑰。它還支持 AWS Key Management Service（AWS KMS）對稱加密 AWS KMS keys。您必須為包裝金鑰的安全性和耐久性負責，因此我們建議您在硬體安全性模組或金鑰基礎架構服務 (例如) 中使用加密金鑰 AWS KMS。

若要指定用於加密和解密的包裝金鑰，請使用金鑰環 (C 和 JavaScript) 或主要金鑰提供者 (Java、Python、 AWS 加密CLI)。您可以指定相同或不同類型的一個包裝鍵或多個包裝鍵。如果您使用多個包裝金鑰來包裝資料金鑰，每個包裝金鑰都會加密相同資料金鑰的副本。加密的數據密鑰（每個包裝密鑰一個）與加密數據一起存儲在 AWS Encryption SDK 返回的加密消息中。若要解密資料， AWS Encryption SDK 必須先使用其中一個包裝金鑰來解密加密的資料金鑰。

若要 AWS KMS key 在金鑰環或主要金鑰提供者中指定，請使用支援的 AWS KMS 金鑰識別碼。如需金鑰的金鑰識別碼的詳細資訊，請參閱AWS Key Management Service 開發人員指南中的金鑰識別碼。 AWS KMS

使用適用於 JAVA 的 AWS Encryption SDK、、或加密進行 AWS 加密時適用於 JavaScript 的 AWS Encryption SDK 適用於 Python 的 AWS Encryption SDK CLI，您可以對金鑰使用任何有效的金鑰識別碼 (金鑰 ID ARN、金鑰、別名或別名ARN)。KMS使用加密時適用於 C 的 AWS Encryption SDK，您只能使用金鑰 ID 或金鑰ARN。

如果您在加密時ARN為KMS金鑰指定別名或別名，則會儲 AWS Encryption SDK 存ARN目前與該別名相關聯的金鑰，而不會儲存別名。對別名的變更不會影響用KMS於解密資料金鑰的金鑰。
在嚴謹模式 (指定特定包裝金鑰) 中解密時，您必須使用金鑰ARN來識別 AWS KMS keys。此要求適用於 AWS Encryption SDK的所有語言實作。

當您使用金 AWS KMS 鑰圈加密時，會將金鑰 AWS Encryption SDK ARN儲存 AWS KMS key 在加密資料金鑰的中繼資料中。在嚴謹模式下解密時，會在嘗試使用環繞金鑰來解密加密的 AWS Encryption SDK 資料金鑰之前，先確認相同的金鑰ARN出現在金鑰環 (或主要金鑰提供者) 中。如果您使用不同的金鑰識別碼，即使識別碼參照相同的金鑰 AWS KMS key，也無法辨識或使用。 AWS Encryption SDK

若要將原始AES金鑰或原始 RSA key pair 指定為金鑰環中的環繞金鑰，您必須指定命名空間和名稱。在主要金鑰提供者中Provider ID，相當於命名空間，而Key ID且相等於名稱。解密時，您必須為每個原始包裝金鑰使用與加密時使用完全相同的命名空間和名稱。如果您使用不同的命名空間或名稱，則即使密鑰材料相同，也不 AWS Encryption SDK 會識別或使用包裝鍵。

使用多地區 AWS KMS keys

您可以在中使用 AWS Key Management Service (AWS KMS) 多區域鍵作為包裝鍵。 AWS Encryption SDK如果您使用一個多區域金鑰加密 AWS 區域，則可以使用不同的相關多區域金鑰來解密。 AWS 區域 2.3 版中引入了對多區域鍵的 Support。和 3.0 版 AWS Encryption SDK 本的 x。 x 的加 AWS 密CLI。

AWS KMS 多區域金鑰是具有相同金鑰材料和金鑰 ID 的 AWS KMS keys 一組不 AWS 區域同金鑰。您可以使用這些相關鍵字，就好像它們在不同區域中是相同的索引鍵一樣。多區域金鑰支援常見的災難復原和備份案例，這些案例需要在一個區域中進行加密，並在不同區域進行解密，而不需要跨區域呼叫。 AWS KMS如需有關多區域金鑰的詳細資訊，請參閱AWS Key Management Service 開發人員指南中的使用多區域金鑰。

為了支援多區域金鑰， AWS Encryption SDK 包括 AWS KMS 多區域感知金鑰環和主金鑰提供者。每種程式語言中的全新多區域感知符號同時支援單一區域和多區域金鑰。

對於單一區域金鑰，多區域感知符號的行為與單一區域金鑰圈和主要金鑰提供者一 AWS KMS 樣。它只會嘗試使用加密資料的單一區域金鑰來解密密文。
對於多區域金鑰，多區域感知符號會嘗試使用加密資料的相同多區域金鑰，或使用您指定之區域中的相關多區域金鑰來解密密文。

在採用多個金鑰的多區域感知金鑰環和主要金鑰提供者中，您可以指定多個單一區域和多區域KMS金鑰。不過，您只能從每組相關的多區域金鑰中指定一個金鑰。如果您使用相同的金鑰 ID 指定多個索引鍵識別碼，建構函式呼叫會失敗。

您也可以將多區域金鑰與標準、單一區域金鑰 AWS KMS 圈和主要金鑰提供者搭配使用。不過，您必須在相同區域中使用相同的多區域金鑰來加密和解密。單一區域金鑰圈和主金鑰提供者只會嘗試使用加密資料的金鑰來解密密文。

下列範例顯示如何使用多區域金鑰以及新的多區域感知金鑰環和主金鑰提供者來加密和解密資料。這些範例會加密「us-east-1區域」中的資料，並使用每個區域中的相關多us-west-2區域金鑰來解密「區域」中的資料。在執行這些範例之前，請先將範例多區域鍵ARN取代為您 AWS 帳戶的.

C

若要使用多區域金鑰加密，請使用方Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder()法來實體化金鑰環。指定多區域金鑰。

這個簡單的範例不包含加密內容。如需在 C 中使用加密內容的範例，請參閱加密和解密字串。

如需完整範例，請參閱的適用於 C 的 AWS Encryption SDK 存放庫中的 kms_multi_region_keys.cpp GitHub。


/* Encrypt with a multi-Region KMS key in us-east-1 */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Initialize a multi-Region keyring */
const char *mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";   

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_east_1);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring);

aws_cryptosdk_keyring_release(mrk_keyring);

/* Encrypt the data
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, ciphertext, ciphertext_buf_sz, &ciphertext_len, plaintext, plaintext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);

C# / .NET

若要使用美國東部 (維吉尼亞北部) (us-east-1) 區域中的多區域金鑰加密，請使用多區域金鑰的金鑰識別碼和指定區域的用戶端來建立CreateAwsKmsMrkKeyringInput物件。 AWS KMS 然後使用該CreateAwsKmsMrkKeyring()方法來創建鑰匙圈。

此方CreateAwsKmsMrkKeyring()法會建立只有一個多區域金鑰的金鑰圈。若要使用多個包裝金鑰 (包括多區域金鑰) 加密，請使用方CreateAwsKmsMrkMultiKeyring()法。

如需完整範例，請參閱中的 AwsKmsMrkKeyringExample AWS Encryption SDK .cs。 NET儲存庫於 GitHub。


//Encrypt with a multi-Region KMS key in us-east-1 Region

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();


// Multi-Region keys have a distinctive key ID that begins with 'mrk'
// Specify a multi-Region key in us-east-1
string mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Create the keyring
// You can specify the Region or get the Region from the key ARN
var createMrkEncryptKeyringInput = new CreateAwsKmsMrkKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USEast1),
    KmsKeyId = mrkUSEast1
};
var mrkEncryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkEncryptKeyringInput);

// Define the encryption context
var encryptionContext = new Dictionary<string, string>()
{
    {"purpose", "test"}
};

// Encrypt your plaintext data.
var encryptInput = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = mrkEncryptKeyring,
    EncryptionContext = encryptionContext
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);

AWS Encryption CLI

此範例會加密 us-east-1 區域中多重區域金鑰下的hello.txt檔案。由於此範例會指定ARN具有 Region 元素的索引鍵，因此此範例不會使用該--wrapping-keys參數的 region 屬性。

當環繞金鑰的金鑰 ID 未指定 Region 時，您可以使用的區域屬性--wrapping-keys來指定區域，例如--wrapping-keys key=$keyID region=us-east-1。


# Encrypt with a multi-Region KMS key in us-east-1 Region

# To run this example, replace the fictitious key ARN with a valid value.
$ mrkUSEast1=arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab

$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$mrkUSEast1 \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --output .

Java

若要使用多區域金鑰加密，請具現化AwsKmsMrkAwareMasterKeyProvider並指定多區域金鑰。

如需完整範例，請參閱BasicMultiRegionKeyEncryptionExample.java的適用於 JAVA 的 AWS Encryption SDK 存放庫中的 GitHub。


//Encrypt with a multi-Region KMS key in us-east-1 Region

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .build();

// Multi-Region keys have a distinctive key ID that begins with 'mrk'
// Specify a multi-Region key in us-east-1
final String mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Instantiate an AWS KMS master key provider in strict mode for multi-Region keys
// Configure it to encrypt with the multi-Region key in us-east-1
final AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider
    .builder()
    .buildStrict(mrkUSEast1);

// Create an encryption context
final Map<String, String> encryptionContext = Collections.singletonMap("Purpose", "Test");

// Encrypt your plaintext data
final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> encryptResult = crypto.encryptData(
    kmsMrkProvider,
    encryptionContext,
    sourcePlaintext);
byte[] ciphertext = encryptResult.getResult();

JavaScript Browser

若要使用多區域金鑰加密，請使用該buildAwsKmsMrkAwareStrictMultiKeyringBrowser()方法建立金鑰環並指定多區域金鑰。

如需完整範例，請參閱上的儲存庫中的。適用於 JavaScript 的 AWS Encryption SDK GitHub


/* Encrypt with a multi-Region KMS key in us-east-1 Region */

import {
  buildAwsKmsMrkAwareStrictMultiKeyringBrowser,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-browser'


/* Instantiate an AWS Encryption SDK client */
const { encrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}

/* Instantiate an AWS KMS client 
 * The 適用於 JavaScript 的 AWS Encryption SDK gets the Region from the key ARN
 */
const clientProvider = (region: string) => new KMS({ region, credentials })


/* Specify a multi-Region key in us-east-1 */
const multiRegionUsEastKey =
    'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Instantiate the keyring */
const encryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({
    generatorKeyId: multiRegionUsEastKey,
    clientProvider,
  })


/* Set the encryption context */
const context = {
    purpose: 'test',
  }

/* Test data to encrypt */
const cleartext = new Uint8Array([1, 2, 3, 4, 5])

/* Encrypt the data */
const { result } = await encrypt(encryptKeyring, cleartext, {
    encryptionContext: context,
  })

JavaScript Node.js

若要使用多區域金鑰加密，請使用該buildAwsKmsMrkAwareStrictMultiKeyringNode()方法建立金鑰環並指定多區域金鑰。

如需完整範例，請參閱上的儲存庫中的。適用於 JavaScript 的 AWS Encryption SDK GitHub


//Encrypt with a multi-Region KMS key in us-east-1 Region

import { buildClient } from '@aws-crypto/client-node'

/* Instantiate the AWS Encryption SDK client
const { encrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

/* Test string to encrypt */
const cleartext = 'asdf'

/* Multi-Region keys have a distinctive key ID that begins with 'mrk'
 * Specify a multi-Region key in us-east-1
 */
const multiRegionUsEastKey =
    'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Create an AWS KMS keyring */
const mrkEncryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({
    generatorKeyId: multiRegionUsEastKey,
  })

/* Specify an encryption context */
const context = {
    purpose: 'test',
  }

/* Create an encryption keyring */
const { result } = await encrypt(mrkEncryptKeyring, cleartext, {
    encryptionContext: context,
  })

Python

若要使用 AWS KMS 多區域金鑰加密，請使用方MRKAwareStrictAwsKmsMasterKeyProvider()法並指定多區域金鑰。

如需完整範例，請參閱的適用於 Python 的 AWS Encryption SDK 存放庫中的 mrk_aware_kms_provider.py GitHub。


* Encrypt with a multi-Region KMS key in us-east-1 Region

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)

# Specify a multi-Region key in us-east-1
mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"

# Use the multi-Region method to create the master key provider
# in strict mode
strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider(
        key_ids=[mrk_us_east_1]
)

# Set the encryption context
encryption_context = {
        "purpose": "test"
    }

# Encrypt your plaintext data
ciphertext, encrypt_header = client.encrypt(
        source=source_plaintext,
        encryption_context=encryption_context,
        key_provider=strict_mrk_key_provider
)

接下來，將您的密文移到「us-west-2地區」。您不需要重新加密密文本。

若要在 [區域] 中以嚴格模式解密密文，請使用 [us-west-2區域] 中相關的多區域金鑰ARN的金鑰來實體化多區域感知符號。us-west-2如果您在不同的區域 (包括us-east-1加密的地區) 中指定相關的多區域金鑰的金鑰，則多區域感知符號會針對此進行跨區域呼叫。ARN AWS KMS key

在嚴謹模式下解密時，多區域感知符號需要金鑰。ARN它只接受ARN來自每組相關的多區域鍵的一個鍵。

在執行這些範例之前，請先將範例多區域鍵ARN取代為您 AWS 帳戶的.

C

若要使用多區域金鑰在嚴謹模式中解密，請使用方Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder()法來實體化金鑰環。在本機 (us-west-2) 區域中指定相關的多區域金鑰。

如需完整範例，請參閱的適用於 C 的 AWS Encryption SDK 存放庫中的 kms_multi_region_keys.cpp GitHub。


/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Initialize a multi-Region keyring */
const char *mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";    

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_west_2);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring);

aws_cryptosdk_session_set_commitment_policy(session,
    COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT);

aws_cryptosdk_keyring_release(mrk_keyring);

/* Decrypt the ciphertext 
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);

C# / .NET

若要在嚴謹模式中使用單一多區域金鑰進行解密，請使用您用來組合輸入並建立金鑰環以進行加密的相同建構函式和方法。使用相關多區域金鑰ARN的金鑰和美國西部 (奧勒岡) (us-west-2) 區域的 AWS KMS 用戶端來實體化CreateAwsKmsMrkKeyringInput物件。然後使用該CreateAwsKmsMrkKeyring()方法建立具有一個多區域金鑰的多區域金鑰圈。KMS

如需完整範例，請參閱中的 AwsKmsMrkKeyringExample AWS Encryption SDK .cs。 NET儲存庫於 GitHub。


// Decrypt with a related multi-Region KMS key in us-west-2 Region

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

// Specify the key ARN of the multi-Region key in us-west-2
string mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Instantiate the keyring input
// You can specify the Region or get the Region from the key ARN
var createMrkDecryptKeyringInput = new CreateAwsKmsMrkKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    KmsKeyId = mrkUSWest2
};

// Create the multi-Region keyring        
var mrkDecryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkDecryptKeyringInput);

// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = mrkDecryptKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);

AWS Encryption CLI

若要使用 us-west-2 區域中的相關多區域金鑰進行解密，請使用--wrapping-keys參數的 key 屬性來指定其金鑰。ARN


# Decrypt with a related multi-Region KMS key in us-west-2 Region

# To run this example, replace the fictitious key ARN with a valid value.
$ mrkUSWest2=arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys key=$mrkUSWest2 \
                     --commitment-policy require-encrypt-require-decrypt \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .

Java

若要以嚴格模式解密，請在本機 (us-west-2) 區域中實例化AwsKmsMrkAwareMasterKeyProvider並指定相關的多區域金鑰。

如需完整範例，請參閱的適用於 JAVA 的 AWS Encryption SDK 存放庫中的 BasicMultiRegionKeyEncryptionExample.java。 GitHub


// Decrypt with a related multi-Region KMS key in us-west-2 Region

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .build();

// Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field.
String mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Use the multi-Region method to create the master key provider
// in strict mode
AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider.builder()
    .buildStrict(mrkUSWest2);

// Decrypt your ciphertext
CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto.decryptData(
        kmsMrkProvider,
        ciphertext);
byte[] decrypted = decryptResult.getResult();

JavaScript Browser

若要以嚴格模式解密，請使用buildAwsKmsMrkAwareStrictMultiKeyringBrowser()方法建立金鑰環，並在本機 (us-west-2) 區域中指定相關的多區域金鑰。

如需完整範例，請參閱上的儲存庫中的。適用於 JavaScript 的 AWS Encryption SDK GitHub


/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

import {
  buildAwsKmsMrkAwareStrictMultiKeyringBrowser,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-browser'


/* Instantiate an AWS Encryption SDK client */
const { decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}

/* Instantiate an AWS KMS client 
 * The 適用於 JavaScript 的 AWS Encryption SDK gets the Region from the key ARN
 */
const clientProvider = (region: string) => new KMS({ region, credentials })


/* Specify a multi-Region key in us-west-2 */
const multiRegionUsWestKey =
    'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Instantiate the keyring */
const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({
    generatorKeyId: multiRegionUsWestKey,
    clientProvider,
  })


/* Decrypt the data */
const { plaintext, messageHeader } = await decrypt(mrkDecryptKeyring, result)

JavaScript Node.js

若要以嚴格模式解密，請使用buildAwsKmsMrkAwareStrictMultiKeyringNode()方法建立金鑰環，並在本機 (us-west-2) 區域中指定相關的多區域金鑰。

如需完整範例，請參閱上的儲存庫中的。適用於 JavaScript 的 AWS Encryption SDK GitHub


/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

import { buildClient } from '@aws-crypto/client-node'

/* Instantiate the client
const { decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

/* Multi-Region keys have a distinctive key ID that begins with 'mrk'
 * Specify a multi-Region key in us-east-1
 */
const multiRegionUsWestKey =
    'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Create an AWS KMS keyring */
const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({
    generatorKeyId: multiRegionUsWestKey,
  })

/* Decrypt your ciphertext */
const { plaintext, messageHeader } = await decrypt(decryptKeyring, result)

Python

若要在嚴謹模式中解密，請使用此MRKAwareStrictAwsKmsMasterKeyProvider()方法建立主要金鑰提供者。在本機 (us-west-2) 區域中指定相關的多區域金鑰。

如需完整範例，請參閱的適用於 Python 的 AWS Encryption SDK 存放庫中的 mrk_aware_kms_provider.py GitHub。


# Decrypt with a related multi-Region KMS key in us-west-2 Region

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)

# Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field
mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"

# Use the multi-Region method to create the master key provider
# in strict mode
strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider(
        key_ids=[mrk_us_west_2]
)

# Decrypt your ciphertext
plaintext, _ = client.decrypt(
        source=ciphertext, 
        key_provider=strict_mrk_key_provider
)

您也可以使用 AWS KMS 多區域金鑰在探索模式下解密。在探索模式下解密時，您不會指定任何 AWS KMS keys。(如需有關單一區域 AWS KMS 探索金鑰圈的資訊，請參閱使用 AWS KMS 探索鑰匙圈。)

如果您使用多區域金鑰加密，則探索模式下的多區域感知符號會嘗試使用本機區域中的相關多區域金鑰進行解密。如果不存在，則呼叫失敗。在探索模式中，不 AWS Encryption SDK 會嘗試跨區域呼叫用於加密的多區域金鑰。

注意

如果您在探索模式中使用多區域感知符號來加密資料，則加密作業會失敗。

下列範例顯示如何在探索模式中使用多區域感知符號進行解密。因為您未指定 AWS KMS key，因此 AWS Encryption SDK 必須從不同的來源取得「區域」。如果可能，請明確指定本地區域。否則， AWS Encryption SDK 從以您的編程語言配置的區域中 AWS SDK獲取本地區域。

在執行這些範例之前，請將範例帳戶 ID 和多區域金鑰ARN取代為您 AWS 帳戶的.

C

若要使用多區域金鑰在探索模式中解密，請使用Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder()方法建立金鑰環，並使用建置探索篩選器的Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder()方法。若要指定本機區域，請定義一個ClientConfiguration並在 AWS KMS 用戶端中指定。

如需完整範例，請參閱的適用於 C 的 AWS Encryption SDK 存放庫中的 kms_multi_region_keys.cpp GitHub。


/* Decrypt in discovery mode with a multi-Region KMS key */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct a discovery filter for the account and partition. The
 *  filter is optional, but it's a best practice that we recommend.
 */
const char *account_id = "111122223333";
const char *partition = "aws";
const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter =
    Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build();

/* Create an AWS KMS client in the desired region. */
const char *region = "us-west-2";

Aws::Client::ClientConfiguration client_config;
client_config.region = region;
const std::shared_ptr<Aws::KMS::KMSClient> kms_client =
    Aws::MakeShared<Aws::KMS::KMSClient>("AWS_SAMPLE_CODE", client_config);

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder()
        .WithKmsClient(kms_client)
        .BuildDiscovery(region, discovery_filter);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_DECRYPT, mrk_keyring);

aws_cryptosdk_keyring_release(mrk_keyring);
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
/* Decrypt the ciphertext 
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);

C# / .NET

若要在的中建立多區域感知探索金鑰圈。 AWS Encryption SDK NET，實體化特定 AWS KMS 用戶端的CreateAwsKmsMrkDiscoveryKeyringInput物件，以及可選的探索篩選器 AWS 區域，將索KMS引鍵限制在特定 AWS 分割區和帳戶。然後使用輸入對象調用該CreateAwsKmsMrkDiscoveryKeyring()方法。如需完整範例，請參閱中的 AwsKmsMrkDiscoveryKeyringExample AWS Encryption SDK .cs。 NET儲存庫於 GitHub。

若要為多個金鑰環建立多個區域感知探索金鑰圈 AWS 區域，請使用該CreateAwsKmsMrkDiscoveryMultiKeyring()方法建立多重金鑰環，或使用建立多個多區域感知探索金鑰環，然後使用該方法CreateAwsKmsMrkDiscoveryKeyring()將它們組合成多重金鑰圈。CreateMultiKeyring()

如需範例，請參閱 AwsKmsMrkDiscoveryMultiKeyringExample.cs。


// Decrypt in discovery mode with a multi-Region KMS key

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

List<string> account = new List<string> { "111122223333" };

// Instantiate the discovery filter
DiscoveryFilter mrkDiscoveryFilter = new DiscoveryFilter()
{
    AccountIds = account,
    Partition = "aws"
}

// Create the keyring
var createMrkDiscoveryKeyringInput = new CreateAwsKmsMrkDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    DiscoveryFilter = mrkDiscoveryFilter
};
var mrkDiscoveryKeyring = materialProviders.CreateAwsKmsMrkDiscoveryKeyring(createMrkDiscoveryKeyringInput);


// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = mrkDiscoveryKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);

AWS Encryption CLI

若要在探索模式下解密，請使用--wrapping-keys參數的探索屬性。探索帳戶和探索分割區屬性會建立選用的探索篩選器，但建議使用。

若要指定「區域」(Region)，此指令會包含--wrapping-keys參數的區域屬性。


# Decrypt in discovery mode with a multi-Region KMS key

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys discovery=true \ 
                                     discovery-account=111122223333 \
                                     discovery-partition=aws \
                                     region=us-west-2 \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .

Java

若要指定本機區域，請使用builder().withDiscoveryMrkRegion參數。否則， AWS Encryption SDK 會從中設定的區域取得本機區域AWS SDK for Java。

如需完整範例，請參閱的適用於 JAVA 的 AWS Encryption SDK 存放庫中的 DiscoveryMultiRegionDecryptionExample.java。 GitHub


// Decrypt in discovery mode with a multi-Region KMS key

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .build();
                
DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);

AwsKmsMrkAwareMasterKeyProvider mrkDiscoveryProvider = AwsKmsMrkAwareMasterKeyProvider
    .builder()
    .withDiscoveryMrkRegion(Region.US_WEST_2)
    .buildDiscovery(discoveryFilter);

// Decrypt your ciphertext
final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto
    .decryptData(mrkDiscoveryProvider, ciphertext);

JavaScript Browser

若要在探索模式中使用對稱的多區域金鑰進行解密，請使用此方AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser()法。

如需完整範例，請參閱上的儲存庫中的。適用於 JavaScript 的 AWS Encryption SDK GitHub


/* Decrypt in discovery mode with a multi-Region KMS key */

import {
  AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-browser'


/* Instantiate an AWS Encryption SDK client */
const { decrypt } = buildClient()

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}

/* Instantiate the KMS client with an explicit Region */
const client = new KMS({ region: 'us-west-2', credentials })


/* Create a discovery filter */
const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] }


/* Create an AWS KMS discovery keyring */
const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser({
    client,
    discoveryFilter,
  })


/* Decrypt the data */
const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, ciphertext)

JavaScript Node.js

若要在探索模式中使用對稱的多區域金鑰進行解密，請使用此方AwsKmsMrkAwareSymmetricDiscoveryKeyringNode()法。

如需完整範例，請參閱上的儲存庫中的。適用於 JavaScript 的 AWS Encryption SDK GitHub


/* Decrypt in discovery mode with a multi-Region KMS key */

import {
  AwsKmsMrkAwareSymmetricDiscoveryKeyringNode,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-node'

/* Instantiate the Encryption SDK client
const { decrypt } = buildClient()

/* Instantiate the KMS client with an explicit Region */
const client = new KMS({ region: 'us-west-2' })

/* Create a discovery filter */
const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] }

/* Create an AWS KMS discovery keyring */
const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringNode({
    client,
    discoveryFilter,
  })

/* Decrypt your ciphertext */
const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, result)

Python

若要在探索模式中使用多區域金鑰進行解密，請使用此方MRKAwareDiscoveryAwsKmsMasterKeyProvider()法。

如需完整範例，請參閱的適用於 Python 的 AWS Encryption SDK 存放庫中的 mrk_aware_kms_provider.py GitHub。


# Decrypt in discovery mode with a multi-Region KMS key

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient()

# Create the discovery filter and specify the region
decrypt_kwargs = dict(
        discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"),
        discovery_region="us-west-2",
    )

# Use the multi-Region method to create the master key provider
# in discovery mode
mrk_discovery_key_provider = MRKAwareDiscoveryAwsKmsMasterKeyProvider(**decrypt_kwargs)

# Decrypt your ciphertext
plaintext, _ = client.decrypt(
        source=ciphertext, 
        key_provider=mrk_discovery_key_provider
)

選擇演算法套件

AWS Encryption SDK 支援數種對稱和非對稱加密演算法，可在您指定的包裝金鑰下加密您的資料金鑰。但是，當它使用這些資料金鑰來加密您的資料時， AWS Encryption SDK 預設會使用建議的演算法套件，該演算法使用具有金鑰衍生、數位簽章和金鑰承諾的 AES-GCM 演算法。雖然預設演算法套件可能適用於大多數應用程式，但您可以選擇替代演算法套件。例如，某些信任模型會由沒有數位簽章的演算法套件來滿足。如需 AWS Encryption SDK 支援之演算法套件的相關資訊，請參閱AWS Encryption SDK中的支援演算法套件。

下列範例說明如何在加密時選取替代演算法套件。這些範例會選取建議AES的GCM演算法套件，其中包含金鑰衍生和金鑰承諾，但沒有數位簽章。使用不包含數位簽章的演算法套件進行加密時，請在解密時使用僅限未簽章的解密模式。此模式在遇到已簽署的加密文字時失敗，在串流解密時最有用。

C

若要在中指定替代演算法套件適用於 C 的 AWS Encryption SDK，您必須CMM明確建立。然後使用aws_cryptosdk_default_cmm_set_alg_id與CMM和選取的演算法套件。


/* Specify an algorithm suite without signing */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);

/* To set an alternate algorithm suite, create an cryptographic 
   materials manager (CMM) explicitly
 */
struct aws_cryptosdk_cmm *cmm = aws_cryptosdk_default_cmm_new(aws_default_allocator(), kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring); 

/* Specify the algorithm suite for the CMM */
aws_cryptosdk_default_cmm_set_alg_id(cmm, ALG_AES256_GCM_HKDF_SHA512_COMMIT_KEY);
    
/* Construct the session with the CMM, 
   then release the CMM reference 
 */
struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(alloc, AWS_CRYPTOSDK_ENCRYPT, cmm);
aws_cryptosdk_cmm_release(cmm);

/* Encrypt the data 
   Use aws_cryptosdk_session_process_full with non-streaming data
 */
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(
                          session, 
                          ciphertext, 
                          ciphertext_buf_sz, 
                          &ciphertext_len, 
                          plaintext, 
                          plaintext_len)) {
    aws_cryptosdk_session_destroy(session);
    return AWS_OP_ERR;
}

解密未經數位簽章加密的資料時，請使用AWS_CRYPTOSDK_DECRYPT_UNSIGNED。如果遇到簽名的密文，這會導致解密失敗。


/* Decrypt unsigned streaming data */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
    
/* Create a session for decrypting with the AWS KMS keyring
   Then release the keyring reference
 */
struct aws_cryptosdk_session *session =
        aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT_UNSIGNED, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring); 
   
if (!session) {
    return AWS_OP_ERR;
}
    
/* Limit encrypted data keys */
aws_cryptosdk_session_set_max_encrypted_data_keys(session, 1);
  
/* Decrypt 
   Use aws_cryptosdk_session_process_full with non-streaming data
 */
    if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(
                          session,                          
                          plaintext,
                          plaintext_buf_sz,
                          &plaintext_len,
                          ciphertext,
                          ciphertext_len)) {
    aws_cryptosdk_session_destroy(session);
    return AWS_OP_ERR;
}

C# / .NET

若要在中指定替代演算法套 AWS Encryption SDK 件。 NET」中，指定EncryptInput物件的AlgorithmSuiteId性質。 AWS Encryption SDK 的。 NET包含可用來識別偏好演算法套件的常數。

AWS Encryption SDK 的。 NET在流解密時沒有檢測簽名密文的方法，因為此庫不支持流數據。


// Specify an algorithm suite without signing

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

// Create the keyring
var keyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};
var keyring = materialProviders.CreateAwsKmsKeyring(keyringInput);

// Encrypt your plaintext data
var encryptInput = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = keyring,
    AlgorithmSuiteId = AlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);

AWS Encryption CLI

加密hello.txt檔案時，此範例會使用--algorithm參數來指定不含數位簽章的演算法套件。


# Specify an algorithm suite without signing

# To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$keyArn \
                     --algorithm AES_256_GCM_HKDF_SHA512_COMMIT_KEY \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --commitment-policy require-encrypt-require-decrypt \
                     --output hello.txt.encrypted \
                     --decode

解密時，此範例會使用--decrypt-unsigned參數。建議您使用此參數來確保您正在解密未簽署的密文，尤其是使用永遠是串流輸入和輸出的。CLI


# Decrypt unsigned streaming data

# To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

$ aws-encryption-cli --decrypt-unsigned \
                     --input hello.txt.encrypted \
                     --wrapping-keys key=$keyArn \
                     --max-encrypted-data-keys 1 \
                     --commitment-policy require-encrypt-require-decrypt \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --output .

Java

若要指定替代演算法套件，請使用此AwsCrypto.builder().withEncryptionAlgorithm()方法。此範例指定不含數位簽章的替代演算法套件。


// Specify an algorithm suite without signing

// Instantiate the client
AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY)
    .build();

String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a master key provider in strict mode
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
    .buildStrict(awsKmsKey);
    
// Create an encryption context to identify this ciphertext
        Map<String, String> encryptionContext = Collections.singletonMap("Example", "FileStreaming");

// Encrypt your plaintext data
CryptoResult<byte[], KmsMasterKey> encryptResult = crypto.encryptData(
    masterKeyProvider,
    sourcePlaintext,
    encryptionContext);
byte[] ciphertext = encryptResult.getResult();

當串流資料進行解密時，請使用此createUnsignedMessageDecryptingStream()方法來確保您要解密的所有密文都是未簽署的。


// Decrypt unsigned streaming data

// Instantiate the client
AwsCrypto crypto = AwsCrypto.builder()
  .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
  .withMaxEncryptedDataKeys(1)
  .build();

// Create a master key provider in strict mode
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
  .buildStrict(awsKmsKey);

// Decrypt the encrypted message
FileInputStream in = new FileInputStream(srcFile + ".encrypted");  
CryptoInputStream<KmsMasterKey> decryptingStream = crypto.createUnsignedMessageDecryptingStream(masterKeyProvider, in);
  
// Return the plaintext data
// Write the plaintext data to disk
FileOutputStream out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();

JavaScript Browser

若要指定替代演算法套件，請使用具有AlgorithmSuiteIdentifier枚舉值的suiteId參數。


// Specify an algorithm suite without signing

// Instantiate the client 
const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Specify a KMS key 
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a keyring with the KMS key
const keyring = new KmsKeyringBrowser({ generatorKeyId })

// Encrypt your plaintext data 
const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })

解密時，請使用標準decrypt方法。適用於 JavaScript 的 AWS Encryption SDK 在瀏覽器中沒有decrypt-unsigned模式，因為瀏覽器不支持流媒體。


// Decrypt unsigned streaming data

// Instantiate the client 
const { decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Create a keyring with the same KMS key used to encrypt
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; 
const keyring = new KmsKeyringBrowser({ generatorKeyId })

// Decrypt the encrypted message 
const { plaintext, messageHeader } = await decrypt(keyring, ciphertextMessage)

JavaScript Node.js

若要指定替代演算法套件，請使用具有AlgorithmSuiteIdentifier枚舉值的suiteId參數。


// Specify an algorithm suite without signing

// Instantiate the client 
const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Specify a KMS key
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a keyring with the KMS key
const keyring = new KmsKeyringNode({ generatorKeyId })

// Encrypt your plaintext data 
const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })

解密沒有數位簽章的加密資料時，請使用「 decryptUnsignedMessage串流」。如果遇到簽名密文此方法失敗。


// Decrypt unsigned streaming data

// Instantiate the client 
const { decryptUnsignedMessageStream } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Create a keyring with the same KMS key used to encrypt
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; 
const keyring = new KmsKeyringNode({ generatorKeyId })

// Decrypt the encrypted message 
const outputStream = createReadStream(filename) .pipe(decryptUnsignedMessageStream(keyring))

Python

若要指定替代加密演算法，請使用具有Algorithm枚舉值的algorithm參數。


# Specify an algorithm suite without signing

# Instantiate a client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
                                                max_encrypted_data_keys=1)

# Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
        key_ids=[aws_kms_key]
)

# Encrypt the plaintext using an alternate algorithm suite
ciphertext, encrypted_message_header = client.encrypt(
    algorithm=Algorithm.AES_256_GCM_HKDF_SHA512_COMMIT_KEY, source=source_plaintext, key_provider=kms_key_provider
)

解密沒有數位簽章的加密郵件時，請使用decrypt-unsigned串流模式，尤其是在串流時進行解密時。


# Decrypt unsigned streaming data

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
                                                max_encrypted_data_keys=1)

# Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
        key_ids=[aws_kms_key]
)

# Decrypt with decrypt-unsigned
with open(ciphertext_filename, "rb") as ciphertext, open(cycled_plaintext_filename, "wb") as plaintext:
    with client.stream(mode="decrypt-unsigned", 
                       source=ciphertext, 
                       key_provider=master_key_provider) as decryptor:
        for chunk in decryptor:
            plaintext.write(chunk)

# Verify that the encryption context
assert all(
   pair in decryptor.header.encryption_context.items() for pair in encryptor.header.encryption_context.items()
)
return ciphertext_filename, cycled_plaintext_filename

限制加密的資料金鑰

您可以限制加密訊息中加密資料金鑰的數量。此最佳作法功能可協助您在加密時偵測設定錯誤的金鑰環，或在解密時偵測惡意密文。它還可以防止對您的關鍵基礎結構進行不必要、昂貴且可能詳盡的呼叫。當您解密來自不受信任來源的郵件時，限制加密的資料金鑰是最有價值的。

雖然大多數加密郵件對於加密中使用的每個包裝金鑰都有一個加密資料金鑰，但加密訊息最多可包含 65,535 個加密資料金鑰。惡意執行者可能會建構含有數千個加密資料金鑰的加密訊息，而這些金鑰都無法解密。因此， AWS Encryption SDK 會嘗試解密每個加密的資料金鑰，直到用盡訊息中的加密資料金鑰為止。

若要限制加密的資料金鑰，請使用MaxEncryptedDataKeys參數。此參數適用於從 1.9 版開始的所有受支援的程式設計語言。 X 和 2.2. 的 x 的 AWS Encryption SDK。它是可選的，在加密和解密時有效。下列範例會解密使用三個不同包裝金鑰加密的資料。該MaxEncryptedDataKeys值設定為 3。

C


/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = 
      Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn1, { key_arn2, key_arn3 });

/* Create a session */
struct aws_cryptosdk_session *session = 
    aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);

/* Limit encrypted data keys */
aws_cryptosdk_session_set_max_encrypted_data_keys(session, 3);
  
/* Decrypt */
size_t ciphertext_consumed_output;
aws_cryptosdk_session_process(session,
    plaintext_output,
    plaintext_buf_sz_output,
    &plaintext_len_output,
    ciphertext_input,
    ciphertext_len_input,
    &ciphertext_consumed_output);
assert(aws_cryptosdk_session_is_done(session));
assert(ciphertext_consumed == ciphertext_len);

C# / .NET

若要限制中的 AWS Encryption SDK 加密資料金鑰。 NET，實例化的 AWS Encryption SDK 用戶端。 NET並將其可選MaxEncryptedDataKeys參數設置為所需的值。然後，在配置的 AWS Encryption SDK 實例上調用該Decrypt()方法。


// Decrypt with limited data keys

// Instantiate the material providers
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
    MaxEncryptedDataKeys = 3
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);

// Create the keyring
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};
var decryptKeyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);

// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = decryptKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);

AWS Encryption CLI


# Decrypt with limited encrypted data keys

$ aws-encryption-cli --decrypt \
    --input hello.txt.encrypted \
    --wrapping-keys key=$key_arn1 key=$key_arn2 key=$key_arn3 \
    --buffer \
    --max-encrypted-data-keys 3 \
    --encryption-context purpose=test \
    --metadata-output ~/metadata \
    --output .

Java


// Construct a client with limited encrypted data keys
final AwsCrypto crypto = AwsCrypto.builder()
  .withMaxEncryptedDataKeys(3)
  .build();

// Create an AWS KMS master key provider
final KmsMasterKeyProvider keyProvider = KmsMasterKeyProvider.builder()
      .buildStrict(keyArn1, keyArn2, keyArn3);
   
// Decrypt
final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(keyProvider, ciphertext)

JavaScript Browser


// Construct a client with limited encrypted data keys
const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 })

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}
const clientProvider = getClient(KMS, {
  credentials: { accessKeyId, secretAccessKey, sessionToken }
})

// Create an AWS KMS keyring
const keyring = new KmsKeyringBrowser({
  clientProvider,
  keyIds: [keyArn1, keyArn2, keyArn3],
})

// Decrypt
const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)

JavaScript Node.js


// Construct a client with limited encrypted data keys
const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 })

// Create an AWS KMS keyring
const keyring = new KmsKeyringBrowser({
  keyIds: [keyArn1, keyArn2, keyArn3],
})
  
// Decrypt
const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)

Python


# Instantiate a client with limited encrypted data keys
client = aws_encryption_sdk.EncryptionSDKClient(max_encrypted_data_keys=3)

# Create an AWS KMS master key provider
master_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(
    key_ids=[key_arn1, key_arn2, key_arn3])

# Decrypt
plaintext, header = client.decrypt(source=ciphertext, key_provider=master_key_provider)

建立探索篩選器

解密使用KMS金鑰加密的資料時，最佳做法是在嚴謹模式下進行解密，也就是將使用的包裝金鑰限制為只有您指定的金鑰。不過，如有必要，您也可以在探索模式中解密，而您不需要指定任何包裝金鑰。在此模式下， AWS KMS 無論誰擁有或有權存取該KMS金鑰，都可以使用加密的金鑰來解密加密的資料KMS金鑰。

如果您必須在探索模式下解密，建議您一律使用探索篩選器，此篩選器會限制指定 AWS 帳戶和分割區中可使用的KMS金鑰。探索篩選器是選擇性的，但這是最佳作法。

使用下表決定探索篩選器的分割區值。

區域	分區
AWS 區域	`aws`
中國區域	`aws-cn`
AWS GovCloud (US) Regions	`aws-us-gov`

本節中的範例顯示如何建立探索篩選器。在使用程式碼之前，請先以 AWS 帳戶和分割區的有效值取代範例值。

C

如需完整範例，請參閱中的 kms_discovery.cpp 適用於 C 的 AWS Encryption SDK。


/* Create a discovery filter for an AWS account and partition */
    
const char *account_id = "111122223333";
const char *partition = "aws";
const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter =
    Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build();

C# / .NET

如需完整範例，請參閱中的 DiscoveryFilterExample AWS Encryption SDK .cs。 NET。


// Create a discovery filter for an AWS account and partition

List<string> account = new List<string> { "111122223333" };

DiscoveryFilter exampleDiscoveryFilter = new DiscoveryFilter()
{
    AccountIds = account,
    Partition = "aws"
}

AWS Encryption CLI


# Decrypt in discovery mode with a discovery filter

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys discovery=true \ 
                                     discovery-account=111122223333 \
                                     discovery-partition=aws \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .

Java

如需完整範例，請參閱中的 DiscoveryDecryptionExample 適用於 JAVA 的 AWS Encryption SDK.java。


// Create a discovery filter for an AWS account and partition

DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);

JavaScript (Node and Browser)

如需完整範例，請參閱中的. 適用於 JavaScript 的 AWS Encryption SDK Node.js


/* Create a discovery filter for an AWS account and partition */
const discoveryFilter = { 
  accountIDs: ['111122223333'], 
  partition: 'aws',
}

Python

如需完整範例，請參閱中的 discovery_kms_provider.py 適用於 Python 的 AWS Encryption SDK。


# Create the discovery filter and specify the region
decrypt_kwargs = dict(
        discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"),
        discovery_region="us-west-2",
    )

設定承諾產品原則

承諾產品原則是一種組態設定，可決定您的應用程式是否使用金鑰承諾進行加密和解密。使用關鍵承諾進行加密和解密是AWS Encryption SDK 最佳實務。

設定及調整承諾產品原則是從 1.7 版移轉的重要步驟。 AWS Encryption SDK 到 2.0 版本的 x 及更早版本。 x 及更新版本。移轉主題中會詳細說明此進度。

最新版本 (從 2.0 版開始 AWS Encryption SDK ) 中的預設承諾產品原則值。 x),RequireEncryptRequireDecrypt, 是大多數情況下的理想選擇。不過，如果您需要解密在沒有金鑰承諾的情況下加密的加密文字，您可能需要將承諾原則變更為。RequireEncryptAllowDecrypt如需如何在每種程式設計語言中設定承諾產品原則的範例，請參閱設定承諾產品原則。

使用串流資料

當您串流資料進行解密時，請注意在完整性檢查完成後，但在驗證數位簽章之前， AWS Encryption SDK 傳回解密的純文字。為了確保您在簽章驗證之前不會傳回或使用純文字，建議您緩衝串流的純文字，直到整個解密程序完成為止。

只有當您要串流加密文字進行解密，並且只有在使用包含數位簽章的演算法套件 (例如預設演算法套件) 時，才會出現此問題。

為了使緩衝更容易，某些 AWS Encryption SDK 語言實現（例如適用於 JavaScript 的 AWS Encryption SDK 在 Node.js 中）包含緩衝功能作為解密方法的一部分。加 AWS 密CLI，總是流輸入和輸出在版本 1.9 中引入了一個--buffer參數。 X 和 2.2. x. 在其他語言實作中，您可以使用現有的緩衝功能。( AWS Encryption SDK 的. NET不支援串流。)

如果您使用的演算法套件不含數位簽章，請務必在每種語言實作中使用decrypt-unsigned此功能。此功能會解密密文，但如果遇到簽署的密文，就會失敗。如需詳細資訊，請參閱選擇演算法套件。

快取資料金鑰

一般而言，不鼓勵重複使用資料金鑰，但提供資料金鑰快取選項，可提供有限的資料金鑰重複使用。 AWS Encryption SDK 資料金鑰快取可以改善某些應用程式的效能，並減少對金鑰基礎結構的呼叫。在生產環境中使用資料金鑰快取之前，請先調整安全性閾值，並進行測試，以確保其優點超過重複使用資料金鑰的缺點。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

最佳實務

使用 keyring