As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Crie uma chave de ramificação ativa
Uma *chave de ramificação* é uma chave de dados derivada de uma AWS KMS key que o AWS KMS chaveiro hierárquico usa para reduzir o número de chamadas feitas. AWS KMS A chave de ramificação *ativa* é a versão mais recente da chave de ramificação. O chaveiro hierárquico gera uma chave de dados exclusiva para cada solicitação de criptografia e criptografa cada chave de dados com uma chave de empacotamento exclusiva derivada da chave de ramificação ativa.
Para criar uma nova chave de ramificação ativa, você deve [configurar estaticamente](keystore-actions.md#static-keystore) suas ações de armazenamento de chaves. `CreateKey`é uma operação privilegiada que adiciona o ARN da chave KMS especificado na configuração das ações do armazenamento de chaves à sua lista de permissões do armazenamento de chaves. Em seguida, a chave KMS é usada para gerar a nova chave de ramificação ativa. Recomendamos limitar o acesso a essa operação porque, depois que uma chave KMS é adicionada ao armazenamento de chaves, ela não pode ser excluída.
Recomendamos usar a `CreateKey` operação por meio da interface KeyStore Admin no plano de controle do seu aplicativo. Essa abordagem se alinha às melhores práticas de gerenciamento de chaves.
Não crie chaves de ramificação no plano de dados. Essa prática pode resultar em:
+ Chamadas desnecessárias para AWS KMS
+ Várias chamadas simultâneas para ambientes de alta AWS KMS simultaneidade
+ Várias TransactWriteItems chamadas para a tabela de apoio do DynamoDB.
A `CreateKey` operação inclui uma verificação de condição na `TransactWriteItems` chamada para evitar a substituição de chaves de ramificação existentes. No entanto, criar chaves no plano de dados ainda pode levar ao uso ineficiente de recursos e a possíveis problemas de desempenho.
Você pode colocar uma chave KMS na lista de permissões em seu armazenamento de chaves ou pode incluir várias chaves KMS na lista de permissões atualizando o ARN da chave KMS que você especificou na configuração de ações do armazenamento de chaves e chamando novamente. `CreateKey` Se você colocar várias chaves do KMS na lista de permissões, os usuários do armazenamento de chaves devem configurar suas ações de armazenamento de chaves para descoberta, de forma que possam usar qualquer uma das chaves da lista de permissões ao qual tenham acesso. Para obter mais informações, consulte [Configurar as principais ações do armazenamento](keystore-actions.md).
**Permissões obrigatórias**
Para criar chaves de ramificação, você precisa das ReEncrypt permissões [kms: GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) e [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) na chave KMS especificada nas ações do seu armazenamento de chaves.
**Crie uma chave de ramificação**
A operação a seguir cria uma nova chave de ramificação ativa usando a chave KMS que você [especificou na configuração de ações do armazenamento de chaves e adiciona a chave de ramificação ativa à tabela do DynamoDB que serve como seu](keystore-actions.md#static-keystore) armazenamento de chaves.
Ao chamar `CreateKey`, você pode optar por especificar os valores opcionais a seguir.
+ `branchKeyIdentifier`: define um `branch-key-id` personalizado.
Para criar um `branch-key-id` personalizado, você também deve incluir um contexto de criptografia adicional com o parâmetro `encryptionContext`.
+ `encryptionContext`[: define um conjunto opcional de pares chave-valor não secretos que fornecem dados autenticados adicionais (AAD) no contexto de criptografia incluído na chamada kms:. GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html)
Esse contexto de criptografia adicional é exibido com o prefixo `aws-crypto-ec:`.
------
#### [ Java ]
```
final Map 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();
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();
```
------
Primeiro, a operação `CreateKey` gera os valores a seguir.
+ Um [Identificador Único Universal](https://www.ietf.org/rfc/rfc4122.txt) (UUID) versão 4 para o `branch-key-id` (a menos que você tenha especificado um `branch-key-id` personalizado).
+ Um UUID da versão 4 para a versão da chave de ramificação
+ Um `timestamp` no [formato de data e hora ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) e em UTC (Tempo Universal Coordenado).
Em seguida, a `CreateKey` operação chama [kms: GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) usando a seguinte solicitação.
```
{
"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"
}
```
**nota**
A operação `CreateKey` cria uma chave de ramificação ativa e uma chave de beacon, mesmo que você não tenha configurado seu banco de dados para [criptografia pesquisável](searchable-encryption.md). Ambas as chaves são armazenadas em seu armazenamento de chaves. Para obter mais informações, consulte [Usar o token de autenticação hierárquico para criptografia pesquisável](use-hierarchical-keyring.md#searchable-encryption-hierarchical-keyrings).
Em seguida, a `CreateKey` operação chama [kms: ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/AAPI_ReEncrypt.html) para criar um registro ativo para a chave de ramificação atualizando o contexto de criptografia.
Por último, a `CreateKey` operação chama [ddb: TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html) para escrever um novo item que persistirá com a chave de ramificação na tabela que você criou na **Etapa** 2. O item tem os seguintes atributos:
```
{
"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"
}
```