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á.
# Tokens de autenticação
****
| |
| --- |
| Nossa biblioteca de criptografia do lado do cliente foi renomeada para SDK de criptografia de AWS banco de dados. Este guia do desenvolvedor ainda fornece informações sobre o [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
O SDK AWS de criptografia de banco de dados usa *chaveiros* para realizar a criptografia de [envelopes](concepts.md#envelope-encryption). Tokens de autenticação geram, criptografam e descriptografam chaves de dados. Os tokens de autenticação determinam a origem das chaves de dados exclusivas que protegem cada registro criptografado, bem como as [chaves de empacotamento](concepts.md#wrapping-key) que criptografam essa chave de dados. Você especifica um token de autenticação ao criptografar e especifica o mesmo ou outro token de autenticação ao descriptografar.
É possível usar cada token individualmente ou combiná-los em um [multitoken de autenticação](use-multi-keyring.md). Embora a maioria dos tokens de autenticação possa gerar, criptografar e descriptografar chaves de dados, você pode criar um que execute apenas uma operação, por exemplo, um token que gere apenas chaves de dados, e usá-lo em combinação com outros.
Recomendamos que você use um chaveiro que proteja suas chaves de agrupamento e execute operações criptográficas dentro de um limite seguro, como o AWS KMS chaveiro, que usa AWS KMS keys that never leave () sem criptografia. [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)AWS KMS Você também pode escrever um chaveiro que use chaves de agrupamento armazenadas em seus módulos de segurança de hardware (HSMs) ou protegidas por outros serviços de chave mestra.
O token de autenticação determina as chaves de encapsulamento que protegem as chaves de dados e, em última análise, os dados. Use as chaves de empacotamento mais seguras e práticas para sua tarefa. Sempre que possível, use chaves de empacotamento protegidas por um módulo de segurança de hardware (HSM) ou por uma infraestrutura de gerenciamento de chaves, como chaves do KMS em [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)(AWS KMS) ou chaves de criptografia em [AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/).
O SDK AWS de criptografia de banco de dados fornece vários chaveiros e configurações de chaveiros, e você pode criar seus próprios chaveiros personalizados. Você também pode criar um [multitoken de autenticação](use-multi-keyring.md) que inclua um ou mais tokens de autenticação do mesmo tipo ou de um tipo diferente.
**Topics**
+ [Como os tokens de autenticação funcionam](#using-keyrings)
+ [AWS KMS chaveiros](use-kms-keyring.md)
+ [AWS KMS Chaveiros hierárquicos](use-hierarchical-keyring.md)
+ [AWS KMS chaveiros ECDH](use-kms-ecdh-keyring.md)
+ [Tokens de autenticação AES Raw](use-raw-aes-keyring.md)
+ [Tokens de autenticação brutos do RSA](use-raw-rsa-keyring.md)
+ [Chaveiros ECDH brutos](use-raw-ecdh-keyring.md)
+ [Multitokens de autenticação](use-multi-keyring.md)
## Como os tokens de autenticação funcionam
****
| |
| --- |
| Nossa biblioteca de criptografia do lado do cliente foi renomeada para SDK de criptografia de AWS banco de dados. Este guia do desenvolvedor ainda fornece informações sobre o [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
Quando você criptografa e assina um campo em seu banco de dados, o SDK de criptografia AWS de banco de dados solicita materiais de criptografia ao chaveiro. O token de autenticação retorna uma chave de dados de texto simples e uma cópia da chave que é criptografada por cada uma das chaves de empacotamento no token de autenticação e uma chave MAC associada à chave de dados. O SDK AWS de criptografia de banco de dados usa a chave de texto simples para criptografar os dados e, em seguida, remove a chave de dados de texto sem formatação da memória assim que possível. Em seguida, o SDK de criptografia de banco de dados da AWS adiciona uma [descrição do material](concepts.md#material-description) que inclui as chaves de dados criptografadas e outras informações, como instruções de criptografia e assinatura. O SDK AWS de criptografia de banco de dados usa a chave MAC para calcular códigos de autenticação de mensagens baseados em hash (HMACs) por meio da canonização da descrição do material e de todos os campos marcados com ou. `ENCRYPT_AND_SIGN` `SIGN_ONLY`
Ao descriptografar dados, você pode usar o mesmo token de autenticação usado para criptografar os dados ou um diferente. Para descriptografar os dados, um token de autenticação de decodificação deve ter acesso a pelo menos uma chave de empacotamento no token de autenticação de criptografia.
O SDK AWS de criptografia de banco de dados passa as chaves de dados criptografadas da descrição do material para o chaveiro e solicita que o chaveiro decifre qualquer uma delas. O token de autenticação usa suas chaves de empacotamento para descriptografar uma das chaves de dados criptografadas e retorna uma chave de dados de texto simples. O SDK de criptografia de banco de dados da AWS usa a chave de dados em texto simples para descriptografar os dados. Se nenhuma das chaves de empacotamento no token de autenticação puder descriptografar qualquer uma das chaves de dados criptografadas, a operação de descriptografia falhará.
Você pode usar um único token de autenticação ou também combinar tokens de autenticação do mesmo ou outro tipo em um [multitoken de autenticação](use-multi-keyring.md). Quando você criptografa dados, o multitoken de autenticação retorna uma cópia da chave de dados criptografada por todas as chaves de empacotamento em todos os tokens de autenticação que compreendem o multitoken de autenticação e uma chave MAC associada à chave de dados. É possível descriptografar os dados usando um token de autenticação com qualquer uma das chaves de empacotamento do multitoken de autenticação.
# AWS KMS chaveiros
****
| |
| --- |
| Nossa biblioteca de criptografia do lado do cliente foi renomeada para SDK de criptografia de AWS banco de dados. Este guia do desenvolvedor ainda fornece informações sobre o [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
Um AWS KMS chaveiro usa criptografia simétrica ou RSA assimétrica [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)para gerar, criptografar e descriptografar chaves de dados. AWS Key Management Service (AWS KMS) protege suas chaves KMS e executa operações criptográficas dentro do limite do FIPS. Recomendamos que você use um AWS KMS chaveiro ou um chaveiro com propriedades de segurança semelhantes, sempre que possível.
Você também pode usar uma chave KMS multirregional simétrica em um chaveiro. AWS KMS Para obter mais detalhes e exemplos de uso de várias regiões AWS KMS keys, consulte[Usando várias regiões AWS KMS keys](#config-mrks). Para obter mais informações sobre chaves multirregionais, consulte [Usar chaves multirregionais](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) no *Guia do Desenvolvedor do AWS Key Management Service *.
AWS KMS os chaveiros podem incluir dois tipos de chaves de embrulho:
+ **Chave geradora**: gera uma chave de dados em texto simples e a criptografa. Um token de autenticação que criptografa dados deve ter uma chave geradora.
+ **Chaves adicionais**: criptografa a chave de dados em texto simples gerada pela chave do gerador. AWS KMS os chaveiros podem ter zero ou mais chaves adicionais.
Você deve ter uma chave geradora para criptografar registros. Quando um AWS KMS chaveiro tem apenas uma AWS KMS chave, essa chave é usada para gerar e criptografar a chave de dados.
Como todos os chaveiros, os AWS KMS chaveiros podem ser usados de forma independente ou em um [chaveiro múltiplo com outros chaveiros](use-multi-keyring.md) do mesmo tipo ou de um tipo diferente.
**Topics**
+ [Permissões necessárias para AWS KMS chaveiros](#kms-keyring-permissions)
+ [Identificação AWS KMS keys em um AWS KMS chaveiro](#kms-keyring-id)
+ [Criando um AWS KMS chaveiro](#kms-keyring-create)
+ [Usando várias regiões AWS KMS keys](#config-mrks)
+ [Usando um chaveiro AWS KMS Discovery](#kms-keyring-discovery)
+ [Usando um chaveiro de descoberta AWS KMS regional](#kms-keyring-regional)
## Permissões necessárias para AWS KMS chaveiros
O SDK AWS de criptografia de banco de dados não exige um Conta da AWS e não depende de nenhum AWS service (Serviço da AWS). No entanto, para usar um AWS KMS chaveiro, você precisa de uma Conta da AWS e das seguintes permissões mínimas AWS KMS keys no seu chaveiro.
+ Para criptografar com um AWS KMS chaveiro, você precisa da GenerateDataKey permissão [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) na chave do gerador. Você precisa da permissão [KMS:Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) em todas as chaves adicionais no chaveiro. AWS KMS
+ Para descriptografar com um AWS KMS chaveiro, você precisa da permissão [kms:Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) em pelo menos uma chave no chaveiro. AWS KMS
+ Para criptografar com um chaveiro múltiplo composto por AWS KMS chaveiros, você precisa da GenerateDataKey permissão [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) na chave do gerador no chaveiro do gerador. Você precisa da permissão [KMS:Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) em todas as outras chaves em todos os outros chaveiros. AWS KMS
+ Para criptografar com um AWS KMS chaveiro RSA assimétrico, você não precisa de [kms: GenerateDataKey ou [kms:Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html)](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) porque você deve especificar o material de chave pública que deseja usar para criptografia ao criar o chaveiro. Nenhuma AWS KMS chamada é feita ao criptografar com este chaveiro. [Para descriptografar com um AWS KMS chaveiro RSA assimétrico, você precisa da permissão KMS:Decrypt.](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
Para obter informações detalhadas sobre permissões para AWS KMS keys, consulte [Autenticação e controle de acesso](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html) no *Guia do AWS Key Management Service desenvolvedor*.
## Identificação AWS KMS keys em um AWS KMS chaveiro
Um AWS KMS chaveiro pode incluir um ou mais AWS KMS keys. Para especificar um AWS KMS key em um AWS KMS chaveiro, use um identificador de AWS KMS chave compatível. Os identificadores de chave que você pode usar para identificar um AWS KMS key em um chaveiro variam de acordo com a operação e a implementação da linguagem. Para obter detalhes sobre os identificadores de chave de uma AWS KMS key, consulte[Identificadores de chave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) no *Guia do Desenvolvedor do AWS Key Management Service *.
Como prática recomendada, use o identificador de chave mais específico que seja prático para sua tarefa.
+ [Para criptografar com um AWS KMS chaveiro, você pode usar um [ID de chave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id), [ARN de chave, nome de alias ou ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) de [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-name) para criptografar dados.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN)
**nota**
Se você especificar um nome de alias ou um ARN de alias para uma chave do KMS em um token de autenticação de criptografia, a operação de criptografia salvará o ARN de chave atualmente associado ao alias nos metadados da chave de dados criptografada. Isso não salva o alias. As alterações no alias não afetam a chave do KMS usada para descriptografar suas chaves de dados criptografadas.
+ Para decifrar com um AWS KMS chaveiro, você deve usar um ARN de chave para identificar. AWS KMS keys Para obter detalhes, consulte [Seleção de chaves de encapsulamento](configure.md#config-keys).
+ Em um token de autenticação usado para criptografia e descriptografia, você deve usar um ARN de chave para identificar AWS KMS keys.
Ao descriptografar, o SDK de criptografia AWS de banco de dados pesquisa no AWS KMS chaveiro uma AWS KMS key que possa descriptografar uma das chaves de dados criptografadas. Especificamente, o SDK AWS de criptografia de banco de dados usa o seguinte padrão para cada chave de dados criptografada na descrição do material.
+ O SDK AWS de criptografia de banco de dados obtém o ARN da chave que criptografou AWS KMS key a chave de dados a partir dos metadados da descrição do material.
+ O SDK AWS de criptografia de banco de dados pesquisa no chaveiro de descriptografia por um ARN com AWS KMS key uma chave correspondente.
+ Se encontrar um ARN AWS KMS key com uma chave correspondente no chaveiro, o SDK de criptografia de AWS banco de dados solicitará o uso da chave KMS AWS KMS para descriptografar a chave de dados criptografada.
+ Caso contrário, ele passará para a próxima chave de dados criptografada, se houver.
## Criando um AWS KMS chaveiro
Você pode configurar cada AWS KMS chaveiro com um único AWS KMS key ou vários AWS KMS keys no mesmo ou em diferentes Contas da AWS e. Regiões da AWS O AWS KMS key deve ser uma chave de criptografia simétrica (`SYMMETRIC_DEFAULT`) ou uma chave RSA KMS assimétrica. Também é possível usar uma [chave KMS multirregional](#config-mrks) criptografia simétrica. Você pode usar um ou mais AWS KMS chaveiros em um chaveiro [múltiplo](use-multi-keyring.md).
Você pode criar um AWS KMS chaveiro que criptografe e descriptografe dados, ou você pode criar AWS KMS chaveiros especificamente para criptografar ou descriptografar. Ao criar um AWS KMS chaveiro para criptografar dados, você deve especificar uma *chave geradora*, AWS KMS key que é usada para gerar uma chave de dados em texto simples e criptografá-la. A chave de dados não tem relação matemática com a chave KMS. Em seguida, se quiser, você pode especificar outras AWS KMS keys que criptografem a mesma chave de dados de texto sem formatação. Para descriptografar um campo criptografado protegido por esse chaveiro, o chaveiro de decodificação que você usa deve incluir pelo menos um dos definidos no chaveiro, ou não. AWS KMS keys AWS KMS keys(Um AWS KMS chaveiro sem AWS KMS keys é conhecido como [chaveiro AWS KMS Discovery](#kms-keyring-discovery).)
Todas as chaves empacotadas em um token de autenticação de criptografia ou em vários tokens de autenticação devem ser capazes de criptografar a chave de dados. Se alguma chave de empacotamento falhar na criptografia, o método de criptografia falhará. Como resultado, o chamador deve ter as [permissões necessárias](#kms-keyring-permissions) para todas as chaves no token de autenticação. Se você usar um token de autenticação para criptografar dados, sozinho ou em um token de autenticação múltiplo, a operação de criptografia falhará.
Os exemplos a seguir usam o `CreateAwsKmsMrkMultiKeyring` método para criar um AWS KMS chaveiro com uma chave KMS de criptografia simétrica. O `CreateAwsKmsMrkMultiKeyring` método cria automaticamente o AWS KMS cliente e garante que o chaveiro manipule corretamente as chaves de região única e multirregião. Esses exemplos usam uma [chave ARNs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) para identificar as chaves KMS. Para obter detalhes, consulte [Identificação AWS KMS keys em um AWS KMS chaveiro](#kms-keyring-id)
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyArn)
.build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createAwsKmsMrkMultiKeyringInput = new CreateAwsKmsMrkMultiKeyringInput
{
Generator = kmsKeyArn
};
var awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ Rust ]
```
let provider_config = MaterialProvidersConfig::builder().build()?;
let mat_prov = client::Client::from_conf(provider_config)?;
let kms_keyring = mat_prov
.create_aws_kms_mrk_multi_keyring()
.generator(kms_key_id)
.send()
.await?;
```
------
Os exemplos a seguir usam o `CreateAwsKmsRsaKeyring` método para criar um AWS KMS chaveiro com uma chave RSA KMS assimétrica. Para criar um AWS KMS chaveiro RSA assimétrico, forneça os seguintes valores.
+ `kmsClient`: criar um novo AWS KMS cliente
+ `kmsKeyID`: o ARN da chave que identifica sua chave RSA KMS assimétrica
+ `publicKey`: a ByteBuffer de um arquivo PEM codificado em UTF-8 que representa a chave pública da chave para a qual você passou `kmsKeyID`
+ `encryptionAlgorithm`: o algoritmo de criptografia deve ser `RSAES_OAEP_SHA_256` ou `RSAES_OAEP_SHA_1`
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsRsaKeyringInput createAwsKmsRsaKeyringInput =
CreateAwsKmsRsaKeyringInput.builder()
.kmsClient(KmsClient.create())
.kmsKeyId(rsaKMSKeyArn)
.publicKey(publicKey)
.encryptionAlgorithm(EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256)
.build();
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createAwsKmsRsaKeyringInput = new CreateAwsKmsRsaKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = rsaKMSKeyArn,
PublicKey = publicKey,
EncryptionAlgorithm = EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256
};
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_rsa_keyring = mpl
.create_aws_kms_rsa_keyring()
.kms_key_id(rsa_kms_key_arn)
.public_key(public_key)
.encryption_algorithm(aws_sdk_kms::types::EncryptionAlgorithmSpec::RsaesOaepSha256)
.kms_client(aws_sdk_kms::Client::new(&sdk_config))
.send()
.await?;
```
------
## Usando várias regiões AWS KMS keys
Você pode usar a multirregião AWS KMS keys como chaves de encapsulamento no SDK de criptografia de AWS banco de dados. Se você criptografar com uma chave multirregional em uma Região da AWS, poderá descriptografar usando uma chave multirregional relacionada em outra. Região da AWS
As chaves KMS multirregionais são um conjunto de AWS KMS keys chaves diferentes Regiões da AWS que têm o mesmo material de chave e ID de chave. É possível usar essas chaves *relacionadas* como se fossem a mesma chave em regiões diferentes. As chaves multirregionais oferecem suporte a cenários comuns de recuperação de desastres e backup que exigem criptografia em uma região e descriptografia em uma região diferente sem fazer uma chamada entre regiões para. AWS KMS Para obter mais informações sobre chaves multirregionais, consulte [Usar chaves multirregionais](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) no *Guia do Desenvolvedor do AWS Key Management Service *.
Para oferecer suporte a chaves multirregionais, o SDK AWS de criptografia de banco de dados inclui AWS KMS multi-Region-aware chaveiros. O método `CreateAwsKmsMrkMultiKeyring` oferece suporte a chaves de região única e de várias regiões.
+ Para chaves de região única, o multi-Region-aware símbolo se comporta exatamente como o chaveiro de região única. AWS KMS Ele tenta descriptografar o texto cifrado somente com a chave de região única que criptografou os dados. Para simplificar sua experiência com o AWS KMS chaveiro, recomendamos usar o `CreateAwsKmsMrkMultiKeyring` método sempre que você usar uma chave KMS de criptografia simétrica.
+ Para chaves multirregionais, o multi-Region-aware símbolo tenta descriptografar o texto cifrado com a mesma chave multirregional que criptografou os dados ou com a chave multirregional relacionada na região especificada.
Nos multi-Region-aware chaveiros que usam mais de uma chave KMS, você pode especificar várias chaves de região única e multirregião. No entanto, é possível especificar somente uma chave de cada conjunto de chaves de várias regiões relacionadas. Se você especificar mais de um identificador de chave com o mesmo ID de chave, a chamada do construtor falhará.
Os exemplos a seguir criam um AWS KMS chaveiro com uma chave KMS multirregional. Os exemplos especificam uma chave multirregional como chave geradora e uma chave de região única como chave secundária.
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMrkMultiKeyringInput createAwsKmsMrkMultiKeyringInput =
CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(multiRegionKeyArn)
.kmsKeyIds(Collections.singletonList(kmsKeyArn))
.build();
IKeyring awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createAwsKmsMrkMultiKeyringInput = new CreateAwsKmsMrkMultiKeyringInput
{
Generator = multiRegionKeyArn,
KmsKeyIds = new List { kmsKeyArn }
};
var awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let aws_kms_mrk_multi_keyring = mpl
.create_aws_kms_mrk_multi_keyring()
.generator(multiRegion_key_arn)
.kms_key_ids(vec![key_arn.to_string()])
.send()
.await?;
```
------
Ao usar AWS KMS chaveiros multirregionais, você pode descriptografar texto cifrado no modo estrito ou no modo de descoberta. Para descriptografar o texto cifrado no modo estrito, instancie o símbolo multi-Region-aware com o ARN da chave multirregional relacionada na região em que você está descriptografando o texto cifrado. Se você especificar o ARN da chave de uma chave multirregional relacionada em uma região diferente (por exemplo, a região em que o registro foi criptografado), o multi-Region-aware símbolo fará uma chamada entre regiões para isso. AWS KMS key
Ao descriptografar no modo estrito, o multi-Region-aware símbolo requer uma chave ARN. Ele aceita somente um ARN de chave de cada conjunto de chaves de várias regiões relacionadas.
Também é possível descriptografar no *modo de descoberta* com chaves do AWS KMS multirregionais. Ao descriptografar no modo de descoberta, você não especifica nenhuma AWS KMS keys. (Para obter informações sobre chaveiros de AWS KMS descoberta de uma única região, consulte[Usando um chaveiro AWS KMS Discovery](#kms-keyring-discovery).)
Se você criptografou com uma chave multirregional, o multi-Region-aware símbolo no modo de descoberta tentará descriptografar usando uma chave multirregional relacionada na região local. Se não existir nenhuma, a chamada falhará. No modo de descoberta, o SDK AWS de criptografia de banco de dados não tentará fazer uma chamada entre regiões para a chave multirregional usada para criptografia.
## Usando um chaveiro AWS KMS Discovery
Ao descriptografar, é uma prática recomendada especificar as chaves de encapsulamento que o SDK de criptografia de AWS banco de dados pode usar. Para seguir essa prática recomendada, use um chaveiro de AWS KMS decodificação que limite as chaves de AWS KMS encapsulamento às que você especificar. No entanto, você também pode criar um *chaveiro de AWS KMS descoberta*, ou seja, um AWS KMS chaveiro que não especifique nenhuma chave de agrupamento.
O SDK AWS de criptografia de banco de dados fornece um chaveiro de AWS KMS descoberta padrão e um chaveiro de descoberta para AWS KMS chaves multirregionais. Para obter informações sobre como usar chaves de várias regiões com o SDK de criptografia de banco de dados da AWS , consulte [Usando várias regiões AWS KMS keys](#config-mrks).
Como ele não especifica nenhuma chave de empacotamento, um token de autenticação de descoberta não pode criptografar dados. Se você usar um token de autenticação para criptografar dados, sozinho ou em um token de autenticação múltiplo, a operação de criptografia falhará.
Ao descriptografar, um chaveiro de descoberta permite que o SDK de criptografia AWS de banco de dados solicite AWS KMS a decodificação de qualquer chave de dados criptografada usando AWS KMS key aquela que a criptografou, independentemente de quem a possui ou tem acesso a ela. AWS KMS key A chamada será bem-sucedida somente quando o chamador tiver a permissão `kms:Decrypt` na AWS KMS key.
**Importante**
Se você incluir um chaveiro de AWS KMS descoberta em um chaveiro de descriptografia [múltiplo, o chaveiro](use-multi-keyring.md) de descoberta substituirá todas as restrições de chave KMS especificadas por outros chaveiros no chaveiro múltiplo. O token de autenticação múltiplo se comporta como o token de autenticação menos restritivo. Se você usar um token de autenticação de descoberta para criptografar dados, sozinho ou em um token de autenticação múltiplo, a operação de criptografia falhará
O SDK AWS de criptografia de banco de dados fornece um chaveiro de AWS KMS descoberta para sua conveniência. No entanto, recomendamos que você use um token de autenticação mais limitado sempre que possível pelas razões a seguir.
+ **Autenticidade** — Um chaveiro de AWS KMS descoberta pode usar qualquer AWS KMS key chave usada para criptografar uma chave de dados na descrição do material, desde que o chamador tenha permissão para usá-la para descriptografar. AWS KMS key Isso pode não ser o AWS KMS key que o chamador pretende usar. Por exemplo, uma das chaves de dados criptografadas pode ter sido criptografada de forma menos segura AWS KMS key que qualquer pessoa possa usar.
+ **Latência e desempenho** — Um chaveiro de AWS KMS descoberta pode ser visivelmente mais lento do que outros chaveiros porque o SDK de criptografia de AWS banco de dados tenta descriptografar todas as chaves de dados criptografadas, incluindo aquelas criptografadas por AWS KMS keys outras regiões Contas da AWS e AWS KMS keys que o chamador não tem permissão para usar para descriptografia.
[Se você usa um chaveiro de descoberta, recomendamos que você use um [*filtro de descoberta*](configure.md#config-discovery) para limitar as chaves KMS que podem ser usadas para aquelas em partições Contas da AWS e partições especificadas.](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) Para obter ajuda para encontrar seu ID de conta e partição, consulte [Seus Conta da AWS identificadores](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html) e formato [ARN no. *Referência geral da AWS*](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax)
Os exemplos de código a seguir instanciam um chaveiro de AWS KMS descoberta com um filtro de descoberta que limita as chaves KMS que o SDK de criptografia AWS de banco de dados pode usar às da partição e da `aws` conta de exemplo. `111122223333`
Antes de usar esse código, substitua os valores de exemplo Conta da AWS e de partição por valores válidos para sua partição Conta da AWS e. Se as chaves do KMS estiverem em regiões da China, use o valor de partição `aws-cn`. Se as chaves do KMS estiverem em AWS GovCloud (US) Regions, use o valor de partição `aws-us-gov`. Para todas as outras Regiões da AWS, use o valor de partição `aws`.
------
#### [ Java ]
```
// Create discovery filter
DiscoveryFilter discoveryFilter = DiscoveryFilter.builder()
.partition("aws")
.accountIds(111122223333)
.build();
// Create the discovery keyring
CreateAwsKmsMrkDiscoveryMultiKeyringInput createAwsKmsMrkDiscoveryMultiKeyringInput = CreateAwsKmsMrkDiscoveryMultiKeyringInput.builder()
.discoveryFilter(discoveryFilter)
.build();
IKeyring decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
// Create discovery filter
var discoveryFilter = new DiscoveryFilter
{
Partition = "aws",
AccountIds = 111122223333
};
// Create the discovery keyring
var createAwsKmsMrkDiscoveryMultiKeyringInput = new CreateAwsKmsMrkDiscoveryMultiKeyringInput
{
DiscoveryFilter = discoveryFilter
};
var decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ Rust ]
```
// Create discovery filter
let discovery_filter = DiscoveryFilter::builder()
.partition("aws")
.account_ids(111122223333)
.build()?;
// Create the discovery keyring
let decrypt_keyring = mpl
.create_aws_kms_mrk_discovery_multi_keyring()
.discovery_filter(discovery_filter)
.send()
.await?;
```
------
## Usando um chaveiro de descoberta AWS KMS regional
Um *chaveiro de descoberta AWS KMS regional* é um chaveiro que não especifica as chaves ARNs KMS. Em vez disso, ele permite que o SDK AWS de criptografia de banco de dados seja descriptografado usando somente as chaves KMS em particular. Regiões da AWS
Ao descriptografar com um chaveiro de descoberta AWS KMS regional, o SDK de criptografia de AWS banco de dados descriptografa qualquer chave de dados criptografada que tenha sido criptografada de acordo com um no especificado. AWS KMS key Região da AWS Para ter sucesso, o chamador deve ter `kms:Decrypt` permissão em pelo menos um dos AWS KMS keys itens especificados Região da AWS que criptografou uma chave de dados.
Como outros tokens de autenticação de descoberta, o token de autenticação de descoberta regional não tem efeito na criptografia. Ele funciona somente ao descriptografar campos criptografados. Se você usar um token de autenticação de descoberta regional em um token de autenticação múltiplo usado para criptografar e descriptografar, ele só será efetivo durante a descriptografia. Se você usar um token de autenticação de descoberta multirregional para criptografar dados, sozinho ou em um token de autenticação com vários tokens de autenticação, a operação de criptografia falhará.
**Importante**
Se você incluir um chaveiro de descoberta AWS KMS regional em um chaveiro de descriptografia [múltiplo, o chaveiro](use-multi-keyring.md) de descoberta regional substituirá todas as restrições de chave KMS especificadas por outros chaveiros no chaveiro múltiplo. O token de autenticação múltiplo se comporta como o token de autenticação menos restritivo. Um token de autenticação de descoberta do AWS KMS não tem efeito na criptografia quando usado sozinho ou em um multitoken de autenticação.
O chaveiro de descoberta regional no SDK AWS de criptografia de banco de dados tenta descriptografar somente com chaves KMS na região especificada. Ao usar um chaveiro de descoberta, você configura a região no AWS KMS cliente. Essas implementações do SDK de criptografia de AWS banco de dados não filtram as chaves do KMS por região, mas AWS KMS falharão na solicitação de descriptografia das chaves do KMS fora da região especificada.
Se você usa um chaveiro de descoberta, recomendamos que você use um *filtro de descoberta* para limitar as chaves KMS usadas na descriptografia àquelas em partições e partições especificadas. Contas da AWS
Por exemplo, o código a seguir cria um chaveiro de descoberta AWS KMS regional com um filtro de descoberta. Esse chaveiro limita o SDK AWS de criptografia de banco de dados às chaves KMS na conta 111122223333 na região Oeste dos EUA (Oregon) (us-west-2).
------
#### [ Java ]
```
// Create the discovery filter
DiscoveryFilter discoveryFilter = DiscoveryFilter.builder()
.partition("aws")
.accountIds(111122223333)
.build();
// Create the discovery keyring
CreateAwsKmsMrkDiscoveryMultiKeyringInput createAwsKmsMrkDiscoveryMultiKeyringInput = CreateAwsKmsMrkDiscoveryMultiKeyringInput.builder()
.discoveryFilter(discoveryFilter)
.regions("us-west-2")
.build();
IKeyring decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
// Create discovery filter
var discoveryFilter = new DiscoveryFilter
{
Partition = "aws",
AccountIds = 111122223333
};
// Create the discovery keyring
var createAwsKmsMrkDiscoveryMultiKeyringInput = new CreateAwsKmsMrkDiscoveryMultiKeyringInput
{
DiscoveryFilter = discoveryFilter,
Regions = us-west-2
};
var decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ Rust ]
```
// Create discovery filter
let discovery_filter = DiscoveryFilter::builder()
.partition("aws")
.account_ids(111122223333)
.build()?;
// Create the discovery keyring
let decrypt_keyring = mpl
.create_aws_kms_mrk_discovery_multi_keyring()
.discovery_filter(discovery_filter)
.regions(us-west-2)
.send()
.await?;
```
------
# AWS KMS Chaveiros hierárquicos
****
| |
| --- |
| Nossa biblioteca de criptografia do lado do cliente foi renomeada para SDK de criptografia de AWS banco de dados. Este guia do desenvolvedor ainda fornece informações sobre o [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
**nota**
Em 24 de julho de 2023, as chaves de ramificação criadas durante a versão prévia para desenvolvedores não são compatíveis. Crie novas chaves de ramificação para continuar usando o armazenamento de chaves que você criou durante a versão prévia para desenvolvedores.
Com o AWS KMS chaveiro hierárquico, você pode proteger seus materiais criptográficos com uma chave KMS de criptografia simétrica sem ligar AWS KMS toda vez que criptografar ou descriptografar um registro. É uma boa opção para aplicativos que precisam minimizar as chamadas e aplicativos que podem reutilizar alguns materiais criptográficos sem violar seus requisitos de segurança. AWS KMS
O chaveiro hierárquico é uma solução de armazenamento em cache de materiais criptográficos que reduz o número de AWS KMS chamadas usando *chaves de ramificação AWS KMS * protegidas persistentes em uma tabela do Amazon DynamoDB e, em seguida, armazenando localmente em cache materiais de chave de ramificação usados em operações de criptografia e descriptografia. A tabela do DynamoDB serve como o armazenamento de chaves que gerencia e protege as chaves de ramificação. Ele armazena a chave de ramificação ativa e todas as versões anteriores da chave de ramificação. A chave de ramificação *ativa* é a versão mais recente da chave de ramificação. O chaveiro hierárquico usa uma chave de criptografia de dados exclusiva para cada solicitação de criptografia e criptografa cada chave de criptografia de dados com uma chave de empacotamento exclusiva derivada da chave de ramificação ativa. O token de autenticação hierárquico depende da hierarquia estabelecida entre as chaves de ramificação ativas e suas chaves de agrupamento derivadas.
O token de autenticação hierárquico normalmente usa cada versão da chave de ramificação para atender a várias solicitações. Porém, você controla até que ponto as chaves de ramificação ativas são reutilizadas e determina com que frequência a chave de ramificação ativa é alternada. A versão ativa da chave de ramificação permanece ativa até que você [a alterne](rotate-branch-key.md). As versões anteriores da chave de ramificação ativa não serão usadas para realizar operações de criptografia, mas ainda podem ser consultadas e usadas em operações de descriptografia.
Quando você instancia o token de autenticação hierárquico, ele cria um cache local. Você especifica um [limite de cache](#cache-limit) que define o tempo máximo em que os materiais da chave de ramificação são armazenados no cache local antes de expirarem e serem despejados do cache. O chaveiro hierárquico faz uma AWS KMS chamada para descriptografar a chave de ramificação e montar os materiais da chave de ramificação na primeira vez em que a é especificado em uma `branch-key-id` operação. Em seguida, os materiais da chave de ramificação são armazenados no cache local e reutilizados para todas as operações de criptografia e descriptografia que especificam `branch-key-id` até que o limite do cache expire. Armazenar materiais de chave de filial no cache local reduz AWS KMS as chamadas. Por exemplo, considere um limite de cache de 15 minutos. Se você realizar 10.000 operações de criptografia dentro desse limite de cache, o [AWS KMS chaveiro tradicional](use-kms-keyring.md) precisaria fazer 10.000 AWS KMS chamadas para satisfazer 10.000 operações de criptografia. Se você tiver um ativo`branch-key-id`, o chaveiro hierárquico só precisará fazer uma AWS KMS chamada para satisfazer 10.000 operações de criptografia.
O cache local separa os materiais de criptografia dos materiais de decodificação. Os materiais de criptografia são reunidos a partir da chave de ramificação ativa e reutilizados em todas as operações de criptografia até que o limite de cache expire. Os materiais de descriptografia são reunidos a partir do ID e da versão da chave de ramificação identificados nos metadados do campo criptografado e são reutilizados para todas as operações de descriptografia relacionadas ao ID e à versão da chave de ramificação até que o limite de cache expire. O cache local pode armazenar várias versões da mesma chave de ramificação ao mesmo tempo. Quando o cache local é configurado para usar um[branch key ID supplier](#branch-key-id-supplier), ele também pode armazenar materiais de chave de ramificação de várias chaves de ramificação ativas ao mesmo tempo.
**nota**
Todas as menções ao *chaveiro hierárquico no SDK de criptografia de AWS banco de dados se referem ao chaveiro* hierárquico. AWS KMS
**Topics**
+ [Como funciona](#how-hierarchical-keyring-works)
+ [Pré-requisitos](#hierarchical-keyring-prereqs)
+ [Permissões obrigatórias](#hierarchical-keyring-permissions)
+ [Escolha um cache](#hierarchical-keyring-caches)
+ [Criar um token de autenticação hierárquico](#initialize-hierarchical-keyring)
+ [Uso do token de autenticação hierárquico para criptografia pesquisável](#searchable-encryption-hierarchical-keyrings)
## Como funciona
As instruções a seguir descrevem como o token de autenticação hierárquico reúne materiais de criptografia e descriptografia e as diferentes chamadas que o token de autenticação faz para operações de criptografia e descriptografia. Para obter detalhes técnicos sobre a derivação da chave de empacotamento e os processos de criptografia da chave de dados em texto simples, consulte [Detalhes técnicos do token de autenticação hierárquico do AWS KMS](reference.md#hierarchical-keyring-details).
**Criptografar e assinar**
O passo a passo a seguir descreve como o token de autenticação hierárquico reúne materiais de criptografia e obtém uma chave de empacotamento exclusiva.
1. O método de criptografia solicita materiais de criptografia ao token de autenticação hierárquico. O chaveiro gera uma chave de dados em texto simples e, em seguida, verifica se há materiais de chave de ramificação válidos no cache local para gerar a chave de empacotamento. Se houver materiais de chave de filial válidos, o chaveiro prossegue para a **Etapa** 4.
1. Se não houver materiais de chave de ramificação válidos, o chaveiro hierárquico consulta o armazenamento de chaves em busca da chave de ramificação ativa.
1. O armazenamento de chaves faz chamadas AWS KMS para descriptografar a chave de ramificação ativa e retorna a chave de ramificação ativa em texto simples. Os dados que identificam a chave de ramificação ativa são serializados para fornecer dados autenticados adicionais (AAD) na chamada de descriptografia para o AWS KMS.
1. O armazenamento de chaves retorna a chave de ramificação em texto simples e os dados que a identificam, como a versão da chave de ramificação.
1. O token de autenticação hierárquico reúne materiais de chave de ramificação (a chave de ramificação em texto simples e a versão da chave de ramificação) e armazena uma cópia deles no cache local.
1. O token de autenticação hierárquico deriva uma chave de empacotamento exclusiva da chave de ramificação de texto simples e um sal aleatório de 16 bytes. Ele usa a chave de empacotamento derivada para criptografar uma cópia da chave de dados em texto simples.
O método de criptografia usa os materiais de criptografia para criptografar e assinar o registro. Para obter mais informações sobre como os registros são criptografados e assinados no SDK de criptografia de banco de dados da AWS , consulte [Criptografar e assinar](how-it-works.md#encrypt-and-sign).
**Descriptografar e verificar**
O passo a passo a seguir descreve como o token de autenticação hierárquico reúne materiais de decodificação e decifra a chave de dados criptografada.
1. O método de descriptografia identifica a chave de dados criptografada no campo de descrição do material do registro criptografado e a passa para o token de autenticação hierárquico.
1. O token de autenticação hierárquico desserializa os dados que identificam a chave de dados criptografada, incluindo a versão da chave de ramificação, o sal de 16 bytes e outras informações que descrevem como a chave de dados foi criptografada.
Para obter mais informações, consulte [AWS KMS Detalhes técnicos do chaveiro hierárquico](reference.md#hierarchical-keyring-details).
1. O token de autenticação hierárquico verifica se há materiais de chave de ramificação válidos no cache local que correspondam à versão da chave de ramificação identificada na **Etapa 2**. Se houver materiais de chave de ramificação válidos, o token de autenticação prosseguirá para a **Etapa 6** .
1. **Se não houver materiais de chave de ramificação válidos, o chaveiro hierárquico consulta o armazenamento de chaves em busca da chave de ramificação que corresponde à versão da chave de ramificação identificada na Etapa 2.**
1. O armazenamento de chaves faz chamadas AWS KMS para descriptografar a chave de ramificação e retorna a chave de ramificação ativa em texto simples. Os dados que identificam a chave de ramificação ativa são serializados para fornecer dados autenticados adicionais (AAD) na chamada de descriptografia para o AWS KMS.
1. O armazenamento de chaves retorna a chave de ramificação em texto simples e os dados que a identificam, como a versão da chave de ramificação.
1. O token de autenticação hierárquico reúne materiais de chave de ramificação (a chave de ramificação em texto simples e a versão da chave de ramificação) e armazena uma cópia deles no cache local.
1. O token de autenticação hierárquico usa os materiais de chave de ramificação montados e o sal de 16 bytes identificado na **Etapa 2** para reproduzir a chave de empacotamento exclusiva que criptografou a chave de dados.
1. O token de autenticação hierárquico usa a chave de empacotamento reproduzida para descriptografar a chave de dados e retorna a chave de dados em texto simples.
O método de decodificação usa os materiais de decodificação e a chave de dados de texto simples para descriptografar e verificar o registro. [Para obter mais informações sobre como os registros são descriptografados e verificados no SDK de criptografia de AWS banco de dados, consulte Descriptografar e verificar.](how-it-works.md#decrypt-and-verify)
## Pré-requisitos
Antes de criar e usar um chaveiro hierárquico, verifique se os seguintes pré-requisitos foram atendidos.
+ Você, ou o administrador do armazenamento de chaves, [criou um armazenamento de chaves](create-keystore.md) e [criou pelo menos uma chave de ramificação ativa](create-branch-keys.md).
+ Você [configurou suas principais ações de armazenamento](keystore-actions.md#config-keystore-actions).
**nota**
A forma como você configura suas ações de armazenamento de chaves determina quais operações você pode realizar e quais chaves KMS o chaveiro hierárquico pode usar. Para obter mais informações, consulte [Principais ações do armazenamento](keystore-actions.md).
+ Você tem as AWS KMS permissões necessárias para acessar e usar as chaves de armazenamento de chaves e de ramificação. Para obter mais informações, consulte [Permissões obrigatórias](#hierarchical-keyring-permissions).
+ Você analisou os tipos de cache compatíveis e configurou o tipo de cache que melhor atende às suas necessidades. Para obter mais informações, consulte [Escolha um cache](#hierarchical-keyring-caches).
## Permissões obrigatórias
O SDK AWS de criptografia de banco de dados não exige um Conta da AWS e não depende de nenhum AWS service (Serviço da AWS). No entanto, para usar um chaveiro hierárquico, você precisa de uma Conta da AWS e das seguintes permissões mínimas sobre a (s) criptografia AWS KMS key(s) simétrica (s) em seu armazenamento de chaves.
+ [Para criptografar e descriptografar dados com o chaveiro hierárquico, você precisa do KMS:Decrypt.](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
+ Para [criar](create-branch-keys.md) e [girar chaves de](rotate-branch-key.md) ramificação, você precisa de [kms: GenerateDataKeyWithoutPlaintext e [kms](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html):](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html). ReEncrypt
Para obter mais informações sobre como controlar o acesso às chaves da filial e ao armazenamento de chaves, consulte[Implementação de permissões de privilégio mínimo](keystore-least-privilege.md).
## Escolha um cache
O chaveiro hierárquico reduz o número de chamadas feitas ao AWS KMS armazenar em cache localmente os materiais de chave de ramificação usados nas operações de criptografia e descriptografia. Antes de [criar seu chaveiro hierárquico](#initialize-hierarchical-keyring), você precisa decidir que tipo de cache deseja usar. Você pode usar o cache padrão ou personalizar o cache para melhor atender às suas necessidades.
O chaveiro hierárquico suporta os seguintes tipos de cache:
+ [Cache padrão](#cache-default)
+ [MultiThreaded cache](#cache-multithreaded)
+ [StormTracking cache](#cache-stormtracking)
+ [Cache compartilhado](#cache-shared)
### Cache padrão
Para a maioria dos usuários, o cache Default atende aos requisitos de segmentação. O cache Default foi projetado para oferecer suporte a ambientes com muitos threads. Quando uma entrada de materiais de chave de ramificação expira, o cache padrão impede que vários segmentos sejam chamados, AWS KMS notificando um segmento de que a entrada de materiais de chave de ramificação expirará com 10 segundos de antecedência. Isso garante que somente um thread envie uma solicitação AWS KMS para atualizar o cache.
O padrão e StormTracking os caches oferecem suporte ao mesmo modelo de segmentação, mas você só precisa especificar a capacidade de entrada para usar o cache padrão. Para personalizações de cache mais granulares, use o. [StormTracking cache](#cache-stormtracking)
A menos que você queira personalizar o número de entradas de materiais de chave de ramificação que podem ser armazenadas no cache local, você não precisa especificar um tipo de cache ao criar o chaveiro hierárquico. Se você não especificar um tipo de cache, o chaveiro hierárquico usa o tipo de cache padrão e define a capacidade de entrada como 1000.
Para personalizar o cache padrão, especifique os seguintes valores:
+ **Capacidade de entrada**: limita o número de entradas de materiais de chave da ramificação que podem ser armazenadas no cache local.
------
#### [ Java ]
```
.cache(CacheType.builder()
.Default(DefaultCache.builder()
.entryCapacity(100)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType defaultCache = new CacheType
{
Default = new DefaultCache{EntryCapacity = 100}
};
```
------
#### [ Rust ]
```
let cache: CacheType = CacheType::Default(
DefaultCache::builder()
.entry_capacity(100)
.build()?,
);
```
------
### MultiThreaded cache
O MultiThreaded cache é seguro para uso em ambientes com vários processos, mas não fornece nenhuma funcionalidade para minimizar as chamadas do Amazon AWS KMS DynamoDB. Como resultado, quando uma entrada de materiais de chave de ramificação expirar, todos os tópicos serão notificados ao mesmo tempo. Isso pode resultar em várias AWS KMS chamadas para atualizar o cache.
Para usar o MultiThreaded cache, especifique os seguintes valores:
+ **Capacidade de entrada**: limita o número de entradas de materiais de chave da ramificação que podem ser armazenadas no cache local.
+ **Tamanho de entrada de limpeza de tail**: define o número de entradas a serem limpas se a capacidade de entrada for atingida.
------
#### [ Java ]
```
.cache(CacheType.builder()
.MultiThreaded(MultiThreadedCache.builder()
.entryCapacity(100)
.entryPruningTailSize(1)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType multithreadedCache = new CacheType
{
MultiThreaded = new MultiThreadedCache
{
EntryCapacity = 100,
EntryPruningTailSize = 1
}
};
```
------
#### [ Rust ]
```
CacheType::MultiThreaded(
MultiThreadedCache::builder()
.entry_capacity(100)
.entry_pruning_tail_size(1)
.build()?)
```
------
### StormTracking cache
O StormTracking cache foi projetado para suportar ambientes altamente multisegmentados. Quando uma entrada de materiais de chave de ramificação expira, o StormTracking cache impede que vários segmentos sejam chamados AWS KMS notificando um segmento de que a entrada de materiais de chave de ramificação expirará com antecedência. Isso garante que somente um thread envie uma solicitação AWS KMS para atualizar o cache.
Para usar o StormTracking cache, especifique os seguintes valores:
+ **Capacidade de entrada**: limita o número de entradas de materiais de chave da ramificação que podem ser armazenadas no cache local.
Valor padrão: 1000 entradas
+ **Tamanho de entrada de limpeza de tail**: define o número de entradas de materiais de chave da ramificação a serem limpas por vez.
Valor padrão: 1 entrada
+ **Período de carência**: define o número de segundos antes da expiração em que é feita uma tentativa de atualizar os materiais de chave da ramificação.
Valor padrão: 10 segundos
+ **Intervalo de carência**: define o número de segundos entre as tentativas de atualizar os materiais de chave da ramificação.
Valor padrão: 1 segundo
+ **Fan out**: define o número de tentativas simultâneas que podem ser feitas para atualizar os materiais de chave da ramificação.
Valor padrão: 20 tentativas
+ **Tempo de ativação (TTL) em trânsito**: define o número de segundos até que uma tentativa de atualizar os materiais de chave de ramificação atinja o tempo limite. Sempre que o cache retorna `NoSuchEntry` em resposta a `GetCacheEntry`, essa chave de ramificação é considerada *em trânsito* até que a mesma chave seja gravada com uma entrada `PutCache`.
Valor padrão: 10 segundos
+ **Sleep**: define o número de segundos que um thread deve ficar em repouso se `fanOut` for excedido.
Valor padrão: 20 milissegundos
------
#### [ Java ]
```
.cache(CacheType.builder()
.StormTracking(StormTrackingCache.builder()
.entryCapacity(100)
.entryPruningTailSize(1)
.gracePeriod(10)
.graceInterval(1)
.fanOut(20)
.inFlightTTL(10)
.sleepMilli(20)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType stormTrackingCache = new CacheType
{
StormTracking = new StormTrackingCache
{
EntryCapacity = 100,
EntryPruningTailSize = 1,
FanOut = 20,
GraceInterval = 1,
GracePeriod = 10,
InFlightTTL = 10,
SleepMilli = 20
}
};
```
------
#### [ Rust ]
```
CacheType::StormTracking(
StormTrackingCache::builder()
.entry_capacity(100)
.entry_pruning_tail_size(1)
.grace_period(10)
.grace_interval(1)
.fan_out(20)
.in_flight_ttl(10)
.sleep_milli(20)
.build()?)
```
------
### Cache compartilhado
Por padrão, o chaveiro hierárquico cria um novo cache local toda vez que você instancia o chaveiro. No entanto, o cache compartilhado pode ajudar a conservar memória, permitindo que você compartilhe um cache em vários chaveiros hierárquicos. Em vez de criar um novo cache de materiais criptográficos para cada chaveiro hierárquico que você instancia, o cache compartilhado armazena somente um cache na memória, que pode ser usado por todos os chaveiros hierárquicos que fazem referência a ele. O cache compartilhado ajuda a otimizar o uso da memória, evitando a duplicação de materiais criptográficos nos chaveiros. Em vez disso, os chaveiros hierárquicos podem acessar o mesmo cache subjacente, reduzindo o consumo geral de memória.
Ao criar seu cache compartilhado, você ainda define o tipo de cache. Você pode especificar um [Cache padrão](#cache-default)[MultiThreaded cache](#cache-multithreaded), ou [StormTracking cache](#cache-stormtracking) como o tipo de cache ou substituir qualquer cache personalizado compatível.
**Partições**
Vários chaveiros hierárquicos podem usar um único cache compartilhado. **Ao criar um chaveiro hierárquico com um cache compartilhado, você pode definir uma ID de partição opcional.** O ID da partição distingue qual chaveiro hierárquico está sendo gravado no cache. Se dois chaveiros hierárquicos fizerem referência ao mesmo ID de partição e ID de chave de ramificação[logical key store name](create-keystore.md#logical-key-store-name), os dois chaveiros compartilharão as mesmas entradas de cache no cache. Se você criar dois chaveiros hierárquicos com o mesmo cache compartilhado, mas com uma partição diferente IDs, cada chaveiro acessará somente as entradas do cache de sua própria partição designada no cache compartilhado. As partições atuam como divisões lógicas dentro do cache compartilhado, permitindo que cada chaveiro hierárquico opere de forma independente em sua própria partição designada, sem interferir com os dados armazenados na outra partição.
Se você pretende reutilizar ou compartilhar as entradas de cache em uma partição, você deve definir seu próprio ID de partição. Quando você passa a ID da partição para seu chaveiro hierárquico, o chaveiro pode reutilizar as entradas de cache que já estão presentes no cache compartilhado, em vez de precisar recuperar e reautorizar os materiais da chave de ramificação novamente. Se você não especificar uma ID de partição, uma ID de partição exclusiva será automaticamente atribuída ao chaveiro toda vez que você instanciar o chaveiro hierárquico.
Os procedimentos a seguir demonstram como criar um cache compartilhado com o [tipo de cache padrão](#cache-default) e passá-lo para um chaveiro hierárquico.
1. Crie um `CryptographicMaterialsCache` (CMC) usando a [Material Providers Library](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL).
------
#### [ Java ]
```
// Instantiate the MPL
final MaterialProviders matProv =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
// Create a CacheType object for the Default cache
final CacheType cache =
CacheType.builder()
.Default(DefaultCache.builder().entryCapacity(100).build())
.build();
// Create a CMC using the default cache
final CreateCryptographicMaterialsCacheInput cryptographicMaterialsCacheInput =
CreateCryptographicMaterialsCacheInput.builder()
.cache(cache)
.build();
final ICryptographicMaterialsCache sharedCryptographicMaterialsCache =
matProv.CreateCryptographicMaterialsCache(cryptographicMaterialsCacheInput);
```
------
#### [ C\$1 / .NET ]
```
// Instantiate the MPL
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
// Create a CacheType object for the Default cache
var cache = new CacheType { Default = new DefaultCache{EntryCapacity = 100} };
// Create a CMC using the default cache
var cryptographicMaterialsCacheInput = new CreateCryptographicMaterialsCacheInput {Cache = cache};
var sharedCryptographicMaterialsCache = materialProviders.CreateCryptographicMaterialsCache(cryptographicMaterialsCacheInput);
```
------
#### [ Rust ]
```
// Instantiate the MPL
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create a CacheType object for the default cache
let cache: CacheType = CacheType::Default(
DefaultCache::builder()
.entry_capacity(100)
.build()?,
);
// Create a CMC using the default cache
let shared_cryptographic_materials_cache: CryptographicMaterialsCacheRef = mpl.
create_cryptographic_materials_cache()
.cache(cache)
.send()
.await?;
```
------
1. Crie um `CacheType` objeto para o cache compartilhado.
Passe o `sharedCryptographicMaterialsCache` que você criou na **Etapa 1** para o novo `CacheType` objeto.
------
#### [ Java ]
```
// Create a CacheType object for the sharedCryptographicMaterialsCache
final CacheType sharedCache =
CacheType.builder()
.Shared(sharedCryptographicMaterialsCache)
.build();
```
------
#### [ C\$1 / .NET ]
```
// Create a CacheType object for the sharedCryptographicMaterialsCache
var sharedCache = new CacheType { Shared = sharedCryptographicMaterialsCache };
```
------
#### [ Rust ]
```
// Create a CacheType object for the shared_cryptographic_materials_cache
let shared_cache: CacheType = CacheType::Shared(shared_cryptographic_materials_cache);
```
------
1. Passe o `sharedCache` objeto da **Etapa 2** para seu chaveiro hierárquico.
Ao criar um chaveiro hierárquico com um cache compartilhado, você pode, opcionalmente, definir um `partitionID` para compartilhar entradas de cache em vários chaveiros hierárquicos. Se você não especificar uma ID de partição, o chaveiro hierárquico atribuirá automaticamente ao chaveiro uma ID de partição exclusiva.
**nota**
Seus chaveiros hierárquicos compartilharão as mesmas entradas de cache em um cache compartilhado se você criar dois ou mais chaveiros que façam referência ao mesmo ID de partição e ID de chave de [logical key store name](create-keystore.md#logical-key-store-name) ramificação. Se você não quiser que vários chaveiros compartilhem as mesmas entradas de cache, use uma ID de partição exclusiva para cada chaveiro hierárquico.
O exemplo a seguir cria um chaveiro hierárquico com um [branch key ID supplier](#branch-key-id-supplier) [limite de cache](#cache-limit) de 600 segundos. Para obter mais informações sobre os valores definidos na seguinte configuração de chaveiro hierárquico, consulte. [Criar um token de autenticação hierárquico](#initialize-hierarchical-keyring)
------
#### [ Java ]
```
// Create the Hierarchical keyring
final CreateAwsKmsHierarchicalKeyringInput keyringInput =
CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(keystore)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(sharedCache)
.partitionID(partitionID)
.build();
final IKeyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
// Create the Hierarchical keyring
var createKeyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
Cache = sharedCache,
TtlSeconds = 600,
PartitionId = partitionID
};
var keyring = materialProviders.CreateAwsKmsHierarchicalKeyring(createKeyringInput);
```
------
#### [ Rust ]
```
// Create the Hierarchical keyring
let keyring1 = mpl
.create_aws_kms_hierarchical_keyring()
.key_store(key_store1)
.branch_key_id(branch_key_id.clone())
// CryptographicMaterialsCacheRef is an Rc (Reference Counted), so if you clone it to
// pass it to different Hierarchical Keyrings, it will still point to the same
// underlying cache, and increment the reference count accordingly.
.cache(shared_cache.clone())
.ttl_seconds(600)
.partition_id(partition_id.clone())
.send()
.await?;
```
------
## Criar um token de autenticação hierárquico
Para criar um chaveiro hierárquico, você deve fornecer os seguintes valores:
+ **Um nome de armazenamento de chaves**
O nome da tabela do DynamoDB que você, ou o administrador do armazenamento de chaves, criou para servir como seu armazenamento de chaves.
+
**Um tempo de vida do cache (TTL)**
A quantidade de tempo, em segundos, em que uma entrada de materiais de chave de ramificação no cache local pode ser usada antes de expirar. O limite de cache TTL determina a frequência com que o cliente liga AWS KMS para autorizar o uso das chaves de ramificação. Este valor deve ser maior que zero. Depois que o limite de cache TTL expirar, a entrada nunca será atendida e será removida do cache local.
+ **Um identificador de chave de ramificação**
Você pode configurar estaticamente o `branch-key-id` que identifica uma única chave de ramificação ativa em seu armazenamento de chaves ou fornecer um fornecedor de ID de chave de filial.
O *fornecedor da ID da chave de filial* usa os campos armazenados no contexto de criptografia para determinar qual chave de ramificação é necessária para descriptografar um registro. Por padrão, somente as chaves de partição e classificação são incluídas no contexto de criptografia. No entanto, você pode usar a [ação `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criptográfica](concepts.md#crypt-actions) para incluir campos adicionais no contexto de criptografia.
É altamente recomendável usar um fornecedor de ID de chave de filial para bancos de dados de vários locatários em que cada inquilino tenha sua própria chave de filial. Você pode usar o fornecedor da ID da chave da filial para criar um nome amigável para a chave da filial, IDs a fim de facilitar o reconhecimento da ID correta da chave da filial para um inquilino específico. Por exemplo, o nome amigável permite que você se refira a uma chave de ramificação como `tenant1` em vez de `b3f61619-4d35-48ad-a275-050f87e15122`.
Para operações de descriptografia, você pode configurar estaticamente um único token de autenticação hierárquico para restringir a descriptografia a um único locatário ou usar o fornecedor da ID da chave da ramificação para identificar qual locatário é responsável por descriptografar um registro.
+ **(Opcional) Um cache**
Se você quiser personalizar o tipo de cache ou o número de entradas de materiais de chave de ramificação que podem ser armazenadas no cache local, especifique o tipo de cache e a capacidade de entrada ao inicializar o token de autenticação.
O chaveiro hierárquico suporta os seguintes tipos de cache: Padrão, MultiThreaded StormTracking, e Compartilhado. Para obter mais informações e exemplos que demonstram como definir cada tipo de cache, consulte[Escolha um cache](#hierarchical-keyring-caches).
Se você não especificar um cache, o token de autenticação hierárquico usará automaticamente o tipo de cache Default e definirá a capacidade de entrada como 1000.
+ **(Opcional) Uma ID de partição**
Se você especificar o[Cache compartilhado](#cache-shared), você pode, opcionalmente, definir uma ID de partição. O ID da partição distingue qual chaveiro hierárquico está sendo gravado no cache. Se você pretende reutilizar ou compartilhar as entradas de cache em uma partição, você deve definir seu próprio ID de partição. Você pode especificar qualquer string para o ID da partição. Se você não especificar uma ID de partição, uma ID de partição exclusiva será automaticamente atribuída ao chaveiro na criação.
Para obter mais informações, consulte [Partitions](#shared-cache-partitions).
**nota**
Seus chaveiros hierárquicos compartilharão as mesmas entradas de cache em um cache compartilhado se você criar dois ou mais chaveiros que façam referência ao mesmo ID de partição e ID de chave de [logical key store name](create-keystore.md#logical-key-store-name) ramificação. Se você não quiser que vários chaveiros compartilhem as mesmas entradas de cache, use uma ID de partição exclusiva para cada chaveiro hierárquico.
+ **(Opcional) Uma lista de Tokens de Concessão**
Se você controlar o acesso à chave do KMS no token de autenticação hierárquico com [concessões](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html), deverá fornecer todos os tokens de concessão necessários ao inicializar o token de autenticação.
### Crie um chaveiro hierárquico com uma ID de chave de ramificação estática
Os exemplos a seguir demonstram como criar um chaveiro hierárquico com um ID de chave de ramificação estático[Cache padrão](#cache-default), o e um TTL de limite de cache de 600 segundos.
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(branchKeyStoreName)
.branchKeyId(branch-key-id)
.ttlSeconds(600)
.build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let hierarchical_keyring = mpl
.create_aws_kms_hierarchical_keyring()
.branch_key_id(branch_key_id)
.key_store(branch_key_store_name)
.ttl_seconds(600)
.send()
.await?;
```
------
### Crie um chaveiro hierárquico com um fornecedor de ID de chave de filial
Os procedimentos a seguir demonstram como criar um chaveiro hierárquico com um fornecedor de ID de chave de filial.
1. Crie um fornecedor de ID de chave de filial
O exemplo a seguir cria nomes amigáveis para as duas chaves de ramificação criadas na **Etapa 1** e chama `CreateDynamoDbEncryptionBranchKeyIdSupplier` a criação de um fornecedor de ID de chave de filial com o cliente AWS Database Encryption SDK for DynamoDB.
------
#### [ Java ]
```
// Create friendly names for each branch-key-id
class ExampleBranchKeyIdSupplier implements IDynamoDbKeyBranchKeyIdSupplier {
private static String branchKeyIdForTenant1;
private static String branchKeyIdForTenant2;
public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
this.branchKeyIdForTenant1 = tenant1Id;
this.branchKeyIdForTenant2 = tenant2Id;
}
// Create the branch key ID supplier
final DynamoDbEncryption ddbEnc = DynamoDbEncryption.builder()
.DynamoDbEncryptionConfig(DynamoDbEncryptionConfig.builder().build())
.build();
final BranchKeyIdSupplier branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
CreateDynamoDbEncryptionBranchKeyIdSupplierInput.builder()
.ddbKeyBranchKeyIdSupplier(new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2))
.build()).branchKeyIdSupplier();
```
------
#### [ C\$1 / .NET ]
```
// Create friendly names for each branch-key-id
class ExampleBranchKeyIdSupplier : DynamoDbKeyBranchKeyIdSupplierBase {
private String _branchKeyIdForTenant1;
private String _branchKeyIdForTenant2;
public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
this._branchKeyIdForTenant1 = tenant1Id;
this._branchKeyIdForTenant2 = tenant2Id;
}
// Create the branch key ID supplier
var ddbEnc = new DynamoDbEncryption(new DynamoDbEncryptionConfig());
var branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
new CreateDynamoDbEncryptionBranchKeyIdSupplierInput
{
DdbKeyBranchKeyIdSupplier = new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2)
}).BranchKeyIdSupplier;
```
------
#### [ Rust ]
```
// Create friendly names for each branch_key_id
pub struct ExampleBranchKeyIdSupplier {
branch_key_id_for_tenant1: String,
branch_key_id_for_tenant2: String,
}
impl ExampleBranchKeyIdSupplier {
pub fn new(tenant1_id: &str, tenant2_id: &str) -> Self {
Self {
branch_key_id_for_tenant1: tenant1_id.to_string(),
branch_key_id_for_tenant2: tenant2_id.to_string(),
}
}
}
// Create the branch key ID supplier
let dbesdk_config = DynamoDbEncryptionConfig::builder().build()?;
let dbesdk = dbesdk_client::Client::from_conf(dbesdk_config)?;
let supplier = ExampleBranchKeyIdSupplier::new(tenant1_branch_key_id, tenant2_branch_key_id);
let branch_key_id_supplier = dbesdk
.create_dynamo_db_encryption_branch_key_id_supplier()
.ddb_key_branch_key_id_supplier(supplier)
.send()
.await?
.branch_key_id_supplier
.unwrap();
```
------
1. Criar um token de autenticação hierárquico
Os exemplos a seguir inicializam um chaveiro hierárquico com o fornecedor de ID de chave de filial criado na **Etapa 1**, um limite de cache TLL de 600 segundos e um tamanho máximo de cache de 1000.
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(keystore)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(CacheType.builder() //OPTIONAL
.Default(DefaultCache.builder()
.entryCapacity(100)
.build())
.build())
.build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600,
Cache = new CacheType
{
Default = new DefaultCache { EntryCapacity = 100 }
}
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let hierarchical_keyring = mpl
.create_aws_kms_hierarchical_keyring()
.branch_key_id_supplier(branch_key_id_supplier)
.key_store(key_store)
.ttl_seconds(600)
.send()
.await?;
```
------
## Uso do token de autenticação hierárquico para criptografia pesquisável
A [criptografia pesquisável](searchable-encryption.md) permite pesquisar registros criptografados sem descriptografar todo o banco de dados. Isso é feito indexando o valor de texto simples de um campo criptografado com um [beacon](beacons.md). Para implementar a criptografia pesquisável, você deve usar um token de autenticação hierárquico.
A operação `CreateKey` de armazenamento de chaves gera uma chave de ramificação e uma chave de *beacon*. A chave de ramificação é usada em operações de criptografia e descriptografia de registros. A chave do beacon é usada para gerar beacons.
A chave de ramificação e a chave de beacon são protegidas pelo mesmo AWS KMS key que você especifica ao criar seu serviço de armazenamento de chaves. Depois que a `CreateKey` operação chama AWS KMS para gerar a chave de ramificação, ela chama [kms: GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) uma segunda vez para gerar a chave de beacon 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
},
"KeyId": "the KMS key ARN",
"NumberOfBytes": "32"
}
```
Depois de gerar as duas chaves, a `CreateKey` operação chama [ddb: TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html) para escrever dois novos itens que manterão a chave de ramificação e a chave de beacon em seu armazenamento de chaves de ramificação.
Quando você [configura um beacon padrão](configure-beacons.md#config-standard-beacons), o SDK do AWS Database Encryption consulta a chave do beacon no armazenamento de chaves. Em seguida, ele usa uma função de derivação de extract-and-expand chave baseada em HMAC ([HKDF](https://en.wikipedia.org/wiki/HKDF)) para combinar a chave do farol com o nome do farol [padrão para criar a chave HMAC para um determinado farol](beacons.md#standard-beacon-overview).
Ao contrário das chaves de ramificação, há apenas uma versão de chave de beacon `branch-key-id` em um armazenamento de chaves. A chave do beacon nunca é alternada.
### Definição da fonte de chave de beacon
Ao definir a [versão do beacon](using-beacons.md#beacon-version) para seus beacons padrão e compostos, você deve identificar a chave do beacon e definir um limite de tempo de vida do cache (TTL) para os materiais da chave do beacon. Os materiais das chaves do beacon são armazenados em um cache local separado das chaves da ramificação. O trecho a seguir demonstra como definir o `keySource` para um banco de dados de locatário único. Identifique sua chave de beacon pelo `branch-key-id` que ela está associada.
------
#### [ Java ]
```
keySource(BeaconKeySource.builder()
.single(SingleKeyStore.builder()
.keyId(branch-key-id)
.cacheTTL(6000)
.build())
.build())
```
------
#### [ C\$1 / .NET ]
```
KeySource = new BeaconKeySource
{
Single = new SingleKeyStore
{
KeyId = branch-key-id,
CacheTTL = 6000
}
}
```
------
#### [ Rust ]
```
.key_source(BeaconKeySource::Single(
SingleKeyStore::builder()
// `keyId` references a beacon key.
// For every branch key we create in the keystore,
// we also create a beacon key.
// This beacon key is not the same as the branch key,
// but is created with the same ID as the branch key.
.key_id(branch_key_id)
.cache_ttl(6000)
.build()?,
))
```
------
**Definição da fonte do beacon em um banco de dados multilocatário**
Se você tiver um banco de dados multilocatário, deverá especificar os valores a seguir ao configurar o `keySource`.
+
**keyFieldName**
Define o nome do campo que armazena o `branch-key-id` associado à chave de beacon usada para gerar beacons para um determinado locatário. O `keyFieldName` pode ser qualquer string, mas deve ser exclusiva para todos os outros campos do banco de dados. Quando você grava novos registros em seu banco de dados, a chave `branch-key-id` que identifica a chave de beacon usada para gerar quaisquer beacons para esse registro é armazenada nesse campo. Você deve incluir esse campo em suas consultas de beacon e identificar os materiais de chave de beacon apropriados necessários para recalcular o beacon. Para obter mais informações, consulte [Consultar beacons em um banco de dados multilocatário](searchable-encryption-multitenant.md#query-multitenant-beacons).
+ **cacheTTL**
A quantidade de tempo, em segundos, em que uma entrada de materiais de chave de beacon no cache local pode ser usada antes de expirar. Esse valor deve ser maior que zero. Quando o limite de cache TTL expira, a entrada é removida do cache local.
+ **(Opcional) Um cache**
Se você quiser personalizar o tipo de cache ou o número de entradas de materiais de chave de ramificação que podem ser armazenadas no cache local, especifique o tipo de cache e a capacidade de entrada ao inicializar o token de autenticação.
O chaveiro hierárquico suporta os seguintes tipos de cache: Padrão, MultiThreaded StormTracking, e Compartilhado. Para obter mais informações e exemplos que demonstram como definir cada tipo de cache, consulte[Escolha um cache](#hierarchical-keyring-caches).
Se você não especificar um cache, o token de autenticação hierárquico usará automaticamente o tipo de cache Default e definirá a capacidade de entrada como 1000.
O exemplo a seguir cria um chaveiro hierárquico com um fornecedor de ID de chave de filial, um limite de cache (TLL) de 600 segundos e uma capacidade de entrada de 1.000.
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(branchKeyStoreName)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(CacheType.builder() //OPTIONAL
.Default(DefaultCache.builder()
.entryCapacity(1000)
.build())
.build());
final IKeyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600,
Cache = new CacheType
{
Default = new DefaultCache { EntryCapacity = 1000 }
}
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
```
let provider_config = MaterialProvidersConfig::builder().build()?;
let mat_prov = client::Client::from_conf(provider_config)?;
let kms_keyring = mat_prov
.create_aws_kms_hierarchical_keyring()
.branch_key_id(branch_key_id)
.key_store(key_store)
.ttl_seconds(600)
.send()
.await?;
```
# AWS KMS chaveiros ECDH
****
| |
| --- |
| Nossa biblioteca de criptografia do lado do cliente foi renomeada para SDK de criptografia de AWS banco de dados. Este guia do desenvolvedor ainda fornece informações sobre o [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
**Importante**
O chaveiro AWS KMS ECDH só está disponível na versão 1.5.0 ou posterior da Material Providers Library.
Um chaveiro AWS KMS ECDH usa um acordo de chave assimétrica [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/key-types.html)para derivar uma chave de embalagem simétrica compartilhada entre duas partes. Primeiro, o chaveiro usa o algoritmo de acordo de chaves Elliptic Curve Diffie-Hellman (ECDH) para derivar um segredo compartilhado da chave privada no par de chaves KMS do remetente e da chave pública do destinatário. Em seguida, o chaveiro usa o segredo compartilhado para derivar a chave de empacotamento compartilhada que protege suas chaves de criptografia de dados. A função de derivação de chave que o SDK AWS de criptografia de banco de dados usa (`KDF_CTR_HMAC_SHA384`) para derivar a chave de encapsulamento compartilhada está em conformidade com as recomendações do [NIST](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-108r1-upd1.pdf) para derivação de chaves.
A função de derivação de chave retorna 64 bytes de material de chaveamento. Para garantir que ambas as partes usem o material de codificação correto, o SDK AWS de criptografia de banco de dados usa os primeiros 32 bytes como chave de compromisso e os últimos 32 bytes como chave de empacotamento compartilhada. Na descriptografia, se o chaveiro não puder reproduzir a mesma chave de compromisso e chave de empacotamento compartilhada armazenadas no campo de descrição do material do registro criptografado, a operação falhará. Por exemplo, se você criptografar um registro com um chaveiro configurado com a chave privada de **Alice** e a chave pública de **Bob**, um chaveiro configurado com a chave privada de **Bob** e a chave pública de **Alice** reproduzirá a mesma chave de compromisso e chave de encapsulamento compartilhada e poderá descriptografar o registro. Se a chave pública de Bob não for de um par de chaves KMS, Bob poderá criar um [chaveiro ECDH bruto para descriptografar o registro](use-raw-ecdh-keyring.md).
O chaveiro AWS KMS ECDH criptografa registros com uma chave simétrica usando o AES-GCM. A chave de dados é então criptografada em envelope com a chave de empacotamento compartilhada derivada usando o AES-GCM. [Cada chaveiro AWS KMS ECDH pode ter apenas uma chave de embrulho compartilhada, mas você pode incluir vários chaveiros AWS KMS ECDH, sozinhos ou com outros chaveiros, em um chaveiro múltiplo.](use-multi-keyring.md)
**Topics**
+ [Permissões necessárias para AWS KMS chaveiros ECDH](#kms-ecdh-permissions)
+ [Criando um AWS KMS chaveiro ECDH](#kms-ecdh-create)
+ [Criando um AWS KMS chaveiro de descoberta ECDH](#kms-ecdh-discovery)
## Permissões necessárias para AWS KMS chaveiros ECDH
O SDK AWS de criptografia de banco de dados não exige uma AWS conta e não depende de nenhum AWS serviço. No entanto, para usar um chaveiro AWS KMS ECDH, você precisa de uma AWS conta e das seguintes permissões mínimas AWS KMS keys no seu chaveiro. As permissões variam de acordo com o esquema de contrato de chaves que você usa.
+ *Para criptografar e descriptografar registros usando o esquema de contrato de `KmsPrivateKeyToStaticPublicKey` chave, você precisa de [kms: GetPublicKey e kms: DeriveSharedSecret no par de chaves KMS](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) [assimétrico](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) do remetente.* Se você fornecer diretamente a chave pública codificada em DER do remetente ao instanciar seu chaveiro, precisará apenas da DeriveSharedSecret permissão [kms: no par de chaves KMS assimétrico](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) do remetente.
+ Para descriptografar registros usando o esquema de contrato de `KmsPublicKeyDiscovery` chaves, você precisa das GetPublicKey permissões [kms: DeriveSharedSecret e kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) no par de chaves [assimétrico KMS](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) especificado.
## Criando um AWS KMS chaveiro ECDH
Para criar um chaveiro AWS KMS ECDH que criptografe e descriptografe dados, você deve usar o esquema de contrato de chave. `KmsPrivateKeyToStaticPublicKey` Para inicializar um chaveiro AWS KMS ECDH com o esquema de contrato de `KmsPrivateKeyToStaticPublicKey` chaves, forneça os seguintes valores:
+ **ID do remetente AWS KMS key **
Deve identificar um par de chaves KMS de curva elíptica (ECC) assimétrica recomendado pelo NIST com um valor de. `KeyUsage` `KEY_AGREEMENT` A chave privada do remetente é usada para derivar o segredo compartilhado.
+ **(Opcional) Chave pública do remetente**
[Deve ser uma chave pública X.509 codificada por DER, também conhecida como `SubjectPublicKeyInfo` (SPKI), conforme definido na RFC 5280.](https://tools.ietf.org/html/rfc5280)
A AWS KMS [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html)operação retorna a chave pública de um par de chaves KMS assimétrico no formato codificado em DER exigido.
Para reduzir o número de AWS KMS chamadas que seu chaveiro faz, você pode fornecer diretamente a chave pública do remetente. Se nenhum valor for fornecido para a chave pública do remetente, o chaveiro liga AWS KMS para recuperar a chave pública do remetente.
+ **Chave pública do destinatário**
[Você deve fornecer a chave pública X.509 codificada em DER do destinatário, também conhecida como `SubjectPublicKeyInfo` (SPKI), conforme definido na RFC 5280.](https://tools.ietf.org/html/rfc5280)
A AWS KMS [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html)operação retorna a chave pública de um par de chaves KMS assimétrico no formato codificado em DER exigido.
+ **Especificação da curva**
Identifica a especificação da curva elíptica nos pares de chaves especificados. Os pares de chaves do remetente e do destinatário devem ter a mesma especificação de curva.
Valores válidos: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
+ **(Opcional) Uma lista de Tokens de Concessão**
Se você controlar o acesso à chave KMS em seu chaveiro AWS KMS ECDH com [concessões](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html), deverá fornecer todos os tokens de concessão necessários ao inicializar o chaveiro.
------
#### [ C\$1 / .NET ]
O exemplo a seguir cria um chaveiro AWS KMS ECDH com a chave KMS do remetente, a chave pública do remetente e a chave pública do destinatário. Este exemplo usa o `senderPublicKey` parâmetro opcional para fornecer a chave pública do remetente. Se você não fornecer a chave pública do remetente, o chaveiro liga AWS KMS para recuperar a chave pública do remetente. Os pares de chaves do remetente e do destinatário estão na `ECC_NIST_P256` curva.
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
// Must be DER-encoded X.509 public keys
var BobPublicKey = new MemoryStream(new byte[] { });
var AlicePublicKey = new MemoryStream(new byte[] { });
// Create the AWS KMS ECDH static keyring
var staticConfiguration = new KmsEcdhStaticConfigurations
{
KmsPrivateKeyToStaticPublicKey = new KmsPrivateKeyToStaticPublicKeyInput
{
SenderKmsIdentifier = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
SenderPublicKey = BobPublicKey,
RecipientPublicKey = AlicePublicKey
}
};
var createKeyringInput = new CreateAwsKmsEcdhKeyringInput
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KmsClient = new AmazonKeyManagementServiceClient(),
KeyAgreementScheme = staticConfiguration
};
var keyring = materialProviders.CreateAwsKmsEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
O exemplo a seguir cria um chaveiro AWS KMS ECDH com a chave KMS do remetente, a chave pública do remetente e a chave pública do destinatário. Este exemplo usa o `senderPublicKey` parâmetro opcional para fornecer a chave pública do remetente. Se você não fornecer a chave pública do remetente, o chaveiro liga AWS KMS para recuperar a chave pública do remetente. Os pares de chaves do remetente e do destinatário estão na `ECC_NIST_P256` curva.
```
// Retrieve public keys
// Must be DER-encoded X.509 public keys
ByteBuffer BobPublicKey = getPublicKeyBytes("arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab");
ByteBuffer AlicePublicKey = getPublicKeyBytes("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321");
// Create the AWS KMS ECDH static keyring
final CreateAwsKmsEcdhKeyringInput senderKeyringInput =
CreateAwsKmsEcdhKeyringInput.builder()
.kmsClient(KmsClient.create())
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
KmsEcdhStaticConfigurations.builder()
.KmsPrivateKeyToStaticPublicKey(
KmsPrivateKeyToStaticPublicKeyInput.builder()
.senderKmsIdentifier("arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
.senderPublicKey(BobPublicKey)
.recipientPublicKey(AlicePublicKey)
.build()).build()).build();
```
------
#### [ Rust ]
O exemplo a seguir cria um chaveiro AWS KMS ECDH com a chave KMS do remetente, a chave pública do remetente e a chave pública do destinatário. Este exemplo usa o `sender_public_key` parâmetro opcional para fornecer a chave pública do remetente. Se você não fornecer a chave pública do remetente, o chaveiro liga AWS KMS para recuperar a chave pública do remetente.
```
// Retrieve public keys
// Must be DER-encoded X.509 keys
let public_key_file_content_sender = std::fs::read_to_string(Path::new(EXAMPLE_KMS_ECC_PUBLIC_KEY_FILENAME_SENDER))?;
let parsed_public_key_file_content_sender = parse(public_key_file_content_sender)?;
let public_key_sender_utf8_bytes = parsed_public_key_file_content_sender.contents();
let public_key_file_content_recipient = std::fs::read_to_string(Path::new(EXAMPLE_KMS_ECC_PUBLIC_KEY_FILENAME_RECIPIENT))?;
let parsed_public_key_file_content_recipient = parse(public_key_file_content_recipient)?;
let public_key_recipient_utf8_bytes = parsed_public_key_file_content_recipient.contents();
// Create KmsPrivateKeyToStaticPublicKeyInput
let kms_ecdh_static_configuration_input =
KmsPrivateKeyToStaticPublicKeyInput::builder()
.sender_kms_identifier(arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab)
// Must be a UTF8 DER-encoded X.509 public key
.sender_public_key(public_key_sender_utf8_bytes)
// Must be a UTF8 DER-encoded X.509 public key
.recipient_public_key(public_key_recipient_utf8_bytes)
.build()?;
let kms_ecdh_static_configuration = KmsEcdhStaticConfigurations::KmsPrivateKeyToStaticPublicKey(kms_ecdh_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create AWS KMS ECDH keyring
let kms_ecdh_keyring = mpl
.create_aws_kms_ecdh_keyring()
.kms_client(kms_client)
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(kms_ecdh_static_configuration)
.send()
.await?;
```
------
## Criando um AWS KMS chaveiro de descoberta ECDH
Ao descriptografar, é uma prática recomendada especificar as chaves que o SDK de criptografia de AWS banco de dados pode usar. Para seguir essa prática recomendada, use um chaveiro AWS KMS ECDH com o esquema de contrato de `KmsPrivateKeyToStaticPublicKey` chaves. No entanto, você também pode criar um chaveiro de descoberta AWS KMS ECDH, ou seja, um chaveiro AWS KMS ECDH que pode descriptografar qualquer registro em que a chave pública do par de chaves KMS especificado corresponda à chave pública do *destinatário armazenada no campo de descrição do material do* registro criptografado.
**Importante**
Ao descriptografar registros usando o esquema de contrato de `KmsPublicKeyDiscovery` chave, você aceita todas as chaves públicas, independentemente de quem as possua.
Para inicializar um chaveiro AWS KMS ECDH com o esquema de contrato de `KmsPublicKeyDiscovery` chaves, forneça os seguintes valores:
+ ** AWS KMS key ID do destinatário**
Deve identificar um par de chaves KMS de curva elíptica (ECC) assimétrica recomendado pelo NIST com um valor de. `KeyUsage` `KEY_AGREEMENT`
+ **Especificação da curva**
Identifica a especificação da curva elíptica no par de chaves KMS do destinatário.
Valores válidos: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
+ **(Opcional) Uma lista de Tokens de Concessão**
Se você controlar o acesso à chave KMS em seu chaveiro AWS KMS ECDH com [concessões](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html), deverá fornecer todos os tokens de concessão necessários ao inicializar o chaveiro.
------
#### [ C\$1 / .NET ]
O exemplo a seguir cria um chaveiro de descoberta AWS KMS ECDH com um par de chaves KMS na curva. `ECC_NIST_P256` Você deve ter as DeriveSharedSecret permissões [kms: GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) e [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) no par de chaves KMS especificado. Esse chaveiro pode descriptografar qualquer registro em que a chave pública do par de chaves KMS especificado corresponda à chave pública do destinatário armazenada no campo de descrição do material do registro criptografado.
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
// Create the AWS KMS ECDH discovery keyring
var discoveryConfiguration = new KmsEcdhStaticConfigurations
{
KmsPublicKeyDiscovery = new KmsPublicKeyDiscoveryInput
{
RecipientKmsIdentifier = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
}
};
var createKeyringInput = new CreateAwsKmsEcdhKeyringInput
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KmsClient = new AmazonKeyManagementServiceClient(),
KeyAgreementScheme = discoveryConfiguration
};
var keyring = materialProviders.CreateAwsKmsEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
O exemplo a seguir cria um chaveiro de descoberta AWS KMS ECDH com um par de chaves KMS na curva. `ECC_NIST_P256` Você deve ter as DeriveSharedSecret permissões [kms: GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) e [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) no par de chaves KMS especificado. Esse chaveiro pode descriptografar qualquer registro em que a chave pública do par de chaves KMS especificado corresponda à chave pública do destinatário armazenada no campo de descrição do material do registro criptografado.
```
// Create the AWS KMS ECDH discovery keyring
final CreateAwsKmsEcdhKeyringInput recipientKeyringInput =
CreateAwsKmsEcdhKeyringInput.builder()
.kmsClient(KmsClient.create())
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
KmsEcdhStaticConfigurations.builder()
.KmsPublicKeyDiscovery(
KmsPublicKeyDiscoveryInput.builder()
.recipientKmsIdentifier("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321").build()
).build())
.build();
```
------
#### [ Rust ]
```
// Create KmsPublicKeyDiscoveryInput
let kms_ecdh_discovery_static_configuration_input =
KmsPublicKeyDiscoveryInput::builder()
.recipient_kms_identifier(ecc_recipient_key_arn)
.build()?;
let kms_ecdh_discovery_static_configuration = KmsEcdhStaticConfigurations::KmsPublicKeyDiscovery(kms_ecdh_discovery_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create AWS KMS ECDH discovery keyring
let kms_ecdh_discovery_keyring = mpl
.create_aws_kms_ecdh_keyring()
.kms_client(kms_client.clone())
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(kms_ecdh_discovery_static_configuration)
.send()
.await?;
```
------
# Tokens de autenticação AES Raw
****
| |
| --- |
| Nossa biblioteca de criptografia do lado do cliente foi renomeada para SDK de criptografia de AWS banco de dados. Este guia do desenvolvedor ainda fornece informações sobre o [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
O SDK AWS de criptografia de banco de dados permite que você use uma chave simétrica AES que você fornece como uma chave de empacotamento que protege sua chave de dados. Você precisa gerar, armazenar e proteger o material de chaves, de preferência em um módulo de segurança de hardware (HSM) ou em um sistema de gerenciamento de chaves. Use um token de autenticação AES bruto quando precisar fornecer a chave de empacotamento e criptografar as chaves de dados local ou offline.
O token de autenticação bruto do AES usa o algoritmo AES-GCM e uma chave de empacotamento que você especifica como uma matriz de bytes para criptografar chaves de dados. É possível especificar somente uma chave de empacotamento em cada token de autenticação bruto do AES, mas você pode incluir vários tokens de autenticação brutos do AES, sozinhos ou com outros tokens de autenticação, em um [multitoken de autenticação](use-multi-keyring.md).
**Nomes e namespaces de chaves**
Para identificar a chave AES em um token de autenticação, o token de autenticação bruto do AES usa um *namespace de chave* e um *nome de chave* fornecidos por você. Esses valores não são secretos. Eles aparecem em texto simples na [descrição do material](concepts.md#material-description) que o SDK do AWS Database Encryption adiciona ao registro. Recomendamos usar um namespace de chave em seu HSM ou sistema de gerenciamento de chaves e um nome de chave que identifique a chave AES nesse sistema.
**nota**
O namespace e o nome da chave são equivalentes aos campos *ID do provedor* (ou *provedor*) e *ID da chave* no `JceMasterKey`.
Se você construir tokens de autenticação diferentes para criptografar e descriptografar um determinado campo, o namespace e os valores do nome são essenciais. Se o namespace e o nome da chave no token de autenticação de decodificação não corresponderem exatamente e com distinção entre maiúsculas e minúsculas ao namespace e ao nome da chave no token de autenticação de criptografia, o token de autenticação de decodificação não será usado, mesmo que os bytes do material da chave sejam idênticos.
Por exemplo, é possível definir um token de autenticação AES bruto com namespace `HSM_01` e nome de chave `AES_256_012`. Em seguida, você usa esse token de autenticação para criptografar alguns dados. Para descriptografar esses dados, construa um token de autenticação bruto do AES bruto com o mesmo namespace de chave, nome de chave e material de chave.
O exemplo a seguir mostra como criar um token de autenticação bruto do AES. A variável `AESWrappingKey` representa o material principal que você fornece.
------
#### [ Java ]
```
final CreateRawAesKeyringInput keyringInput = CreateRawAesKeyringInput.builder()
.keyName("AES_256_012")
.keyNamespace("HSM_01")
.wrappingKey(AESWrappingKey)
.wrappingAlg(AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16)
.build();
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var keyNamespace = "HSM_01";
var keyName = "AES_256_012";
// This example uses the key generator in Bouncy Castle to generate the key material.
// In production, use key material from a secure source.
var aesWrappingKey = new MemoryStream(GeneratorUtilities.GetKeyGenerator("AES256").GenerateKey());
// Create the keyring
var keyringInput = new CreateRawAesKeyringInput
{
KeyNamespace = keyNamespace,
KeyName = keyName,
WrappingKey = AESWrappingKey,
WrappingAlg = AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
};
var matProv = new MaterialProviders(new MaterialProvidersConfig());
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let raw_aes_keyring = mpl
.create_raw_aes_keyring()
.key_name("AES_256_012")
.key_namespace("HSM_01")
.wrapping_key(aes_key_bytes)
.wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
.send()
.await?;
```
------
# Tokens de autenticação brutos do RSA
****
| |
| --- |
| Nossa biblioteca de criptografia do lado do cliente foi renomeada para SDK de criptografia de AWS banco de dados. Este guia do desenvolvedor ainda fornece informações sobre o [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
O token de autenticação bruto do RSA realiza a criptografia e a descriptografia assimétricas das chaves de dados na memória local com chaves de empacotamento pública e privada fornecidas. Você precisa gerar, armazenar e proteger a chave privada, de preferência em um módulo de segurança de hardware (HSM) ou com o sistema de gerenciamento de chaves. A função de criptografia criptografa a chave de dados com chave pública do RSA. A função de descriptografia descriptografa a chave de dados usando a chave privada. É possível selecionar entre os vários modos de padding do RSA.
Um token de autenticação bruto do RSA que criptografa e descriptografa deve incluir uma chave pública e um par de chaves privadas assimétricas. No entanto, é possível criptografar dados com um token de autenticação bruto do RSA que tenha apenas uma chave pública e descriptografar dados com um token de autenticação bruto do RSA que tenha apenas uma chave privada. É possível incluir qualquer token de autenticação bruto do RSA em um [multitoken de autenticação](use-multi-keyring.md). Se você configurar um token de autenticação bruto do RSA com uma chave pública e privada, certifique-se de que eles façam parte do mesmo par de chaves.
O chaveiro RSA bruto é equivalente e interopera com o [JceMasterKey](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/jce/JceMasterKey.html)no AWS Encryption SDK for Java quando é usado com chaves de criptografia assimétrica RSA.
**nota**
O token de autenticação RSA bruto não oferece suporte a chaves do KMS assimétricas. [Para usar chaves RSA KMS assimétricas, construa um token de autenticação do AWS KMS](use-kms-keyring.md).
**Namespaces e nomes**
Para identificar a chave RSA em um token de autenticação, o token de autenticação bruto do RSA usa um *namespace de chave* e um *nome de chave* fornecidos por você. Esses valores não são secretos. Eles aparecem em texto simples na [descrição do material](concepts.md#material-description) que o SDK do AWS Database Encryption adiciona ao registro. Recomendamos usar um namespace de chave e um nome de chave que identifique o par de chaves RSA (ou a sua chave privada) no HSM ou no sistema de gerenciamento de chaves..
**nota**
O namespace e o nome da chave são equivalentes aos campos *ID do provedor* (ou *provedor*) e *ID da chave* no `JceMasterKey`.
Se você construir tokens de autenticação diferentes para criptografar e descriptografar um determinado registro, o namespace e os valores do nome são essenciais. Se o namespace e o nome da chave no token de autenticação de decodificação não corresponderem exatamente e com distinção entre maiúsculas e minúsculas ao namespace e ao nome da chave no token de autenticação de criptografia, o token de autenticação de decodificação não será usado, mesmo que as chaves sejam do mesmo par de chaves.
O namespace da chave e o nome da chave do material da chave nos tokens de autenticação de criptografia e decodificação devem ser os mesmos, independentemente de o token de autenticação conter a chave pública RSA, a chave privada RSA ou ambas as chaves no par de chaves. Por exemplo, suponha que você criptografe dados com um token de autenticação RSA bruto para uma chave pública RSA com o namespace de chave `HSM_01` e nome de chave `RSA_2048_06`. Para descriptografar esses dados, construa um token de autenticação RSA bruto com a chave privada (ou par de chaves) e o mesmo namespace e nome de chave.
**Modo de preenchimento**
Você deve especificar um modo de preenchimento para tokens de autenticação RSA brutos usados para criptografia e descriptografia, ou usar atributos de sua implementação de linguagem que o especifiquem para você.
O AWS Encryption SDK suporta os seguintes modos de preenchimento, sujeitos às restrições de cada idioma. Recomendamos um modo de preenchimento [OAEP](https://tools.ietf.org/html/rfc8017#section-7.1), particularmente OAEP com SHA-256 e com preenchimento SHA-256. MGF1 O modo [PKCS1](https://tools.ietf.org/html/rfc8017#section-7.2)de preenchimento é suportado somente para compatibilidade com versões anteriores.
+ OAEP com SHA-1 e com preenchimento SHA-1 MGF1
+ OAEP com SHA-256 e com preenchimento SHA-256 MGF1
+ OAEP com SHA-384 e com preenchimento SHA-384 MGF1
+ OAEP com SHA-512 e com preenchimento SHA-512 MGF1
+ PKCS1 Preenchimento v1.5
O exemplo Java a seguir mostra como criar um chaveiro RSA bruto com a chave pública e privada de um par de chaves RSA e o OAEP com SHA-256 e com o modo de preenchimento SHA-256. MGF1 As variáveis `RSAPublicKey` e `RSAPrivateKey` representam o material principal que você fornece.
------
#### [ Java ]
```
final CreateRawRsaKeyringInput keyringInput = CreateRawRsaKeyringInput.builder()
.keyName("RSA_2048_06")
.keyNamespace("HSM_01")
.paddingScheme(PaddingScheme.OAEP_SHA256_MGF1)
.publicKey(RSAPublicKey)
.privateKey(RSAPrivateKey)
.build();
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
IKeyring rawRsaKeyring = matProv.CreateRawRsaKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var keyNamespace = "HSM_01";
var keyName = "RSA_2048_06";
// Get public and private keys from PEM files
var publicKey = new MemoryStream(System.IO.File.ReadAllBytes("RSAKeyringExamplePublicKey.pem"));
var privateKey = new MemoryStream(System.IO.File.ReadAllBytes("RSAKeyringExamplePrivateKey.pem"));
// Create the keyring input
var keyringInput = new CreateRawRsaKeyringInput
{
KeyNamespace = keyNamespace,
KeyName = keyName,
PaddingScheme = PaddingScheme.OAEP_SHA512_MGF1,
PublicKey = publicKey,
PrivateKey = privateKey
};
// Create the keyring
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var rawRsaKeyring = matProv.CreateRawRsaKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let raw_rsa_keyring = mpl
.create_raw_rsa_keyring()
.key_name("RSA_2048_06")
.key_namespace("HSM_01")
.padding_scheme(PaddingScheme::OaepSha256Mgf1)
.public_key(RSA_public_key)
.private_key(RSA_private_key)
.send()
.await?;
```
------
# Chaveiros ECDH brutos
****
| |
| --- |
| Nossa biblioteca de criptografia do lado do cliente foi renomeada para SDK de criptografia de AWS banco de dados. Este guia do desenvolvedor ainda fornece informações sobre o [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
**Importante**
O chaveiro ECDH bruto só está disponível na versão 1.5.0 da Material Providers Library.
O chaveiro ECDH bruto usa os pares de chaves públicas-privadas de curva elíptica que você fornece para derivar uma chave de empacotamento compartilhada entre duas partes. Primeiro, o chaveiro obtém um segredo compartilhado usando a chave privada do remetente, a chave pública do destinatário e o algoritmo de acordo de chave Elliptic Curve Diffie-Hellman (ECDH). Em seguida, o chaveiro usa o segredo compartilhado para derivar a chave de empacotamento compartilhada que protege suas chaves de criptografia de dados. A função de derivação de chave que o SDK AWS de criptografia de banco de dados usa (`KDF_CTR_HMAC_SHA384`) para derivar a chave de encapsulamento compartilhada está em conformidade com as recomendações do [NIST](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-108r1-upd1.pdf) para derivação de chaves.
A função de derivação de chave retorna 64 bytes de material de chaveamento. Para garantir que ambas as partes usem o material de codificação correto, o SDK AWS de criptografia de banco de dados usa os primeiros 32 bytes como chave de compromisso e os últimos 32 bytes como chave de empacotamento compartilhada. Na descriptografia, se o chaveiro não puder reproduzir a mesma chave de compromisso e chave de empacotamento compartilhada armazenadas no campo de descrição do material do registro criptografado, a operação falhará. Por exemplo, se você criptografar um registro com um chaveiro configurado com a chave privada de **Alice** e a chave pública de **Bob**, um chaveiro configurado com a chave privada de **Bob** e a chave pública de **Alice** reproduzirá a mesma chave de compromisso e chave de encapsulamento compartilhada e poderá descriptografar o registro. Se a chave pública de Bob for de um AWS KMS key par, Bob poderá criar um [chaveiro AWS KMS ECDH](use-kms-ecdh-keyring.md) para decifrar o registro.
O chaveiro Raw ECDH criptografa registros com uma chave simétrica usando o AES-GCM. A chave de dados é então criptografada em envelope com a chave de empacotamento compartilhada derivada usando o AES-GCM. [Cada chaveiro Raw ECDH pode ter apenas uma chave de embrulho compartilhada, mas você pode incluir vários chaveiros Raw ECDH, sozinhos ou com outros chaveiros, em um chaveiro múltiplo.](use-multi-keyring.md)
Você é responsável por gerar, armazenar e proteger suas chaves privadas, preferencialmente em um módulo de segurança de hardware (HSM) ou sistema de gerenciamento de chaves. Os pares de chaves do remetente e do destinatário devem estar na mesma curva elíptica. O SDK AWS de criptografia de banco de dados é compatível com as seguintes especificações de curva elíptica:
+ `ECC_NIST_P256`
+ `ECC_NIST_P384`
+ `ECC_NIST_P512`
## Criando um chaveiro ECDH bruto
O chaveiro Raw ECDH suporta três esquemas de contrato principais:`RawPrivateKeyToStaticPublicKey`, e. `EphemeralPrivateKeyToStaticPublicKey` `PublicKeyDiscovery` O esquema de contrato de chave selecionado determina quais operações criptográficas você pode realizar e como os materiais de chaveamento são montados.
**Topics**
+ [RawPrivateKeyToStaticPublicKey](#raw-ecdh-RawPrivateKeyToStaticPublicKey)
+ [EphemeralPrivateKeyToStaticPublicKey](#raw-ecdh-EphemeralPrivateKeyToStaticPublicKey)
+ [PublicKeyDiscovery](#raw-ecdh-PublicKeyDiscovery)
### RawPrivateKeyToStaticPublicKey
Use o esquema de contrato de `RawPrivateKeyToStaticPublicKey` chave para configurar estaticamente a chave privada do remetente e a chave pública do destinatário no chaveiro. Esse esquema de contrato de chave pode criptografar e descriptografar registros.
Para inicializar um chaveiro ECDH bruto com o esquema de contrato de `RawPrivateKeyToStaticPublicKey` chave, forneça os seguintes valores:
+ **Chave privada do remetente**
[Você deve fornecer a chave privada codificada por PEM do remetente ( PrivateKeyInfo estruturas PKCS \$18), conforme definido na RFC 5958.](https://tools.ietf.org/html/rfc5958#section-2)
+ **Chave pública do destinatário**
[Você deve fornecer a chave pública X.509 codificada em DER do destinatário, também conhecida como `SubjectPublicKeyInfo` (SPKI), conforme definido na RFC 5280.](https://tools.ietf.org/html/rfc5280)
Você pode especificar a chave pública de um contrato de chave assimétrica (par de chaves KMS) ou a chave pública de um par de chaves gerado fora do. AWS
+ **Especificação da curva**
Identifica a especificação da curva elíptica nos pares de chaves especificados. Os pares de chaves do remetente e do destinatário devem ter a mesma especificação de curva.
Valores válidos: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
------
#### [ C\$1 / .NET ]
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
var BobPrivateKey = new MemoryStream(new byte[] { });
var AlicePublicKey = new MemoryStream(new byte[] { });
// Create the Raw ECDH static keyring
var staticConfiguration = new RawEcdhStaticConfigurations()
{
RawPrivateKeyToStaticPublicKey = new RawPrivateKeyToStaticPublicKeyInput
{
SenderStaticPrivateKey = BobPrivateKey,
RecipientPublicKey = AlicePublicKey
}
};
var createKeyringInput = new CreateRawEcdhKeyringInput()
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KeyAgreementScheme = staticConfiguration
};
var keyring = materialProviders.CreateRawEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
O exemplo Java a seguir usa o esquema de contrato de `RawPrivateKeyToStaticPublicKey` chave para configurar estaticamente a chave privada do remetente e a chave pública do destinatário. Ambos os pares de chaves estão na `ECC_NIST_P256` curva.
```
private static void StaticRawKeyring() {
// Instantiate material providers
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
KeyPair senderKeys = GetRawEccKey();
KeyPair recipient = GetRawEccKey();
// Create the Raw ECDH static keyring
final CreateRawEcdhKeyringInput rawKeyringInput =
CreateRawEcdhKeyringInput.builder()
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
RawEcdhStaticConfigurations.builder()
.RawPrivateKeyToStaticPublicKey(
RawPrivateKeyToStaticPublicKeyInput.builder()
// Must be a PEM-encoded private key
.senderStaticPrivateKey(ByteBuffer.wrap(senderKeys.getPrivate().getEncoded()))
// Must be a DER-encoded X.509 public key
.recipientPublicKey(ByteBuffer.wrap(recipient.getPublic().getEncoded()))
.build()
)
.build()
).build();
final IKeyring staticKeyring = materialProviders.CreateRawEcdhKeyring(rawKeyringInput);
}
```
------
#### [ Rust ]
O exemplo de Python a seguir usa o esquema de contrato de `raw_ecdh_static_configuration` chave para configurar estaticamente a chave privada do remetente e a chave pública do destinatário. Ambos os pares de chaves devem estar na mesma curva.
```
// Create keyring input
let raw_ecdh_static_configuration_input =
RawPrivateKeyToStaticPublicKeyInput::builder()
// Must be a UTF8 PEM-encoded private key
.sender_static_private_key(private_key_sender_utf8_bytes)
// Must be a UTF8 DER-encoded X.509 public key
.recipient_public_key(public_key_recipient_utf8_bytes)
.build()?;
let raw_ecdh_static_configuration = RawEcdhStaticConfigurations::RawPrivateKeyToStaticPublicKey(raw_ecdh_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create raw ECDH static keyring
let raw_ecdh_keyring = mpl
.create_raw_ecdh_keyring()
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(raw_ecdh_static_configuration)
.send()
.await?;
```
------
### EphemeralPrivateKeyToStaticPublicKey
Os chaveiros configurados com o esquema de contrato de `EphemeralPrivateKeyToStaticPublicKey` chaves criam um novo par de chaves localmente e derivam uma chave de empacotamento compartilhada exclusiva para cada chamada criptografada.
Esse esquema de contrato de chave só pode criptografar registros. Para descriptografar registros criptografados com o esquema de contrato de `EphemeralPrivateKeyToStaticPublicKey` chave, você deve usar um esquema de contrato de chave de descoberta configurado com a mesma chave pública do destinatário. Para descriptografar, você pode usar um chaveiro ECDH bruto com o algoritmo de acordo de chave ou, se a [`PublicKeyDiscovery`](#raw-ecdh-PublicKeyDiscovery)chave pública do destinatário for de um par de chaves KMS de acordo de chave assimétrico, você pode AWS KMS usar um chaveiro ECDH com o esquema de contrato de chave. [KmsPublicKeyDiscovery](use-kms-ecdh-keyring.md#kms-ecdh-discovery)
Para inicializar um chaveiro ECDH bruto com o esquema de contrato de `EphemeralPrivateKeyToStaticPublicKey` chave, forneça os seguintes valores:
+ **Chave pública do destinatário**
[Você deve fornecer a chave pública X.509 codificada em DER do destinatário, também conhecida como `SubjectPublicKeyInfo` (SPKI), conforme definido na RFC 5280.](https://tools.ietf.org/html/rfc5280)
Você pode especificar a chave pública de um contrato de chave assimétrica (par de chaves KMS) ou a chave pública de um par de chaves gerado fora do. AWS
+ **Especificação da curva**
Identifica a especificação da curva elíptica na chave pública especificada.
Ao criptografar, o chaveiro cria um novo par de chaves na curva especificada e usa a nova chave privada e a chave pública especificada para derivar uma chave de empacotamento compartilhada.
Valores válidos: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
------
#### [ C\$1 / .NET ]
O exemplo a seguir cria um chaveiro ECDH bruto com o esquema de contrato de `EphemeralPrivateKeyToStaticPublicKey` chaves. Ao criptografar, o chaveiro criará um novo par de chaves localmente na curva especificada`ECC_NIST_P256`.
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
var AlicePublicKey = new MemoryStream(new byte[] { });
// Create the Raw ECDH ephemeral keyring
var ephemeralConfiguration = new RawEcdhStaticConfigurations()
{
EphemeralPrivateKeyToStaticPublicKey = new EphemeralPrivateKeyToStaticPublicKeyInput
{
RecipientPublicKey = AlicePublicKey
}
};
var createKeyringInput = new CreateRawEcdhKeyringInput()
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KeyAgreementScheme = ephemeralConfiguration
};
var keyring = materialProviders.CreateRawEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
O exemplo a seguir cria um chaveiro ECDH bruto com o esquema de contrato de `EphemeralPrivateKeyToStaticPublicKey` chaves. Ao criptografar, o chaveiro criará um novo par de chaves localmente na curva especificada`ECC_NIST_P256`.
```
private static void EphemeralRawEcdhKeyring() {
// Instantiate material providers
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
ByteBuffer recipientPublicKey = getPublicKeyBytes();
// Create the Raw ECDH ephemeral keyring
final CreateRawEcdhKeyringInput ephemeralInput =
CreateRawEcdhKeyringInput.builder()
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
RawEcdhStaticConfigurations.builder()
.EphemeralPrivateKeyToStaticPublicKey(
EphemeralPrivateKeyToStaticPublicKeyInput.builder()
.recipientPublicKey(recipientPublicKey)
.build()
)
.build()
).build();
final IKeyring ephemeralKeyring = materialProviders.CreateRawEcdhKeyring(ephemeralInput);
}
```
------
#### [ Rust ]
O exemplo a seguir cria um chaveiro ECDH bruto com o esquema de contrato de `ephemeral_raw_ecdh_static_configuration` chaves. Ao criptografar, o chaveiro criará um novo par de chaves localmente na curva especificada.
```
// Create EphemeralPrivateKeyToStaticPublicKeyInput
let ephemeral_raw_ecdh_static_configuration_input =
EphemeralPrivateKeyToStaticPublicKeyInput::builder()
// Must be a UTF8 DER-encoded X.509 public key
.recipient_public_key(public_key_recipient_utf8_bytes)
.build()?;
let ephemeral_raw_ecdh_static_configuration =
RawEcdhStaticConfigurations::EphemeralPrivateKeyToStaticPublicKey(ephemeral_raw_ecdh_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create raw ECDH ephemeral private key keyring
let ephemeral_raw_ecdh_keyring = mpl
.create_raw_ecdh_keyring()
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(ephemeral_raw_ecdh_static_configuration)
.send()
.await?;
```
------
### PublicKeyDiscovery
Ao descriptografar, é uma prática recomendada especificar as chaves de encapsulamento que o SDK de criptografia de AWS banco de dados pode usar. Para seguir essa prática recomendada, use um chaveiro ECDH que especifique a chave privada do remetente e a chave pública do destinatário. No entanto, você também pode criar um chaveiro de descoberta de ECDH bruto, ou seja, um chaveiro ECDH bruto que pode descriptografar qualquer registro em que a chave pública da chave especificada corresponda à chave pública do destinatário armazenada no campo de descrição do material do registro criptografado. Esse esquema de contrato de chave só pode descriptografar registros.
**Importante**
Ao descriptografar registros usando o esquema de contrato de `PublicKeyDiscovery` chave, você aceita todas as chaves públicas, independentemente de quem as possua.
Para inicializar um chaveiro ECDH bruto com o esquema de contrato de `PublicKeyDiscovery` chave, forneça os seguintes valores:
+ **Chave privada estática do destinatário**
[Você deve fornecer a chave privada codificada por PEM do destinatário ( PrivateKeyInfo estruturas PKCS \$18), conforme definido na RFC 5958.](https://tools.ietf.org/html/rfc5958#section-2)
+ **Especificação da curva**
Identifica a especificação da curva elíptica na chave privada especificada. Os pares de chaves do remetente e do destinatário devem ter a mesma especificação de curva.
Valores válidos: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
------
#### [ C\$1 / .NET ]
O exemplo a seguir cria um chaveiro ECDH bruto com o esquema de contrato de `PublicKeyDiscovery` chaves. Esse chaveiro pode descriptografar qualquer registro em que a chave pública da chave privada especificada corresponda à chave pública do destinatário armazenada no campo de descrição do material do registro criptografado.
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
var AlicePrivateKey = new MemoryStream(new byte[] { });
// Create the Raw ECDH discovery keyring
var discoveryConfiguration = new RawEcdhStaticConfigurations()
{
PublicKeyDiscovery = new PublicKeyDiscoveryInput
{
RecipientStaticPrivateKey = AlicePrivateKey
}
};
var createKeyringInput = new CreateRawEcdhKeyringInput()
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KeyAgreementScheme = discoveryConfiguration
};
var keyring = materialProviders.CreateRawEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
O exemplo a seguir cria um chaveiro ECDH bruto com o esquema de contrato de `PublicKeyDiscovery` chaves. Esse chaveiro pode descriptografar qualquer registro em que a chave pública da chave privada especificada corresponda à chave pública do destinatário armazenada no campo de descrição do material do registro criptografado.
```
private static void RawEcdhDiscovery() {
// Instantiate material providers
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
KeyPair recipient = GetRawEccKey();
// Create the Raw ECDH discovery keyring
final CreateRawEcdhKeyringInput rawKeyringInput =
CreateRawEcdhKeyringInput.builder()
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
RawEcdhStaticConfigurations.builder()
.PublicKeyDiscovery(
PublicKeyDiscoveryInput.builder()
// Must be a PEM-encoded private key
.recipientStaticPrivateKey(ByteBuffer.wrap(sender.getPrivate().getEncoded()))
.build()
)
.build()
).build();
final IKeyring publicKeyDiscovery = materialProviders.CreateRawEcdhKeyring(rawKeyringInput);
}
```
------
#### [ Rust ]
O exemplo a seguir cria um chaveiro ECDH bruto com o esquema de contrato de `discovery_raw_ecdh_static_configuration` chaves. Esse chaveiro pode descriptografar qualquer mensagem em que a chave pública da chave privada especificada corresponda à chave pública do destinatário armazenada no texto cifrado da mensagem.
```
// Create PublicKeyDiscoveryInput
let discovery_raw_ecdh_static_configuration_input =
PublicKeyDiscoveryInput::builder()
// Must be a UTF8 PEM-encoded private key
.recipient_static_private_key(private_key_recipient_utf8_bytes)
.build()?;
let discovery_raw_ecdh_static_configuration =
RawEcdhStaticConfigurations::PublicKeyDiscovery(discovery_raw_ecdh_static_configuration_input);
// Create raw ECDH discovery private key keyring
let discovery_raw_ecdh_keyring = mpl
.create_raw_ecdh_keyring()
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(discovery_raw_ecdh_static_configuration)
.send()
.await?;
```
------
# Multitokens de autenticação
****
| |
| --- |
| Nossa biblioteca de criptografia do lado do cliente foi renomeada para SDK de criptografia de AWS banco de dados. Este guia do desenvolvedor ainda fornece informações sobre o [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
É possível combinar tokens de autenticação em um multitoken de autenticação. Um *multitoken de autenticação* é um token que consiste em um ou mais tokens de autenticação individuais do mesmo ou de outro tipo. O efeito é como se estivesse usando vários tokens de autenticação em uma série. Quando você usa um multitoken de autenticação para criptografar dados, qualquer uma das chaves de empacotamento em qualquer um de seus tokens de autenticação pode descriptografar esses dados.
Ao criar um multitoken de autenticação para criptografar dados, é possível designar um dos tokens de autenticação como o *token de autenticação gerador*. Todos os outros tokens de autenticação são conhecidos como *tokens de autenticação filho*. O token de autenticação gerador cria e criptografa a chave de dados em texto simples. Depois, todas as chaves de empacotamento em todos os tokens filho criptografam a mesma chave de dados em texto simples. O multitoken de autenticação retorna a chave em texto simples e uma chave de dados criptografada para cada chave de empacotamento do multitoken de autenticação. Se o chaveiro do gerador for um [chaveiro KMS](use-kms-keyring.md), a chave do gerador no AWS KMS chaveiro gera e criptografa a chave de texto simples. Em seguida, todas as chaves adicionais AWS KMS keys no AWS KMS chaveiro e todas as chaves de embrulho em todos os chaveiros secundários do chaveiro múltiplo criptografam a mesma chave de texto sem formatação.
Ao descriptografar, o SDK de criptografia AWS de banco de dados usa os chaveiros para tentar descriptografar uma das chaves de dados criptografadas. Os tokens de autenticação são chamados na ordem em que são especificados no multitoken de autenticação. O processamento para assim que qualquer chave em qualquer token de autenticação pode descriptografar uma chave de dados criptografada.
Para criar um multitoken de autenticação, primeiro instancie os tokens de autenticação filho. Neste exemplo, usamos um AWS KMS chaveiro e um chaveiro AES bruto, mas você pode combinar qualquer chaveiro compatível em um chaveiro múltiplo.
------
#### [ Java ]
```
// 1. Create the raw AES keyring.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateRawAesKeyringInput createRawAesKeyringInput = CreateRawAesKeyringInput.builder()
.keyName("AES_256_012")
.keyNamespace("HSM_01")
.wrappingKey(AESWrappingKey)
.wrappingAlg(AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16)
.build();
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(createRawAesKeyringInput);
// 2. Create the AWS KMS keyring.
final CreateAwsKmsMrkMultiKeyringInput createAwsKmsMrkMultiKeyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyArn)
.build();
IKeyring awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
```
// 1. Create the raw AES keyring.
var keyNamespace = "HSM_01";
var keyName = "AES_256_012";
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var createRawAesKeyringInput = new CreateRawAesKeyringInput
{
KeyName = "keyName",
KeyNamespace = "myNamespaces",
WrappingKey = AESWrappingKey,
WrappingAlg = AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
};
var rawAesKeyring = matProv.CreateRawAesKeyring(createRawAesKeyringInput);
// 2. Create the AWS KMS keyring.
// We create a MRK multi keyring, as this interface also supports
// single-region KMS keys,
// and creates the KMS client for us automatically.
var createAwsKmsMrkMultiKeyringInput = new CreateAwsKmsMrkMultiKeyringInput
{
Generator = keyArn
};
var awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ Rust ]
```
// 1. Create the raw AES keyring
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let raw_aes_keyring = mpl
.create_raw_aes_keyring()
.key_name("AES_256_012")
.key_namespace("HSM_01")
.wrapping_key(aes_key_bytes)
.wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
.send()
.await?;
// 2. Create the AWS KMS keyring
let aws_kms_mrk_multi_keyring = mpl
.create_aws_kms_mrk_multi_keyring()
.generator(key_arn)
.send()
.await?;
```
------
Em seguida, crie o multitoken de autenticação e especifique seu token gerador, se houver. Neste exemplo, criamos um chaveiro múltiplo no qual o chaveiro é o AWS KMS chaveiro do gerador e o chaveiro AES é o chaveiro infantil.
------
#### [ Java ]
O `CreateMultiKeyringInput` construtor Java permite definir um gerador de chaveiros e um chaveiro secundário. O objeto `createMultiKeyringInput` resultante é imutável.
```
final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
.generator(awsKmsMrkMultiKeyring)
.childKeyrings(Collections.singletonList(rawAesKeyring))
.build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
```
------
#### [ C\$1 / .NET ]
O construtor.NET `CreateMultiKeyringInput` permite definir um token de autenticação gerador e tokens de autenticação secundários. O objeto `CreateMultiKeyringInput` resultante é imutável.
```
var createMultiKeyringInput = new CreateMultiKeyringInput
{
Generator = awsKmsMrkMultiKeyring,
ChildKeyrings = new List { rawAesKeyring }
};
var multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
```
------
#### [ Rust ]
```
let multi_keyring = mpl
.create_multi_keyring()
.generator(aws_kms_mrk_multi_keyring)
.child_keyrings(vec![raw_aes_keyring.clone()])
.send()
.await?;
```
------
Agora, é possível usar o multitoken de autenticação para criptografar e descriptografar dados.