多重密钥环 - AWS Encryption SDK

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

多重密钥环

您可以将多个密钥环合并为一个多重密钥环。多重密钥环 是由一个或多个相同或不同类型的密钥环组成的密钥环。效果与连续使用多个密钥环类似。在使用多重密钥环加密数据时，其任意密钥环中的任意包装密钥都可以对数据进行解密。

在创建多重密钥环以加密数据时，您可以将一个密钥环指定为生成器密钥环。所有其他密钥环称为子密钥环。生成器密钥环生成并加密明文数据密钥。然后，所有子密钥环中的所有包装密钥都加密相同的明文数据密钥。对于多重密钥环中的每个包装密钥，多重密钥环都返回明文密钥和一个加密的数据密钥。如果生成器密钥环是密KMS钥环，则密钥 AWS KMS 环中的生成器密钥会生成并加密纯文本密钥。然后，密钥环 AWS KMS keys 中的所有其他密钥，以及多密 AWS KMS 钥环中所有子密钥环中的所有封装密钥，都将加密相同的纯文本密钥。

如果您创建了一个没有生成器密钥环的多密钥环，则可以单独使用它来解密数据，但不能用于加密。或者，要在加密操作中使用没有生成器密钥环的多密钥环，可以在另一个多密钥环中将其指定为子密钥环。没有生成器密钥环的多密钥环不能被指定为另一个多密钥环中的生成器密钥环。

解密时， AWS Encryption SDK 使用密钥环尝试解密其中一个加密的数据密钥。密钥环是按照在多重密钥环中指定的顺序调用的。只要任何密钥环中的任何密钥可以解密加密的数据密钥，处理就会立即停止。

从 1.7 版本开始。 x，当加密的数据密钥在 AWS Key Management Service (AWS KMS) 密钥环（或主密钥提供程序）下加密时， AWS Encryption SDK 始终会将ARN的密钥传递 AWS KMS key 给 AWS KMS 解密操作的KeyId参数。这是一种 AWS KMS 最佳实践，可确保您使用要使用的包装密钥解密加密的数据密钥。

要查看多重密钥环的有效示例，请参阅：

要创建多重密钥环，首先要实例化子密钥环。在此示例中，我们使用 AWS KMS 密钥环和原始密AES钥环，但您可以将任何支持的密钥环组合成一个多密钥环。

C
/* Define an AWS KMS keyring. For details, see string.cpp */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(example_key);

// Define a Raw AES keyring. For details, see raw_aes_keyring.c */
struct aws_cryptosdk_keyring *aes_keyring = aws_cryptosdk_raw_aes_keyring_new(
        alloc, wrapping_key_namespace, wrapping_key_name, wrapping_key, AWS_CRYPTOSDK_AES256);
C# / .NET
// Define an AWS KMS keyring. For details, see AwsKmsKeyringExample.cs.
var kmsKeyring = materialProviders.CreateAwsKmsKeyring(createKmsKeyringInput);

// Define a Raw AES keyring. For details, see RawAESKeyringExample.cs.
var aesKeyring = materialProviders.CreateRawAesKeyring(createAesKeyringInput);
JavaScript Browser

以下示例使用buildClient函数来指定默认的承诺策略REQUIRE_ENCRYPT_REQUIRE_DECRYPT。您也可以使用buildClient来限制加密消息中加密数据密钥的数量。有关更多信息，请参阅 限制加密数据密钥。

import {
  KmsKeyringBrowser,
  KMS,
  getClient,
  RawAesKeyringWebCrypto,
  RawAesWrappingSuiteIdentifier,
  MultiKeyringWebCrypto,
  buildClient,
  CommitmentPolicy,
  synchronousRandomValues,
} from '@aws-crypto/client-browser'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

const clientProvider = getClient(KMS, { credentials })

// Define an AWS KMS keyring. For details, see kms_simple.ts. 
const kmsKeyring = new KmsKeyringBrowser({ generatorKeyId: exampleKey })

// Define a Raw AES keyring. For details, see aes_simple.ts.
const aesKeyring = new RawAesKeyringWebCrypto({ keyName, keyNamespace, wrappingSuite, masterKey })
JavaScript Node.js

以下示例使用buildClient函数来指定默认的承诺策略REQUIRE_ENCRYPT_REQUIRE_DECRYPT。您也可以使用buildClient来限制加密消息中加密数据密钥的数量。有关更多信息，请参阅 限制加密数据密钥。

