建立作用中分支金鑰

分支索引鍵是從 AWS KMS 衍生的資料索引鍵 AWS KMS key ，階層式 keyring 會使用它來減少對 進行的呼叫數量 AWS KMS。作用中分支金鑰是最新的分支金鑰版本。階層式 keyring 會為每個加密請求產生唯一的資料金鑰，並使用衍生自作用中分支金鑰的唯一包裝金鑰來加密每個資料金鑰。

若要建立新的作用中分支金鑰，您必須靜態設定金鑰存放區動作。 CreateKey是一項特殊權限操作，可將金鑰存放區動作組態中指定的 KMS 金鑰 ARN 新增至金鑰存放區允許清單。然後，KMS 金鑰會用來產生新的作用中分支金鑰。我們建議您限制對此操作的存取，因為一旦 KMS 金鑰新增至金鑰存放區，就無法刪除。

您可以在金鑰存放區中允許列出一個 KMS 金鑰，也可以更新您在金鑰存放區動作組態中指定的 KMS 金鑰 ARN 並CreateKey再次呼叫，以允許列出多個 KMS 金鑰。如果您允許列出多個 KMS 金鑰，您的金鑰存放區使用者應設定其金鑰存放區動作以進行探索，以便他們可以在可存取的金鑰存放區中使用任何允許列出的金鑰。如需詳細資訊，請參閱設定金鑰存放區動作。

所需的 許可

若要建立分支金鑰，您需要kms:GenerateDataKeyWithoutPlaintext 和 kms:ReEncrypt 許可。

建立分支金鑰

下列操作會使用您在金鑰存放區動作組態中指定的 KMS 金鑰建立新的作用中分支金鑰，並將作用中分支金鑰新增至做為金鑰存放區的 DynamoDB 資料表。

當您呼叫 時CreateKey，您可以選擇指定下列選用值。

• branchKeyIdentifier：定義自訂 branch-key-id。

  若要建立自訂 branch-key-id，您還必須在 encryptionContext 參數中包含其他加密內容。

• encryptionContext：定義一組選用的非秘密金鑰/值對，在 kms:GenerateDataKeyWithoutPlaintext 呼叫中包含的加密內容中提供額外的已驗證資料 (AAD)。

  此額外的加密內容會以 aws-crypto-ec: 字首顯示。

Java

final Map<String, String> additionalEncryptionContext = Collections.singletonMap("Additional Encryption Context for",
	         "custom branch key id");
	             
	 final String BranchKey = keystore.CreateKey(
	         CreateKeyInput.builder()
	                 .branchKeyIdentifier(custom-branch-key-id) //OPTIONAL
	                 .encryptionContext(additionalEncryptionContext) //OPTIONAL              
	                 .build()).branchKeyIdentifier();

C# / .NET

var additionalEncryptionContext = new Dictionary<string, string>();
	 additionalEncryptionContext.Add("Additional Encryption Context for", "custom branch key id");
	         
	 var branchKeyId = keystore.CreateKey(new CreateKeyInput
	 {
	     BranchKeyIdentifier = "custom-branch-key-id", // OPTIONAL
	     EncryptionContext = additionalEncryptionContext // OPTIONAL
	 });

Rust

let additional_encryption_context = HashMap::from([
    ("Additional Encryption Context for".to_string(), "custom branch key id".to_string())
]);

let branch_key_id = keystore.create_key()
    .branch_key_identifier("custom-branch-key-id") // OPTIONAL
    .encryption_context(additional_encryption_context) // OPTIONAL
    .send()
    .await?
    .branch_key_identifier
    .unwrap();

首先，CreateKey操作會產生下列值。

• 第 4 版的通用唯一識別碼 (UUID) branch-key-id（除非您指定了自訂 branch-key-id)。

• 分支金鑰版本的第 4 版 UUID

• ISO 8601 日期和時間格式timestamp的 ，以國際標準時間 (UTC) 為單位。

然後，CreateKey操作會使用下列請求呼叫 kms:GenerateDataKeyWithoutPlaintext。

{
	    "EncryptionContext": { 
	       "branch-key-id" : "branch-key-id",
	       "type" : "type",
	       "create-time" : "timestamp",
	       "logical-key-store-name" : "the logical table name for your key store",
	       "kms-arn" : the KMS key ARN,
	       "hierarchy-version" : "1",
	       "aws-crypto-ec:contextKey": "contextValue"
	    },
	    "KeyId": "the KMS key ARN you specified in your key store actions",
	    "NumberOfBytes": "32"
	 }

注意

CreateKey 操作會建立作用中分支金鑰和信標金鑰，即使您尚未將資料庫設定為可搜尋加密。這兩個金鑰都存放在您的金鑰存放區中。如需詳細資訊，請參閱使用階層式 keyring 進行可搜尋加密。

接著，CreateKey操作會呼叫 kms:ReEncrypt，透過更新加密內容來建立分支金鑰的作用中記錄。

最後，CreateKey操作會呼叫 ddb：TransactWriteItems 來寫入新項目，該項目將保留您在步驟 2 中建立的資料表中的分支索引鍵。項目具有下列屬性。

{
	     "branch-key-id" : branch-key-id,
	     "type" : "branch:ACTIVE",
	     "enc" : the branch key returned by the GenerateDataKeyWithoutPlaintext call,
	     "version": "branch:version:the branch key version UUID",
	     "create-time" : "timestamp",
	     "kms-arn" : "the KMS key ARN you specified in Step 1",
	     "hierarchy-version" : "1",
	     "aws-crypto-ec:contextKey": "contextValue"
 }