翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# アクティブなブランチキーを作成する
<a name="create-branch-keys"></a>

*ブランチキー*は、 AWS KMS 階層キーリング AWS KMS key が呼び出しの数を減らすために使用する から派生したデータキーです AWS KMS。アクティブなブランチキーは、ブランチキーの最新バージョンです。階層キーリングは、暗号化リクエストごとに一意のデータキーを生成し、アクティブなブランチキーから派生した一意のラッピングキーを使用して各データキーを暗号化します。

新しいアクティブなブランチキーを作成するには、キーストアアクションを[静的に設定](keystore-actions.md#static-keystore)する必要があります。 `CreateKey`は、キーストアアクション設定で指定された KMS キー ARN をキーストア許可リストに追加する特権オペレーションです。次に、KMS キーを使用して新しいアクティブなブランチキーを生成します。KMS キーがキーストアに追加されると、削除できないため、このオペレーションへのアクセスを制限することをお勧めします。

アプリケーションのコントロールプレーンの KeyStore Admin インターフェイスを介して `CreateKey`オペレーションを使用することをお勧めします。このアプローチは、キー管理のベストプラクティスと一致しています。

データプレーンにブランチキーを作成しないでください。この方法により、次のような結果になる可能性があります。
+ への不要な呼び出し AWS KMS
+ 同時実行性の高い環境で AWS KMS の への複数の同時呼び出し
+ バッキング DynamoDB テーブルへの複数の TransactWriteItems 呼び出し。

`CreateKey` オペレーションには、既存のブランチキーが上書きされないように、`TransactWriteItems`呼び出しに条件チェックが含まれます。ただし、データプレーンでキーを作成すると、リソースの非効率的な使用やパフォーマンスの問題が発生する可能性があります。

キーストアで 1 つの KMS キーを許可リストに登録することも、キーストアアクション設定で指定した KMS キー ARN を更新して`CreateKey`再度 を呼び出すことで、複数の KMS キーを許可リストに登録することもできます。複数の KMS キーを許可リストに登録する場合、キーストアユーザーは、アクセスできるキーストアで任意の許可リストに登録されたキーを使用できるように、キーストアアクションを検出用に設定する必要があります。詳細については、「[キーストアアクションを設定する](keystore-actions.md)」を参照してください。

**必要な アクセス許可**  
ブランチキーを作成するには、キーストアアクションで指定された KMS キーに対する [kms:GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) および [kms:ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) アクセス許可が必要です。

**ブランチキーを作成する**  
次のオペレーションでは、キー[ストアアクション設定で指定した](keystore-actions.md#static-keystore) KMS キーを使用して新しいアクティブなブランチキーを作成し、キーストアとして機能する DynamoDB テーブルにアクティブなブランチキーを追加します。

`CreateKey` を呼び出す際に、次のオプションの値を指定することを選択できます。
+ `branchKeyIdentifier`: カスタム `branch-key-id` を定義します。

  カスタム `branch-key-id` を作成するには、`encryptionContext` パラメータに追加の暗号化コンテキストを含める必要もあります。
+ `encryptionContext`: は、[kms:GenerateDataKeyWithoutPlaintext ](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html)呼び出しに含まれる暗号化コンテキストで追加の認証データ (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\$1 / .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` オペレーションにより次の値が生成されます。
+ `branch-key-id` のバージョン 4 [Universally Unique Identifier](https://www.ietf.org/rfc/rfc4122.txt) (UUID) (カスタム `branch-key-id` を指定した場合を除く)。
+ ブランチキーバージョンのバージョン 4 UUID
+ [ISO 8601 の日時形式](https://www.iso.org/iso-8601-date-and-time-format.html)の `timestamp` (協定世界時 (UTC))。

その後、`CreateKey` オペレーションは次のリクエストを使用して [kms:GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) を呼び出します。

```
{
	    "EncryptionContext": { 
	       "branch-key-id" : "branch-key-id",
	       "type" : "type",
	       "create-time" : "timestamp",
	       "tablename" : "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"
	 }
```

**注記**  
[検索可能な暗号化](searchable-encryption.md)のためにデータベースを設定していない場合でも、`CreateKey` オペレーションはアクティブなブランチキーとビーコンキーを作成します。両方のキーはキーストアに保存されます。詳細については、「[検索可能な暗号化のための階層キーリングの使用](use-hierarchical-keyring.md#searchable-encryption-hierarchical-keyrings)」を参照してください。

次に、`CreateKey` オペレーションは [kms:ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/AAPI_ReEncrypt.html) を呼び出し、暗号化コンテキストを更新してブランチキーのアクティブレコードを作成します。

最後に、`CreateKey` オペレーションは [ddb:TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html) を呼び出して、**ステップ 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"
 }
```