import {
  MultiKeyringNode,
  KmsKeyringNode,
  RawAesKeyringNode,
  RawAesWrappingSuiteIdentifier,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-node'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

// Define an AWS KMS keyring. For details, see kms_simple.ts. 
const kmsKeyring = new KmsKeyringNode({ generatorKeyId: exampleKey })

// Define a Raw AES keyring. For details, see raw_aes_keyring_node.ts.
const aesKeyring = new RawAesKeyringNode({ keyName, keyNamespace, wrappingSuite, unencryptedMasterKey })
Java
// Define the raw AES keyring.
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateRawAesKeyringInput createRawAesKeyringInput = CreateRawAesKeyringInput.builder()
        .keyName("AES_256_012")
        .keyNamespace("HSM_01")
        .wrappingKey(AESWrappingKey)
        .wrappingAlg(AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16)
        .build();
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(createRawAesKeyringInput);

// Define the AWS KMS keyring.
final CreateAwsKmsMrkMultiKeyringInput createAwsKmsMrkMultiKeyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
        .generator(kmsKeyArn)
        .build();
IKeyring awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
Python

以下示例使用默认承诺策略实例化 AWS Encryption SDK 客户端。REQUIRE_ENCRYPT_REQUIRE_DECRYPT

# Create the AWS KMS keyring
kms_client = boto3.client('kms', region_name="us-west-2")
        
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
    config=MaterialProvidersConfig()
)

kms_keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput(
    generator=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab,
    kms_client=kms_client
)

kms_keyring: IKeyring = mat_prov.create_aws_kms_keyring(
    input=kms_keyring_input
)
                        
# Create Raw AES keyring
key_name_space = "HSM_01"
key_name = "AES_256_012"
                            
raw_aes_keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput(
    key_namespace=key_name_space,
    key_name=key_name,
    wrapping_key=AESWrappingKey,
    wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
)

raw_aes_keyring: IKeyring = mat_prov.create_raw_aes_keyring(
    input=raw_aes_keyring_input
)

接下来创建多重密钥环并指定其生成器密钥环（如果有）。在此示例中，我们创建了一个多密钥环，其中密钥环是生成器 AWS KMS 密钥环，密钥环是子AES密钥环。

C

在 C 的多重密钥环构造函数中，您仅指定其生成器密钥环。

struct aws_cryptosdk_keyring *multi_keyring = aws_cryptosdk_multi_keyring_new(alloc, kms_keyring);

要将子密钥环添加到多重密钥环中，请使用 aws_cryptosdk_multi_keyring_add_child 方法。您需要为添加的每个子密钥环调用一次该方法。

// Add the Raw AES keyring (C only)
aws_cryptosdk_multi_keyring_add_child(multi_keyring, aes_keyring);
C# / .NET

的。 NETCreateMultiKeyringInput构造函数允许你定义生成器密钥环和子密钥环。生成的 CreateMultiKeyringInput 对象不可变。

var createMultiKeyringInput = new CreateMultiKeyringInput
{
    Generator = kmsKeyring,
    ChildKeyrings = new List<IKeyring>() {aesKeyring}
};

var multiKeyring = materialProviders.CreateMultiKeyring(createMultiKeyringInput);
JavaScript Browser

JavaScript 多钥匙圈是不可变的。 JavaScript 多密钥环构造函数允许您指定生成器密钥环和多个子密钥环。

const clientProvider = getClient(KMS, { credentials })

const multiKeyring = new MultiKeyringWebCrypto(generator: kmsKeyring, children: [aesKeyring]);
JavaScript Node.js

JavaScript 多钥匙圈是不可变的。 JavaScript 多密钥环构造函数允许您指定生成器密钥环和多个子密钥环。

const multiKeyring = new MultiKeyringNode(generator: kmsKeyring, children: [aesKeyring]);
Java

Java CreateMultiKeyringInput 构造函数允许您定义生成器密钥环和子密钥环。生成的 createMultiKeyringInput 对象不可变。

final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
        .generator(awsKmsMrkMultiKeyring)
        .childKeyrings(Collections.singletonList(rawAesKeyring))
        .build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
Python
multi_keyring_input: CreateMultiKeyringInput = CreateMultiKeyringInput(
    generator=kms_keyring,
    child_keyrings=[raw_aes_keyring]
)

multi_keyring: IKeyring = mat_prov.create_multi_keyring(
    input=multi_keyring_input
)

现在，您就可以使用此多重密钥环加密和解密数据了。