AWS KMS 密钥环所需权限在 AWS KMS 钥匙圈 AWS KMS keys 中识别创建用于加密的 AWS KMS 密钥环创建用于解 AWS KMS 密的密钥环使用 AWS KMS 发现密钥环使用 AWS KMS 区域发现密钥环

AWS KMS 钥匙圈

密 AWS KMS 钥环使用对称加密AWS KMS keys来生成、加密和解密数据密钥。 AWS Key Management Service (AWS KMS) 保护您的 KMS 密钥并在 FIPS 边界内执行加密操作。我们建议您尽可能使用 AWS KMS 密钥环或具有类似安全属性的密钥环。

从 2.3 版开始，您可以在密钥 AWS KMS 环或主密钥提供程序中使用 AWS KMS 多区域密钥。 AWS Encryption SDK 和版本 3.0 中的 x。 AWS 加密 CLI 中的 x。有关使用新的多区域感知符号的详细信息和示例，请参阅使用多区域 AWS KMS keys。有关多区域密钥的更多信息，请参阅《AWS Key Management Service 开发人员指南》中的使用多区域密钥。

注意

版本 4。 .NET AWS Encryption SDK 的 x 和版本 3。 其中 x AWS Encryption SDK for Java 是唯一支持使用非对称 RSA 的 AWS KMS 密钥环的编程语言实现。 AWS KMS keys

如果您尝试将非对称 KMS 密钥纳入任何其他语言实施的加密密钥环中，加密调用将失败。如果将其纳入解密密钥环中，调用将被忽略。

中所有提及 KMS 密钥环的 AWS Encryption SDK 内容均指 AWS KMS 密钥环。

AWS KMS 钥匙圈可以包括两种类型的包装钥匙：

生成器密钥：生成并加密明文数据密钥。加密数据的密钥环必须有一个生成器密钥。
其他密钥：加密生成器密钥生成的纯文本数据密钥。 AWS KMS 钥匙圈可以有零个或多个额外的钥匙。

加密时，您使用的 AWS KMS 密钥环必须具有生成器密钥。解密时，生成器密钥可选，忽略生成器密钥和附加密钥之间的区别。

当 AWS KMS 加密密钥环只有一个 AWS KMS 密钥时，该密钥用于生成和加密数据密钥。

像所有钥匙圈一样， AWS KMS 钥匙圈可以单独使用，也可以与其他相同或不同类型的钥匙圈一起在多钥匙圈中使用。

AWS KMS 密钥环所需权限

AWS Encryption SDK 不需要 AWS 账户，也不依赖于任何一个 AWS 服务。但是，要使用 AWS KMS 密钥环，您需要对 AWS 账户密钥环 AWS KMS keys 中的具有以下最低权限。

要使用密 AWS KMS 钥环进行加密，您需要生成器密钥的 kms: GenerateDataKey 权限。您需要对密钥环中的所有其他密钥拥有 kms: encrypt 权限。 AWS KMS
要使用密钥环进行解密，您需要对密 AWS KMS 钥环中的至少一个密钥具有 kms: Decrypt 权限。 AWS KMS
要使用由密钥环组成的多密钥环进行加密，你需要获得生成器密 AWS KMS 钥环中生成器密钥的 kms: GenerateDataKey 权限。您需要拥有所有其他 AWS KMS 密钥环中所有其他密钥的 kms:Encrypt 权限。

有关权限的详细信息 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 Encryption SDK for C，您可以使用密钥 ARN 或别名 ARN 来识别 KMS 密钥。在所有其他语言实施中，您可以使用密钥 ID、密钥 ARN、别名名称或别名 ARN加密数据。
在解密密钥环中，您必须使用密钥 ARN 以标识 AWS KMS keys。该要求适用于 AWS Encryption SDK的所有语言实施。有关更多信息，请参阅选择包装密钥。
在用于加密和解密的密钥环中，您必须使用密钥 ARN 以标识 AWS KMS keys。该要求适用于 AWS Encryption SDK的所有语言实施。

