AWS KMS 鑰匙圈

我們的客戶端加密庫被重命名為 AWS 數據庫加密 SDK。本開發人員指南仍提供 DynamoDB 加密用戶端的相關資訊。

AWS KMS 金鑰圈使用對稱加密或非對稱 RSA AWS KMS keys來產生、加密和解密資料金鑰。 AWS Key Management Service (AWS KMS) 保護您的 KMS 金鑰，並在 FIPS 界限內執行密碼編譯作業。我們建議您盡可能使用 AWS KMS 金鑰圈或具有類似安全性屬性的鑰匙圈。

您也可以在金鑰圈中使用對稱的多區域 KMS 金鑰。 AWS KMS 如需使用多區域的詳細資訊和範例 AWS KMS keys，請參閱使用多地區 AWS KMS keys。如需有關多區域金鑰的詳細資訊，請參閱AWS Key Management Service 開發人員指南中的使用多區域金鑰。

AWS KMS 鑰匙圈可以包含兩種類型的環繞鍵：

• 產生器金鑰：產生純文字資料金鑰並加密。加密資料的金鑰環必須有一個產生器金鑰。

• 其他金鑰：加密產生器金鑰所產生的純文字資料金鑰。 AWS KMS 鑰匙圈可以有零個或多個其他金鑰。

您必須具有生成器密鑰才能加密記錄。當金 AWS KMS 鑰圈只有一個 AWS KMS 金鑰時，就會使用該金鑰來產生和加密資料金鑰。

與所有鑰匙圈一樣， AWS KMS 鑰匙圈可以單獨使用，也可以與其他相同或不同類型的鑰匙圈一起使用。

AWS KMS 金鑰圈所需的權限

數 AWS 據庫加密 SDK 不需要 AWS 帳戶 ，它不依賴於任何 AWS 服務. 但是，若要使用 AWS KMS 金鑰圈，您需要在 AWS 帳戶 金鑰圈 AWS KMS keys 中具有以下最低權限。

• 要使用密 AWS KMS 鑰環進行加密，您需要 kms：對生成器密鑰的GenerateDataKey權限。您需要 KMS: 加密金鑰環中所有其他金鑰的權限。 AWS KMS

• 若要使用金 AWS KMS 鑰圈進行解密，您需要 KMS: 在金鑰環中至少有一個金鑰的 Decryp t 權限。 AWS KMS

• 要使用由密鑰環組成的多密 AWS KMS 鑰環進行加密，您需要 kms：對生成器密鑰環中的生成器密鑰的GenerateDataKey權限。您需要 KMS：對所有其他金鑰環中所有其他金鑰的加密權限。 AWS KMS

• 若要使用非對稱 RSA 金 AWS KMS 鑰圈加密，您不需要 kms: GenerateDataKey 或 KMS: Encrypt，因為您必須在建立金鑰環時指定要用於加密的公開金鑰材料。使用此金鑰圈加密時，不會進行任何 AWS KMS 呼叫。若要使用非對稱 RSA AWS KMS 金鑰圈進行解密，您需要 K MS: 解密權限。

如需有關權限的詳細資訊 AWS KMS keys，請參閱AWS Key Management Service 開發人員指南中的驗證和存取控制。

在 AWS KMS 鑰匙圈 AWS KMS keys 中識別

一個 AWS KMS 鑰匙圈可以包括一個或多 AWS KMS keys個。若要在金 AWS KMS 鑰環 AWS KMS key 中指定，請使用支援的 AWS KMS 金鑰識別碼。您可以用來識別金鑰圈 AWS KMS key 中的金鑰識別碼會隨作業和語言實作而有所不同。有關的密鑰標識符的詳細信息 AWS KMS key，請參閱AWS Key Management Service 開發人員指南中的密鑰標識符。

最佳做法是使用適合您工作的最特定金鑰識別碼。

• 若要使用金 AWS KMS 鑰圈加密，您可以使用金鑰識別碼、金鑰 ARN、別名或別名 ARN 來加密資料。

  注意

  如果您在加密金鑰圈中為 KMS 金鑰指定別名或別名 ARN，則加密作業會將目前與別名關聯的金鑰 ARN 儲存在加密資料金鑰的中繼資料中。它不會儲存別名。變更別名不會影響用於解密加密資料金鑰的 KMS 金鑰。

• 若要使用金 AWS KMS 鑰圈進行解密，您必須使用金鑰 ARN 來識別。 AWS KMS keys如需詳細資訊，請參閱 選擇包裝鍵。

• 在用於加密和解密的 keyring 中，您必須使用金鑰 ARN 來識別 AWS KMS keys。

解密時，資料 AWS 庫加密 SDK 會在 AWS KMS 金鑰環中搜尋可以解密其中一個加密資料金鑰的金鑰。 AWS KMS key 具體而言，資料 AWS 庫加密 SDK 會針對材料描述中的每個加密資料金鑰使用下列模式。

