多重 keyring - AWS Encryption SDK

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

多重 keyring

您可以結合 keyring 成為多重 keyring。多重 keyring 是一種 keyring，其中包含相同或不同類型的一或多個個別 keyring。效果就像是使用系列中的數個 keyring。使用多重 keyring 來加密資料時，其任何 keyring 中的任何包裝金鑰均可以解密該資料。

建立多重 keyring 來加密資料時，您會指定其中一個 keyring 做為產生器 keyring。所有其他 keyring 稱為子 keyring。產生器 keyring 會產生並加密純文字資料金鑰。然後，所有子 keyring 中的所有包裝金鑰會加密相同的純文字資料金鑰。該多重 keyring 會為多重 keyring 中的每個包裝金鑰傳回純文字金鑰和一個加密的資料金鑰。如果產生器金鑰環是KMS金鑰環 ， AWS KMS 則金鑰環中的產生器金鑰會產生並加密純文字金鑰。然後， AWS KMS 金鑰環 AWS KMS keys 中的所有額外金鑰，以及多金鑰環中所有子金鑰環中的所有包裝金鑰，都會加密相同的純文字金鑰。

如果您建立沒有產生器金鑰控制的多金鑰，則可以單獨使用它來解密資料，但不能加密。或者，若要在加密操作中使用沒有產生器金鑰控制的多金鑰，您可以將它指定為另一個多金鑰中的子金鑰。沒有產生器金鑰控制的多金鑰無法指定為另一個多金鑰中的產生器金鑰。

解密時， AWS Encryption SDK 會使用 鍵環嘗試解密其中一個加密的資料金鑰。按照在多重 keyring 中指定的順序呼叫 keyring。只要任何 keyring 中的任何金鑰可以解密已加密的資料金鑰，處理就會停止。

從 1.7.x 版開始，當加密的資料金鑰是在 AWS Key Management Service （AWS KMS） 金鑰輸入 （或主金鑰提供者） 下加密時， AWS Encryption SDK 一律會將 ARN的金鑰傳遞 AWS KMS key 至 AWS KMS 解密操作的 KeyId 參數。這是 AWS KMS 最佳實務，可確保您使用打算使用的包裝金鑰來解密加密的資料金鑰。

若要查看多重 keyring 的工作範例，請參閱：

若要建立多重 keyring，請先將子 keyring 執行個體化。在此範例中，我們使用 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
)

接著，建立多重 keyring，並指定其產生器 keyring (如果有)。在此範例中，我們會建立多鍵控，其中 AWS KMS 鍵控是產生器鍵控，AES而鍵控是子鍵控。

C

在 C 中的多重 keyring 建構函數中，您只會指定其產生器 keyring。

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

若要將子 keyring 新增至您的多重 keyring，請使用 aws_cryptosdk_multi_keyring_add_child 方法。您需要為您新增的每個子 keyring 呼叫該方法一次。

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

.NET CreateMultiKeyringInput 建構器可讓您定義產生器鍵環和子鍵環。產生的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
)

現在，您可以使用多重 keyring 來加密和解密資料。