如果您在加密密钥环中为 KMS 密钥指定别名名称或别名 ARN，则加密操作会将当前与该别名关联的密钥 ARN 保存在加密数据密钥的元数据中。它不会保存别名。更改别名不会影响用于解密加密数据密钥的 KMS 密钥。

创建用于加密的 AWS KMS 密钥环

您可以为每个 AWS KMS 密钥环配置一个 AWS KMS key 或多个 AWS KMS keys 相同或不同的密钥环， AWS 账户以及。 AWS 区域 AWS KMS keys 必须为对称加密密钥 (SYMMETRIC_DEFAULT)。您也可以使用对称加密多区域 KMS 密钥。与所有密钥环一样，您可以在一个多重密钥环中使用一个或多个 AWS KMS 密钥环。

创建用于加密数据的 AWS KMS 密钥环时，必须指定生成器密钥，该密钥用于生成纯文本数据密钥并对其进行加密。 AWS KMS key 数据密钥在数学上与 KMS 密钥无关。然后，如果您愿意，则可以指定用于加密相同纯文本数据密钥的其他 AWS KMS keys 内容。

要解密受此密钥环保护的加密消息，您使用的密钥环必须至少包含密钥环中 AWS KMS keys 定义的密钥环中的一个，或者不是。 AWS KMS keys（没有的 AWS KMS 密钥环 AWS KMS keys 称为AWS KMS 发现密钥环。）

在除之外的 AWS Encryption SDK 语言实现中 AWS Encryption SDK for C，所有封装在加密密钥环或多密钥环中的密钥都必须能够加密数据密钥。如有任何包装密钥无法加密，此加密方法将失败。因此，调用方必须拥有密钥环中所有密钥的所需权限。如果您单独或在多重密钥环中使用 Discovery 密钥环加密数据，加密操作将失败。唯一的例外是 AWS Encryption SDK for C，加密操作会忽略标准发现密钥环，但是如果您单独或在多密钥环中指定多区域发现密钥环，则会失败。

以下示例使用一个生成器 AWS KMS 密钥和一个附加密钥创建密钥环。这些示例使用密钥 ARN 标识 KMS 密钥。这是用于加密的 AWS KMS 密钥环的最佳实践，也是用于解密的 AWS KMS 密钥环的要求。有关更多信息，请参阅在 AWS KMS 钥匙圈 AWS KMS keys 中识别。

C

要 AWS KMS key 在中的加密密钥环中识别 AWS Encryption SDK for C，请指定密钥 ARN 或别名 ARN。在解密密钥环中，您必须使用密钥 ARN。有关更多信息，请参阅在 AWS KMS 钥匙圈 AWS KMS keys 中识别。

有关完整的示例，请参阅 string.cpp。


const char * generator_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"

const char * additional_key = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"    

struct aws_cryptosdk_keyring *kms_encrypt_keyring = 
       Aws::Cryptosdk::KmsKeyring::Builder().Build(generator_key,{additional_key});

C# / .NET

要在 for .NET 中创建包含一个或多个 AWS KMS 密钥 AWS Encryption SDK 的密钥 AWS KMS 环，请创建一个多密钥环。f AWS Encryption SDK or .NET 包括一个仅用于 AWS KMS 密钥的多密钥环。

在.NET 中 AWS KMS key 为加密密钥环指定时，可以使用任何有效的密钥标识符：密钥 ID、密钥 AR N 、别名或别名 ARN。 AWS Encryption SDK有关识别 AWS KMS 钥匙圈 AWS KMS keys 中的的帮助，请参阅在 AWS KMS 钥匙圈 AWS KMS keys 中识别。

以下示例使用版本 4。 x for .NET AWS Encryption SDK 用于创建带有生成器密 AWS KMS 钥和其他密钥的密钥环。有关完整示例，请参见 AwsKmsMultiKeyringExample.cs。


// Instantiate the AWS Encryption SDK and material provider
var mpl = new MaterialProviders(new MaterialProvidersConfig());
var esdk =  new ESDK(new AwsEncryptionSdkConfig());

string generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<string> additionalKey = new List<string> { "alias/exampleAlias" };

// Instantiate the keyring input object
var kmsEncryptKeyringInput = new CreateAwsKmsMultiKeyringInput
{
    Generator = generatorKey,
    KmsKeyIds = additionalKey
};