• 數據 AWS 庫加密 SDK 從材料描述的元數據中 AWS KMS key 獲取加密數據密鑰的密鑰 ARN。

• 資 AWS 料庫加密 SDK 會在解密金鑰環中搜尋 AWS KMS key 具有相符金鑰 ARN 的。

• 如果在金鑰環中找到 AWS KMS key 具有相符金鑰 ARN 的金鑰，資料 AWS 庫加密 SDK 會 AWS KMS 要求使用 KMS 金鑰來解密加密的資料金鑰。

• 否則會跳到下一個加密的資料金鑰 (如果有)。

建立 AWS KMS 金鑰圈

您可以將每個 AWS KMS 鑰匙圈配置為一個 AWS KMS key 或多 AWS KMS keys 個相同或不同的 AWS 帳戶 和 AWS 區域。 AWS KMS key 必須是對稱加密金鑰 (SYMMETRIC_DEFAULT) 或非對稱 RSA KMS 金鑰。您也可以使用對稱加密多區域 KMS 金鑰。您可以在多重鑰匙圈中使用一或多個 AWS KMS 鑰匙圈。

您可以建立加密和解密資料的 AWS KMS 金鑰環，也可以建立專門用於加密或解密的 AWS KMS 金鑰環。當您建立金 AWS KMS 鑰環來加密資料時，您必須指定產生器金鑰， AWS KMS key 這是用來產生純文字資料金鑰並加密的產生器金鑰。資料金鑰在數學上與 KMS 金鑰無關。然後，如果您選擇，您可以指定其他加密 AWS KMS keys 相同的純文字資料金鑰。若要解密受此金鑰圈保護的加密欄位，您使用的解密金鑰圈必須至少包含金鑰圈中 AWS KMS keys 定義的其中一個，或者 no。 AWS KMS keys（沒有的 AWS KMS 鑰匙圈稱 AWS KMS keys 為AWS KMS 探索鑰匙圈。）

加密金鑰圈或多重金鑰環中的所有包裝金鑰都必須能夠加密資料金鑰。如果有任何包裝金鑰無法加密，則加密方法會失敗。因此，呼叫者必須擁有金鑰環中所有金鑰的必要權限。如果您單獨使用探索金鑰環加密資料，或在多重金鑰環中加密資料，則加密作業會失敗。

下列範例使用此方CreateAwsKmsMrkMultiKeyring法建立具有對稱加密 KMS 金 AWS KMS 鑰的金鑰環。此方CreateAwsKmsMrkMultiKeyring法會自動建立用 AWS KMS 戶端，並確保金鑰環能夠正確處理單一區域和多區域金鑰。這些範例使用金鑰 ARN 來識別 KMS 金鑰。如需詳細資訊，請參閱在 AWS KMS 鑰匙圈 AWS KMS keys 中識別

Java

final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
        .generator(kmsKeyArn)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);

C# / .NET

var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createAwsKmsMrkMultiKeyringInput = new CreateAwsKmsMrkMultiKeyringInput
{
    Generator = kmsKeyArn
};
var awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);

下列範例使用此方CreateAwsKmsRsaKeyring法建立具有非對稱 RSA KMS 金 AWS KMS 鑰的金鑰圈。若要建立非對稱的 RSA AWS KMS 金鑰圈，請提供下列值。

• kmsClient：建立新 AWS KMS 用戶端

• kmsKeyID：識別您非對稱 RSA KMS 金鑰的金鑰 ARN

• publicKey: 一個 UTF-8 編碼 ByteBuffer 的 PEM 檔案，代表您傳遞給的金鑰的公開金鑰 kmsKeyID

• encryptionAlgorithm：加密演算法必須是RSAES_OAEP_SHA_256或 RSAES_OAEP_SHA_1

Java

 final MaterialProviders matProv = MaterialProviders.builder()
    .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
    .build();
final CreateAwsKmsRsaKeyringInput createAwsKmsRsaKeyringInput =
    CreateAwsKmsRsaKeyringInput.builder()
        .kmsClient(KmsClient.create())
        .kmsKeyId(rsaKMSKeyArn)
        .publicKey(publicKey)
        .encryptionAlgorithm(EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256)
        .build();
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);

C# / .NET

var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createAwsKmsRsaKeyringInput = new CreateAwsKmsRsaKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = rsaKMSKeyArn,
    PublicKey = publicKey,
    EncryptionAlgorithm = EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256
};
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);

使用多地區 AWS KMS keys

您可以在 AWS 資料庫加密 SDK 中使用多區域 AWS KMS keys 作為包裝金鑰。如果您使用一個多區域金鑰加密 AWS 區域，則可以使用不同的相關多區域金鑰來解密。 AWS 區域

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

