建立作用中分支金鑰 - AWS 資料庫加密 SDK

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

建立作用中分支金鑰

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

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

我們建議您透過應用程式控制平面中的 KeyStore Admin 界面使用 CreateKey操作。此方法符合金鑰管理的最佳實務。

請勿在資料平面中建立分支金鑰。此實務可能會導致：

  • 對 進行不必要的呼叫 AWS KMS

  • 在高並行環境中對 AWS KMS 的多個並行呼叫

  • 對後端 DynamoDB 資料表的多個 TransactWriteItems 呼叫。

CreateKey 操作會在TransactWriteItems呼叫中包含條件檢查，以防止覆寫現有的分支金鑰。不過，在資料平面中建立金鑰仍可能導致資源使用效率低下和潛在的效能問題。

您可以在金鑰存放區中允許列出一個 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操作會產生下列值。

然後， 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"
 }