var kmsEncryptKeyring = materialProviders.CreateAwsKmsMultiKeyring(kmsEncryptKeyringInput);

JavaScript Browser

在中 AWS KMS key 为加密密钥环指定时 AWS Encryption SDK for JavaScript，您可以使用任何有效的密钥标识符：密钥 ID、密钥 AR N 、别名或别名 ARN。有关识别 AWS KMS 钥匙圈 AWS KMS keys 中的的帮助，请参阅在 AWS KMS 钥匙圈 AWS KMS keys 中识别。

有关完整的示例，请参阅中存储库中的 kms_simple.ts。 AWS Encryption SDK for JavaScript GitHub


const clientProvider = getClient(KMS, { credentials })
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
const additionalKey = 'alias/exampleAlias'

const keyring = new KmsKeyringBrowser({
  clientProvider, 
  generatorKeyId, 
  keyIds: [additionalKey] 
})

JavaScript Node.js

有关完整的示例，请参阅中存储库中的 kms_simple.ts。 AWS Encryption SDK for JavaScript GitHub


const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
                            
const additionalKey = 'alias/exampleAlias'

const keyring = new KmsKeyringNode({
  generatorKeyId,
  keyIds: [additionalKey]
})

Java

要在中创建包含一个或多个 AWS KMS 密钥的密钥 AWS KMS 环 AWS Encryption SDK for Java，请创建一个多密钥环。 AWS Encryption SDK for Java 包括一个仅用于 AWS KMS 存放钥匙的多钥匙圈。

在中 AWS KMS key 为加密密钥环指定时 AWS Encryption SDK for Java，您可以使用任何有效的密钥标识符：密钥 ID、密钥 AR N 、别名或别名 ARN。有关识别 AWS KMS 钥匙圈 AWS KMS keys 中的的帮助，请参阅在 AWS KMS 钥匙圈 AWS KMS keys 中识别。

有关完整示例，请参阅中 AWS Encryption SDK for Java 存储库中的 BasicEncryptionKeyringExample GitHub.java。


 // Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
            .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
            .build();

String generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<String> additionalKey = Collections.singletonList("alias/exampleAlias");

// Create the AWS KMS keyring
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
        .generator(generatorKey)
        .kmsKeyIds(additionalKey)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);

创建用于解 AWS KMS 密的密钥环

解密返回的加密消息时，您还可以指定密 AWS KMS 钥环。 AWS Encryption SDK 如果解密密钥环指定 AWS KMS keys，则 AWS Encryption SDK 将仅使用那些包装密钥来解密加密消息中的加密数据密钥。（您也可以使用未指定任何内容的AWS KMS 发现密钥环 AWS KMS keys。）

解密时，会在密 AWS KMS 钥环中 AWS Encryption SDK 搜索可以解密其中 AWS KMS key 一个加密数据密钥的。具体而言，对加密消息中的每个加密数据密钥 AWS Encryption SDK 使用以下模式。

从加密消息的元数据中 AWS Encryption SDK AWS KMS key 获取加密数据密钥的密钥 ARN。
在解密密钥环中 AWS Encryption SDK 搜索 AWS KMS key 具有匹配密钥 ARN 的。
如果它在密钥环中找到密钥 ARN 匹配的，则 AWS Encryption SDK 会要求 AWS KMS 使用 KMS 密钥解密加密的数据密钥。 AWS KMS key
否则，它跳到下一个加密的数据密钥（如果有）。

除非加密数据密钥的密钥 ARN 包含在解密密钥环中 AWS KMS key ，否则 AWS Encryption SDK 永远不会尝试解密加密的数据密钥。如果解密密钥环不包含任何加密了任何数据密钥的 ARN AWS KMS keys ，则解密调用将 AWS Encryption SDK 失败，而不会调用。 AWS KMS

从 1.7 版本开始。 x，解密加密数据密钥时， AWS Encryption SDK 始终将的密钥 ARN 传递 AWS KMS key 给解密操作的KeyId参数。 AWS KMS确定 AWS KMS key 何时解密是一种 AWS KMS 最佳做法，可确保使用要使用的包装密钥解密加密的数据密钥。