為了支援多區域金鑰， AWS 資料庫加密 SDK 包含 AWS KMS 多區域感知金鑰環。該CreateAwsKmsMrkMultiKeyring方法同時支持單區域和多區域鍵。

• 對於單一區域金鑰，多區域感知符號的行為與單一區域金鑰圈一樣。 AWS KMS 它只會嘗試使用加密資料的單一區域金鑰來解密密文。為了簡化金 AWS KMS 鑰圈體驗，我們建議您在使用對稱加密 KMS 金鑰時使用此CreateAwsKmsMrkMultiKeyring方法。

• 對於多區域金鑰，多區域感知符號會嘗試使用加密資料的相同多區域金鑰，或使用您指定之區域中的相關多區域金鑰來解密密文。

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

下列範例會建立具有多區域 KMS 金 AWS KMS 鑰的金鑰圈。範例指定多區域鍵做為產生器鍵，並指定單一區域鍵做為子關鍵字。

Java

final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsMrkMultiKeyringInput createAwsKmsMrkMultiKeyringInput =
    CreateAwsKmsMrkMultiKeyringInput.builder()
            .generator(multiRegionKeyArn)
            .kmsKeyIds(Collections.singletonList(kmsKeyArn))
            .build();
IKeyring awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);

C# / .NET

var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createAwsKmsMrkMultiKeyringInput = new CreateAwsKmsMrkMultiKeyringInput
{
    Generator = multiRegionKeyArn,
    KmsKeyIds = new List<String> { kmsKeyArn }
};
var awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);

使用多區域 AWS KMS 金鑰圈時，您可以在嚴謹模式或探索模式下解密密文。若要在嚴謹模式中解密密文，請在您要解密密文的區域中，使用相關多區域金鑰的金鑰 ARN 來實體化多區域感知符號。如果您在不同的區域中指定相關多區域金鑰的金鑰 ARN (例如，記錄已加密的區域)，則多區域感知符號會針對此進行跨區域呼叫。 AWS KMS key

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

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

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

使用 AWS KMS 探索鑰匙圈

解密時，最佳做法是指定 AWS 資料庫加密 SDK 可以使用的包裝金鑰。若要遵循此最佳作法，請使用 AWS KMS 解密金鑰圈，將 AWS KMS 包裝金鑰限制為您指定的金鑰。不過，您也可以建立AWS KMS 探索金鑰圈，也就是不會指定任何 AWS KMS 環繞金鑰的金鑰圈。

資 AWS 料庫加密 SDK 為 AWS KMS 多區域金鑰提供標準 AWS KMS 探索金鑰環和探索金鑰圈。如需將多區域金鑰搭配資 AWS 料庫加密 SDK 使用的詳細資訊，請參閱使用多地區 AWS KMS keys。

因為它不會指定任何包裝金鑰，因此探索金鑰環無法加密資料。如果您單獨使用探索金鑰環加密資料，或在多重金鑰環中加密資料，則加密作業會失敗。

解密時，探索金鑰圈允許 AWS Database Encryption SDK AWS KMS 要求使用 AWS KMS key 該加密資料金鑰來解密任何加密的資料金鑰，而不論誰擁有或具有存取權。 AWS KMS key只有當呼叫kms:Decrypt者具有. AWS KMS key

重要

如果您在解密多重金鑰環中包含 AWS KMS 探索金鑰圈，探索金鑰圈會覆寫多重金鑰圈中其他金鑰環指定的所有 KMS 金鑰限制。多重金鑰環的行為與其限制性最小的鑰匙圈一樣。如果您單獨使用探索金鑰圈加密資料，或在多重金鑰環中加密資料，則加密作業會失敗

為了方便起見， AWS 資料庫加密 SDK 提供 AWS KMS 探索金鑰環。不過，基於下列原因，建議您在可能時使用較具限制的 keyring。

• 真實性 — AWS KMS 探索金鑰圈可以使用任何 AWS KMS key 用來加密材料描述中的資料金鑰，只要呼叫者有權使用該金鑰 AWS KMS key 來解密該金鑰的權限。這可能不是呼 AWS KMS key 叫者打算使用的。例如，其中一個加密的資料金鑰可能以較不安全的方式加密 AWS KMS key ，任何人都可以使用。

• 延遲和效能 — AWS KMS 探索金鑰圈的速度可能會比其他金鑰環慢，因為 AWS Database Encryption SDK 會嘗試解密所有加密的資料金鑰，包括 AWS KMS keys 在其他 AWS 帳戶 和區域中加密的資料金鑰，而且 AWS KMS keys 呼叫者沒有用於解密的權限。

如果您使用探索金鑰圈，建議您使用探索篩選器來限制可用於指定 AWS 帳戶 和磁碟分割中的 KMS 金鑰。如需尋找帳戶 ID 和分割區的 AWS 帳戶 ARN 助，請參閱. AWS 一般參考

