建立作用中分支金鑰 - AWS Encryption SDK

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

建立作用中分支金鑰

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

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

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

所需的 許可

若要建立分支金鑰，您需要金鑰存放區動作中指定KMS金鑰的 kms：GenerateDataKeyWithoutPlaintext 和 kms：ReEncrypt 許可。

建立分支金鑰

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

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

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

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

  • encryptionContext：定義一組選用的非秘密金鑰值對，在 kms：GenerateDataKeyWithoutPlaintext call 中包含的加密內容中提供其他已驗證的資料 （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
	 });
Python
additional_encryption_context = {"Additional Encryption Context for": "custom branch key id"}

branch_key_id: str = keystore.create_key(
    CreateKeyInput(
        branch_key_identifier = "custom-branch-key-id", # OPTIONAL
        encryption_context = additional_encryption_context, # OPTIONAL
    )
)

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

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

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

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

然後， 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操作會呼叫 km：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"
 }