当解密密 AWS KMS 钥环中至少有一个可以解密加密消息 AWS KMS key 中的一个加密数据密钥时，使用密钥环的解密调用就会成功。此外，调用方必须具有该 AWS KMS key的 kms:Decrypt 权限。此行为使您能够加密不同 AWS 区域和账户 AWS KMS keys 中的多个数据，但提供针对特定账户、区域、用户、群组或角色量身定制的更有限的解密密钥环。

在解密密钥环 AWS KMS key 中指定时，必须使用其密钥 ARN。否则 AWS KMS key ，将无法识别。要获得有关查找密钥 ARN 的帮助，请参阅《AWS Key Management Service 开发人员指南》中的查找密钥 ID 和 ARN。

注意

如果将加密密钥环重新用于解密，请确保密钥环中的 AWS KMS keys 由其密钥 ARN 标识。

例如，以下 AWS KMS 密钥环仅包含加密密钥环中使用的附加密钥。但是，该示例并未按别名引用附加密钥 alias/exampleAlias，而是按照解密调用的要求使用附加密钥的密钥 ARN。

您可以使用该密钥环解密使用生成器密钥和附加密钥加密的消息，但前提是您有权使用附加密钥解密数据。

C


const char * additional_key = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"    

struct aws_cryptosdk_keyring *kms_decrypt_keyring = 
       Aws::Cryptosdk::KmsKeyring::Builder().Build(additional_key);

C# / .NET

由于此解密密钥环仅包含一个 AWS KMS 密钥，因此该示例使用该CreateAwsKmsKeyring()方法及其对象的实例。CreateAwsKmsKeyringInput要创建具有一把 AWS KMS 钥匙的 AWS KMS 密钥环，可以使用单钥或多钥匙圈。有关更多信息，请参阅加密适用于 .NET 的 AWS Encryption SDK 中的数据。以下示例使用版本 4。 x for .NET AWS Encryption SDK 用于创建用于解密的 AWS KMS 密钥环。


// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string additionalKey = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321";

// Instantiate a KMS keyring for one AWS KMS key.
var kmsDecryptKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = additionalKey
};

var kmsDecryptKeyring = materialProviders.CreateAwsKmsKeyring(kmsDecryptKeyringInput);

JavaScript Browser


const clientProvider = getClient(KMS, { credentials })
const additionalKey = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321'

const keyring = new KmsKeyringBrowser({ clientProvider, keyIds: [additionalKey] })

JavaScript Node.js


const additionalKey = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321'

const keyring = new KmsKeyringNode({ keyIds: [additionalKey] })

Java

由于此解密密钥环仅包含一个 AWS KMS 密钥，因此该示例使用该CreateAwsKmsKeyring()方法及其对象的实例。CreateAwsKmsKeyringInput要创建具有一把 AWS KMS 钥匙的 AWS KMS 密钥环，可以使用单钥或多钥匙圈。


// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
        
String additionalKey = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321";

// Create a AwsKmsKeyring
CreateAwsKmsKeyringInput kmsDecryptKeyringInput = CreateAwsKmsKeyringInput.builder()
        .generator(additionalKey)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(kmsDecryptKeyringInput);

您也可以使用 AWS KMS 密钥环来指定用于解密的生成器密钥，例如以下密钥。解密时， AWS Encryption SDK 会忽略生成器密钥和其他密钥之间的区别。它可以使用任何指定的方法 AWS KMS keys 来解密加密的数据密钥。只有当调用者有权使用它来解密数据时，对的调 AWS KMS key 用才会 AWS KMS 成功。

C


struct aws_cryptosdk_keyring *kms_decrypt_keyring = 
       Aws::Cryptosdk::KmsKeyring::Builder().Build(generator_key, {additional_key, other_key});

C# / .NET

以下示例使用适用于 .NET 的 AWS Encryption SDK 版本 4.x。


// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

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

// Instantiate a KMS keyring for one AWS KMS key.
var kmsDecryptKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = generatorKey
};

var kmsDecryptKeyring = materialProviders.CreateAwsKmsKeyring(kmsDecryptKeyringInput);