下列程式碼範例會使用 AWS KMS 探索篩選器來實體化探索金鑰環，該篩選器會限制 AWS Database Encryption SDK 可用於aws分割區和範111122223333例帳戶中的 KMS 金鑰。

在使用此代碼之前，請將示例 AWS 帳戶 和分區值替換為您的 AWS 帳戶 和分區的有效值。如果您的 KMS 金鑰位於中國區域，請使用aws-cn分割區值。如果您的 KMS 金鑰位於中 AWS GovCloud (US) Regions，請使用aws-us-gov分割區值。對於所有其他 AWS 區域，請使用aws分區值。

Java

// Create discovery filter
DiscoveryFilter discoveryFilter = DiscoveryFilter.builder()
        .partition("aws")
        .accountIds(111122223333)
        .build();
// Create the discovery keyring
CreateAwsKmsMrkDiscoveryMultiKeyringInput createAwsKmsMrkDiscoveryMultiKeyringInput = CreateAwsKmsMrkDiscoveryMultiKeyringInput.builder()
        .discoveryFilter(discoveryFilter)
        .build();
IKeyring decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);

C# / .NET

// Create discovery filter
var discoveryFilter = new DiscoveryFilter
{
    Partition = "aws",
    AccountIds = 111122223333
};
// Create the discovery keyring
var createAwsKmsMrkDiscoveryMultiKeyringInput = new CreateAwsKmsMrkDiscoveryMultiKeyringInput
{
    DiscoveryFilter = discoveryFilter
};
var decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);

使用 AWS KMS 區域探索金鑰圈

AWS KMS 區域探索金鑰圈是不會指定 KMS 金鑰 ARN 的金鑰圈。相反地，它允許 AWS 資料庫加密 SDK 僅使用 KMS 金鑰進行解密 AWS 區域。

使用 AWS KMS 區域探索金鑰圈進行解密時，資料 AWS 庫加密 SDK 會將 AWS KMS key 在指定的中加密的任何加密資料金鑰解密。 AWS 區域若要成功，呼叫者必須kms:Decrypt擁有至少一個加密資料金鑰 AWS 區域 的指定 AWS KMS keys 中的權限。

與其他探索金鑰環一樣，區域探索金鑰圈對加密沒有影響。它僅在解密加密字段時才起作用。如果您在用於加密和解密的多重金鑰環中使用區域探索金鑰圈，則只有在解密時才有效。如果您單獨或在多重金鑰環中使用多區域探索金鑰環來加密資料，則加密作業會失敗。

重要

如果您在解密多重金鑰圈中包含 AWS KMS 區域探索金鑰圈，則區域探索金鑰圈會覆寫多重金鑰圈中其他金鑰圈所指定的所有 KMS 金鑰限制。多重金鑰環的行為與其限制性最小的鑰匙圈一樣。 AWS KMS 探索金鑰圈在單獨使用或多重金鑰環中使用時，對加密沒有影響。

AWS 資料庫加密 SDK 中的地區探索金鑰圈只會嘗試使用指定區域中的 KMS 金鑰進行解密。當您使用探索金鑰圈時，您可以在用 AWS KMS 戶端上設定 [區域]。這些 AWS 資料庫加密 SDK 實作不會依區域篩選 KMS 金鑰，但 AWS KMS 會失敗指定區域以外的 KMS 金鑰的解密要求。

如果您使用探索金鑰圈，建議您使用探索篩選器，將用於解密的 KMS 金鑰限制為指定 AWS 帳戶 和分割區中的 KMS 金鑰。

例如，下列程式碼會使用探索篩選器建立 AWS KMS 區域探索金鑰圈。此金鑰圈會將 AWS 資料庫加密 SDK 限制在美國西部 (奧勒岡) 區域 (美國西部 -2) 帳戶 111122223333 中的 KMS 金鑰。

Java

// Create the discovery filter
DiscoveryFilter discoveryFilter = DiscoveryFilter.builder()
        .partition("aws")
        .accountIds(111122223333)
        .build();
// Create the discovery keyring
CreateAwsKmsMrkDiscoveryMultiKeyringInput createAwsKmsMrkDiscoveryMultiKeyringInput = CreateAwsKmsMrkDiscoveryMultiKeyringInput.builder()
        .discoveryFilter(discoveryFilter)
        .regions("us-west-2")
        .build();
IKeyring decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);

C# / .NET

// Create discovery filter
var discoveryFilter = new DiscoveryFilter
{
    Partition = "aws",
    AccountIds = 111122223333
};
// Create the discovery keyring
var createAwsKmsMrkDiscoveryMultiKeyringInput = new CreateAwsKmsMrkDiscoveryMultiKeyringInput
{
    DiscoveryFilter = discoveryFilter,
    Regions = us-west-2
};
var decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);