JavaScript Browser


const clientProvider = getClient(KMS, { credentials })

const keyring = new KmsKeyringBrowser({
  clientProvider, 
  generatorKeyId, 
  keyIds: [additionalKey, otherKey]
})

JavaScript Node.js


const keyring = new KmsKeyringNode({
  generatorKeyId,
  keyIds: [additionalKey, otherKey]
})

Java


// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
        
String generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a AwsKmsKeyring
CreateAwsKmsKeyringInput kmsDecryptKeyringInput = CreateAwsKmsKeyringInput.builder()
        .generator(generatorKey)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(kmsDecryptKeyringInput);

与使用所有指定内容的加密密钥环不同 AWS KMS keys，您可以使用解密密钥环来解密加密的消息，该密钥环包含 AWS KMS keys 与加密消息无关且呼叫者无权 AWS KMS keys 使用的内容。如果对 AWS KMS 的 decrypt 调用失败（例如，在调用方没有所需的权限时）， AWS Encryption SDK 直接跳到下一个加密的数据密钥。

使用 AWS KMS 发现密钥环

解密时，最佳做法是指定 AWS Encryption SDK 可以使用的包装密钥。要遵循此最佳实践，请使用 AWS KMS 解密密钥环，将 AWS KMS 封装密钥限制在您指定的密钥范围内。但是，您也可以创建AWS KMS 发现密钥环，即不指定任何包装 AWS KMS 密钥的密钥环。

为 AWS KMS 多区域密钥 AWS Encryption SDK 提供了标准 AWS KMS 发现密钥环和发现密钥环。有关在中使用多区域密钥的信息 AWS Encryption SDK，请参阅使用多区域 AWS KMS keys。

由于 Discovery 密钥环未指定任何包装密钥，因此 Discovery 密钥无法加密数据。如果您单独或在多重密钥环中使用 Discovery 密钥环加密数据，加密操作将失败。唯一的例外是 AWS Encryption SDK for C，加密操作会忽略标准发现密钥环，但是如果您单独或在多密钥环中指定多区域发现密钥环，则会失败。

解密时，发现密钥环允许使用加密后的密钥要求 AWS KMS 解密任何加密的数据密钥，无论谁拥有或有权访问 AWS KMS key 该密钥。 AWS Encryption SDK AWS KMS key只有在调用方拥有 AWS KMS key的 kms:Decrypt 权限时，调用才会成功。

重要

如果您在解密多密钥环中包含 AWS KMS 发现密钥环，则发现密钥环将覆盖多密钥环中其他密钥环中指定的所有 KMS 密钥限制。多重密钥环的行为类似于限制最少的密钥环。 AWS KMS 发现密钥环单独使用或在多密钥环中使用时，对加密没有影响。

为方便起见， AWS Encryption SDK 提供了 AWS KMS 发现钥匙圈。不过，出于以下原因，建议尽可能使用更受限制的密钥环。

真实性 — AWS KMS 发现密钥环可以使用任何 AWS KMS key 用于加密加密消息中数据密钥的密钥，这样调用者就可以使用该密钥 AWS KMS key 进行解密。这可能不是调用方打算使用的 AWS KMS key 。例如，其中一个加密的数据密钥可能是在任何人都可以 AWS KMS key 使用的安全性较低的情况下加密的。
延迟和性能 — AWS KMS 发现密钥环可能比其他密钥环慢得多，因为他们 AWS Encryption SDK 会尝试解密所有加密的数据密钥，包括由 AWS KMS keys 其他 AWS 账户和区域加密的数据密钥，而调用者无权使用这些密钥进行解密。 AWS KMS keys

如果您使用发现密钥环，我们建议您使用发现过滤器将可用的 KMS 密钥限制为指定 AWS 账户和分区中的密钥。 AWS Encryption SDK版本 1.7.x 及更高版本支持发现筛选条件。如需帮助查找您的账户 ID 和分区，请参阅 AWS 一般参考 中的您的 AWS 账户标识符和 ARN 格式。

以下代码使用发现过滤器实例化 AWS KMS 发现密钥环，该过滤器将 AWS Encryption SDK 可用的 KMS 密钥限制为aws分区和 111122223333 示例账户中的密钥。

在使用此代码之前，请将示例 AWS 账户和分区值替换为 AWS 账户和分区的有效值。如果您的 KMS 密钥位于中国区域，请使用 aws-cn 分区值。如果您的 KMS 密钥在中 AWS GovCloud (US) Regions，请使用aws-us-gov分区值。对于所有其他值 AWS 区域，请使用aws分区值。

C

有关完整的示例，请参阅：kms_discovery.cpp。


std::shared_ptr<KmsKeyring::> discovery_filter(
    KmsKeyring::DiscoveryFilter::Builder("aws")
        .AddAccount("111122223333")
        .Build());

struct aws_cryptosdk_keyring *kms_discovery_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
       .BuildDiscovery(discovery_filter));

C# / .NET

以下示例使用适用于 .NET 的 AWS Encryption SDK 版本 4.x。


// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

List<string> account = new List<string> { "111122223333" };
        
// In a discovery keyring, you specify an AWS KMS client and a discovery filter,
// but not a AWS KMS key
var kmsDiscoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    DiscoveryFilter = new DiscoveryFilter()
    {
        AccountIds = account,
        Partition = "aws"
    }
};
        
var kmsDiscoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(kmsDiscoveryKeyringInput);

JavaScript Browser

在中 JavaScript，必须明确指定发现属性。


const clientProvider = getClient(KMS, { credentials })

const discovery = true
const keyring = new KmsKeyringBrowser(clientProvider, {
    discovery,
    discoveryFilter: { accountIDs: [111122223333], partition: 'aws' }
})

JavaScript Node.js

在中 JavaScript，必须明确指定发现属性。


const discovery = true

const keyring = new KmsKeyringNode({
    discovery,
    discoveryFilter: { accountIDs: ['111122223333'], partition: '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);

使用 AWS KMS 区域发现密钥环

AWS KMS Regional Discovery 密钥环是一种不指定 KMS 密钥 ARN 的密钥环。相反，它允许仅使用 KMS 密钥进行解密。 AWS Encryption SDK AWS 区域

使用 AWS KMS 区域发现密钥环解密时，会 AWS Encryption SDK 解密在指定项下加密的所有加密数据密钥。 AWS KMS key AWS 区域要成功，调用者必须拥有对指定数据密钥 AWS KMS keys 中至少一个加密数据密钥 AWS 区域的kms:Decrypt权限。

与其他 Discovery 密钥环相同，Regional Discovery 密钥环对加密无效。该密钥环仅在解密加密消息时适用。如果您在用于加密和解密的多重密钥环中使用 Regional Discovery 密钥环，则该密钥环仅在解密时有效。如果您单独或在多重密钥环中使用多区域 Discovery 密钥环加密数据，加密操作将失败。

重要

如果您在解密多密钥环中包含 AWS KMS 区域发现密钥环，则区域发现密钥环将覆盖多密钥环中其他密钥环中指定的所有 KMS 密钥限制。多重密钥环的行为类似于限制最少的密钥环。 AWS KMS 发现密钥环单独使用或在多密钥环中使用时，对加密没有影响。

AWS Encryption SDK for C 尝试中的区域发现密钥环仅使用指定区域中的 KMS 密钥进行解密。在 AWS Encryption SDK for JavaScript 和中 AWS Encryption SDK 为.NET 使用发现密钥环时，需要在 AWS KMS 客户端上配置区域。这些 AWS Encryption SDK 实现不会按区域过滤 KMS 密钥，但对指定区域之外的 KMS 密钥的解密请求 AWS KMS 会失败。

如果您使用发现密钥环，我们建议您使用发现过滤器将解密中使用的 KMS 密钥限制为指定 AWS 账户和分区中的密钥。 AWS Encryption SDK版本 1.7.x 及更高版本支持发现筛选条件。

例如，以下代码使用发现过滤器创建 AWS KMS 区域发现密钥环。此密钥环 AWS Encryption SDK 将仅限于美国西部（俄勒冈）地区 (us-west-2) 账户 111122223333 中的 KMS 密钥。

C

要在可正常使用的示例中查看此密钥环和 create_kms_client 方法，请参阅 kms_discovery.cpp。


std::shared_ptr<KmsKeyring::DiscoveryFilter> discovery_filter(
    KmsKeyring::DiscoveryFilter::Builder("aws")
        .AddAccount("111122223333")
        .Build());

struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
       .WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery(discovery_filter));

C# / .NET

f AWS Encryption SDK or .NET 没有专用的区域发现密钥环。但是，您可以使用多种方法将解密时使用的 KMS 密钥限制在特定区域。

限制 Discovery 密钥环区域的最有效方法是使用多区域感知 Discovery 密钥环，即使您仅使用单区域密钥加密数据。遇到单区域密钥时，多区域感知密钥环不使用任何多区域功能。

CreateAwsKmsMrkDiscoveryKeyring() 方法返回的密钥环会在调用 AWS KMS之前按区域筛选 KMS 密钥。 AWS KMS 只有当加密的数据密钥由对象中的Region参数指定的区域中的 KMS 密钥加密时，它才会向发送解密请求。CreateAwsKmsMrkDiscoveryKeyringInput

以下示例使用版本 4。 .NET AWS Encryption SDK 的 x。


// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

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

// Create the discovery filter
var filter = DiscoveryFilter = new DiscoveryFilter
{
    AccountIds = account,
    Partition = "aws"
};
                                
var regionalDiscoveryKeyringInput = new CreateAwsKmsMrkDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    Region = RegionEndpoint.USWest2,
    DiscoveryFilter = filter
};                                

var kmsRegionalDiscoveryKeyring = materialProviders.CreateAwsKmsMrkDiscoveryKeyring(regionalDiscoveryKeyringInput);

您还可以 AWS 区域通过在 AWS KMS 客户端实例中指定区域来将 KMS 密钥限制为特定的密钥 (AmazonKeyManagementServiceClient)。但是，与使用多区域感知 Discovery 密钥环相比，这种配置效率较低，而且成本可能更高。for .NET 不是在调用之前按区域筛选 KMS 密钥 AWS KMS，而是调 AWS KMS 用每个加密的数据密钥（直到它解密一个），并依靠它 AWS KMS 来将其使用的 KMS 密钥限制在指定区域。 AWS Encryption SDK

以下示例使用适用于 .NET 的 AWS Encryption SDK 版本 4.x。


// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

List<string> account = new List<string> { "111122223333" };
        
// Create the discovery filter,
// but not a AWS KMS key
var createRegionalDiscoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    DiscoveryFilter = new DiscoveryFilter()
    {
        AccountIds = account,
        Partition = "aws"
    }
};
        
var kmsRegionalDiscoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(createRegionalDiscoveryKeyringInput);

JavaScript Browser


const clientProvider = getClient(KMS, { credentials })

const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser(clientProvider, {
    discovery,
    discoveryFilter: { accountIDs: ['111122223333'], partition: 'aws' }
})

JavaScript Node.js

要在有效的示例中查看该密钥环以及 limitRegions 函数，请参阅 kms_regional_discovery.ts。


const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({
    clientProvider,
    discovery,
    discoveryFilter: { accountIDs: ['111122223333'], partition: 'aws' }
})

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);

AWS Encryption SDK for JavaScript 还导出了 Node.js 和浏览器的excludeRegions函数。此函数会创建一个 AWS KMS 区域发现密钥环，该密钥环省略 AWS KMS keys 了特定区域。以下示例创建了一个 AWS KMS 区域发现密钥环，除了美国东部（弗吉尼亚北部）(us-east-1) AWS 区域之外，该密钥环可在账户 111122223333 中使用 AWS KMS keys 。

AWS Encryption SDK for C 没有类似的方法，但您可以通过创建自定义方法来实现。ClientSupplier

该示例显示了 Node.js 的代码。


const discovery = true
const clientProvider = excludeRegions(['us-east-1'], getKmsClient)
const keyring = new KmsKeyringNode({
    clientProvider,
    discovery,
    discoveryFilter: { accountIDs: [111122223333], partition: 'aws' }
})

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

选择密钥环

AWS KMS 分层钥匙圈