AWS KMS chaveiros - AWS Encryption SDK
Permissões necessárias para tokens de autenticação do AWS KMSIdentificação AWS KMS keys em um AWS KMS chaveiroCriação de um AWS KMS chaveiro para criptografiaCriando um AWS KMS chaveiro para decodificaçãoUsando um chaveiro AWS KMS DiscoveryUsando um chaveiro de descoberta AWS KMS regional

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á.

AWS KMS chaveiros

Um AWS KMS chaveiro usa criptografia simétrica AWS KMS keyspara 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ê pode usar uma chave AWS KMS multirregional em um AWS KMS chaveiro ou provedor de chave mestra a partir da versão 2.3. x do AWS Encryption SDK e versão 3.0. x da CLI AWS de criptografia. Para obter detalhes e exemplos de como usar do novo símbolo compatível com várias regiões, consulte Usar AWS KMS keys multirregionais. Para obter mais informações sobre chaves multirregionais, consulte Usar chaves multirregionais no Guia do Desenvolvedor do AWS Key Management Service .

nota

Versão 4. x do AWS Encryption SDK para .NET e versão 3. x das AWS Encryption SDK for Java são as únicas implementações de linguagem de programação que suportam AWS KMS chaveiros que usam RSA assimétrico. AWS KMS keys

Se você tentar incluir uma chave do KMS assimétrica em um token de autenticação de criptografia que esteja em outra implementação de linguagem, a chamada de criptografia falhará. Se você incluí-la em um token de autenticação de descriptografia, ele será ignorado.

Todas as menções aos chaveiros KMS AWS Encryption SDK se referem aos chaveiros. AWS KMS

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.

Ao criptografar, o AWS KMS chaveiro que você usa deve ter uma chave geradora. Para a descriptografia, a chave geradora é opcional e a distinção entre chaves geradoras e chaves adicionais é ignorada.

Quando um chaveiro de AWS KMS criptografia 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 do mesmo tipo ou de um tipo diferente.

Permissões necessárias para tokens de autenticação do AWS KMS

O AWS Encryption SDK não requer 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 em seu chaveiro.

  • Para criptografar com um AWS KMS chaveiro, você precisa da GenerateDataKey permissão kms: na chave do gerador. Você precisa da permissão KMS:Encrypt em todas as chaves adicionais no chaveiro. AWS KMS

  • Para descriptografar com um AWS KMS chaveiro, você precisa da permissão kms:Decrypt 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: na chave do gerador no chaveiro do gerador. Você precisa da permissão kms:Encrypt em todas as outras chaves em todos os outros tokens de autenticação do AWS KMS .

Para obter informações detalhadas sobre permissões para AWS KMS keys, consulte Autenticação e controle de acesso 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, consulteIdentificadores de chave 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.

  • Em um chaveiro de criptografia para o AWS Encryption SDK for C, você pode usar um ARN de chave ou um alias ARN para identificar chaves KMS. Em todas as outras implementações de linguagem, você pode usar um ID de chave, ARN de chave, nome de alias ou ARN de alias para criptografar dados.

  • Em um token de autenticação de descriptografia, você deve usar um ARN de chave para identificar AWS KMS keys. Esse requisito aplica-se a todas as implementações de linguagem do AWS Encryption SDK. Para obter detalhes, consulte Seleção de chaves de encapsulamento.

  • Em um token de autenticação usado para criptografia e descriptografia, você deve usar um ARN de chave para identificar AWS KMS keys. Esse requisito aplica-se a todas as implementações de linguagem do AWS Encryption SDK.

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.

Criação de um AWS KMS chaveiro para criptografia

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 As AWS KMS keys devem ser chaves de criptografia simétrica (SYMMETRIC_DEFAULT). Também é possível usar uma chave do KMS multirregional de criptografia simétrica. Como ocorre com todos os tokens de autenticação, é possível usar um ou mais tokens de autenticação do AWS KMS em um multitoken de autenticação.

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 a mensagem criptografada protegida por esse chaveiro, o chaveiro que você usa deve incluir pelo menos um dos AWS KMS keys definidos no chaveiro, ou não. AWS KMS keys(Um AWS KMS chaveiro sem AWS KMS keys é conhecido como chaveiro AWS KMS Discovery.)

Em implementações de AWS Encryption SDK linguagem diferentes da AWS Encryption SDK for C, todas as chaves agrupadas em um chaveiro de criptografia ou em vários chaveiros devem ser capazes de criptografar a chave de dados. Se alguma chave de encapsulamento falhar na criptografia, o método de criptografia falhará. Como resultado, o chamador deve ter as permissões necessárias 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á. A exceção é a AWS Encryption SDK for C, em que a operação de criptografia ignora um chaveiro de descoberta padrão, mas falha se você especificar um chaveiro de descoberta de várias regiões, sozinho ou em um chaveiro com várias chaves.

Os exemplos a seguir criam um AWS KMS chaveiro com uma chave geradora e uma chave adicional. Esses exemplos usam ARNs de chave para identificar as chaves do KMS. Essa é uma prática recomendada para AWS KMS chaveiros usados para criptografia e um requisito para AWS KMS chaveiros usados para decodificação. Para obter detalhes, consulte Identificação AWS KMS keys em um AWS KMS chaveiro.

C

Para identificar um AWS KMS key em um chaveiro de criptografia no AWS Encryption SDK for C, especifique o ARN da chave ou o ARN do alias. Em um token de autenticação de descriptografia, é necessário usar um ARN de chave. Para obter detalhes, consulte Identificação AWS KMS keys em um AWS KMS chaveiro.

Para obter um exemplo completo, consulte string.cpp.

const char * generator_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"

const char * additional_key = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"    

struct aws_cryptosdk_keyring *kms_encrypt_keyring = 
       Aws::Cryptosdk::KmsKeyring::Builder().Build(generator_key,{additional_key});
C# / .NET

Para criar um AWS KMS chaveiro com uma ou várias AWS KMS chaves no para.NET, crie um chaveiro múltiplo. AWS Encryption SDK O AWS Encryption SDK for.NET inclui um chaveiro múltiplo apenas para AWS KMS chaves.

Ao especificar um AWS KMS key para um chaveiro de criptografia no AWS Encryption SDK para.NET, você pode usar qualquer identificador de chave válido: um ID de chave, ARN de chave, nome de alias ou ARN de alias. Para obter ajuda para identificar o AWS KMS keys em um AWS KMS chaveiro, consulteIdentificação AWS KMS keys em um AWS KMS chaveiro.

O exemplo a seguir usa a versão 4. x do AWS Encryption SDK para que o.NET crie um AWS KMS chaveiro com uma chave geradora e chaves adicionais. Para ver um exemplo completo, consulte AwsKmsMultiKeyringExample.cs.

// Instantiate the AWS Encryption SDK and material provider
var mpl = new MaterialProviders(new MaterialProvidersConfig());
var esdk =  new ESDK(new AwsEncryptionSdkConfig());

string generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<string> additionalKey = new List<string> { "alias/exampleAlias" };

// Instantiate the keyring input object
var kmsEncryptKeyringInput = new CreateAwsKmsMultiKeyringInput
{
    Generator = generatorKey,
    KmsKeyIds = additionalKey
};

var kmsEncryptKeyring = materialProviders.CreateAwsKmsMultiKeyring(kmsEncryptKeyringInput);
JavaScript Browser

Ao especificar um AWS KMS key para um chaveiro de criptografia no AWS Encryption SDK para JavaScript, você pode usar qualquer identificador de chave válido: um ID de chave, ARN da chave, nome do alias ou ARN do alias. Para obter ajuda para identificar o AWS KMS keys em um AWS KMS chaveiro, consulteIdentificação AWS KMS keys em um AWS KMS chaveiro.

Para ver um exemplo completo, consulte kms_simple.ts no repositório em. AWS Encryption SDK para JavaScript GitHub

const clientProvider = getClient(KMS, { credentials })
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
const additionalKey = 'alias/exampleAlias'

const keyring = new KmsKeyringBrowser({
  clientProvider, 
  generatorKeyId, 
  keyIds: [additionalKey] 
})
JavaScript Node.js

Ao especificar um AWS KMS key para um chaveiro de criptografia no AWS Encryption SDK para JavaScript, você pode usar qualquer identificador de chave válido: um ID de chave, ARN da chave, nome do alias ou ARN do alias. Para obter ajuda para identificar o AWS KMS keys em um AWS KMS chaveiro, consulteIdentificação AWS KMS keys em um AWS KMS chaveiro.

Para ver um exemplo completo, consulte kms_simple.ts no repositório em. AWS Encryption SDK para JavaScript GitHub

const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
                            
const additionalKey = 'alias/exampleAlias'

const keyring = new KmsKeyringNode({
  generatorKeyId,
  keyIds: [additionalKey]
})
Java

Para criar um AWS KMS chaveiro com uma ou várias AWS KMS chaves no AWS Encryption SDK for Java, crie um chaveiro múltiplo. AWS Encryption SDK for Java Inclui um chaveiro múltiplo apenas para AWS KMS chaves.

Ao especificar um AWS KMS key para um chaveiro de criptografia no AWS Encryption SDK for Java, você pode usar qualquer identificador de chave válido: um ID de chave, ARN da chave, nome do alias ou ARN do alias. Para obter ajuda para identificar o AWS KMS keys em um AWS KMS chaveiro, consulteIdentificação AWS KMS keys em um AWS KMS chaveiro.

Para ver um exemplo completo, consulte BasicEncryptionKeyringExample.java no AWS Encryption SDK for Java repositório em. GitHub

 // Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
            .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
            .build();

String generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<String> additionalKey = Collections.singletonList("alias/exampleAlias");

// Create the AWS KMS keyring
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
        .generator(generatorKey)
        .kmsKeyIds(additionalKey)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);

Criando um AWS KMS chaveiro para decodificação

Você também especifica um AWS KMS chaveiro ao descriptografar a mensagem criptografada que ele retorna. AWS Encryption SDK Se o chaveiro de descriptografia especificar AWS KMS keys, eles AWS Encryption SDK usarão somente essas chaves de encapsulamento para descriptografar as chaves de dados criptografadas na mensagem criptografada. (Você também pode usar um chaveiro de AWS KMS descoberta, que não especifica nenhum AWS KMS keys.)

Ao descriptografar, ele AWS Encryption SDK pesquisa no AWS KMS chaveiro por uma AWS KMS key que possa descriptografar uma das chaves de dados criptografadas. Especificamente, o AWS Encryption SDK usa o seguinte padrão para cada chave de dados criptografada em uma mensagem criptografada.

  • O AWS Encryption SDK obtém o ARN da chave AWS KMS key que criptografou a chave de dados a partir dos metadados da mensagem criptografada.

  • O AWS Encryption SDK pesquisa no chaveiro de decodificação por um AWS KMS key com um ARN de chave correspondente.

  • Se encontrar um ARN AWS KMS key com uma chave correspondente no chaveiro, ele AWS Encryption SDK 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.

Ele AWS Encryption SDK nunca tenta descriptografar uma chave de dados criptografada, a menos que o ARN da chave AWS KMS key que criptografou essa chave de dados esteja incluído no chaveiro de decodificação. Se o chaveiro de decodificação não incluir os ARNs de nenhuma das chaves de dados AWS KMS keys criptografadas, a chamada de decodificação AWS Encryption SDK falhará sem nunca ligar. AWS KMS

A partir da versão 1.7. x, ao descriptografar uma chave de dados criptografada, AWS Encryption SDK sempre passa o ARN da chave AWS KMS key para o KeyId parâmetro da operação Decrypt. AWS KMS Identificar o AWS KMS key ao descriptografar é uma prática AWS KMS recomendada que garante que você descriptografe a chave de dados criptografada com a chave de empacotamento que você pretende usar.

Uma chamada de decodificação com um AWS KMS chaveiro é bem-sucedida quando pelo menos uma no chaveiro de decodificação pode descriptografar uma das chaves de dados criptografadas AWS KMS key na mensagem criptografada. Além disso, o chamador deve ter a permissão kms:Decrypt para essa AWS KMS key. Esse comportamento permite que você Regiões da AWS criptografe dados AWS KMS keys em vários em diferentes contas, mas forneça um chaveiro de descriptografia mais limitado, adaptado a uma conta, região, usuário, grupo ou função específica.

Ao especificar um AWS KMS key em um chaveiro de descriptografia, você deve usar o ARN da chave. Caso contrário, AWS KMS key o não será reconhecido. Para ajudar a encontrar o ARN de chave, consulte Descobrir o ID de chave e o ARN no Guia do desenvolvedor do AWS Key Management Service .

nota

Se você reutilizar um token de autenticação de criptografia para descriptografar, verifique se as AWS KMS keys no token de autenticação são identificadas por seus ARNs de chave.

Por exemplo, o AWS KMS chaveiro a seguir inclui somente a chave adicional que foi usada no chaveiro de criptografia. No entanto, em vez de se referir à chave adicional por meio de seu alias, alias/exampleAlias, o exemplo usa o ARN de chave da chave adicional, conforme exigido pelas chamadas de descriptografia.

Você pode usar esse token de autenticação para descriptografar uma mensagem que foi criptografada sob a chave geradora e a chave adicional, desde que você tenha permissão para usar a chave adicional para descriptografar dados.

C
const char * additional_key = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"    

struct aws_cryptosdk_keyring *kms_decrypt_keyring = 
       Aws::Cryptosdk::KmsKeyring::Builder().Build(additional_key);
C# / .NET

Como esse chaveiro de decodificação inclui somente uma AWS KMS chave, o exemplo usa o CreateAwsKmsKeyring() método com uma instância de seu objeto. CreateAwsKmsKeyringInput Para criar um AWS KMS chaveiro com uma AWS KMS chave, você pode usar um chaveiro de uma ou várias teclas. Para obter detalhes, consulte Criptografia de dados no AWS Encryption SDK para .NET. O exemplo a seguir usa a versão 4. x do AWS Encryption SDK para o.NET para criar um AWS KMS chaveiro para decodificação.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string additionalKey = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321";

// Instantiate a KMS keyring for one AWS KMS key.
var kmsDecryptKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = additionalKey
};

var kmsDecryptKeyring = materialProviders.CreateAwsKmsKeyring(kmsDecryptKeyringInput);
JavaScript Browser
const clientProvider = getClient(KMS, { credentials })
const additionalKey = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321'

const keyring = new KmsKeyringBrowser({ clientProvider, keyIds: [additionalKey] })
JavaScript Node.js
const additionalKey = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321'

const keyring = new KmsKeyringNode({ keyIds: [additionalKey] })
Java

Como esse chaveiro de decodificação inclui somente uma AWS KMS chave, o exemplo usa o CreateAwsKmsKeyring() método com uma instância de seu objeto. CreateAwsKmsKeyringInput Para criar um AWS KMS chaveiro com uma AWS KMS chave, você pode usar um chaveiro de uma ou várias teclas.

// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
        
String additionalKey = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321";

// Create a AwsKmsKeyring
CreateAwsKmsKeyringInput kmsDecryptKeyringInput = CreateAwsKmsKeyringInput.builder()
        .generator(additionalKey)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(kmsDecryptKeyringInput);

Você também pode usar um AWS KMS chaveiro que especifica uma chave geradora para descriptografia, como a seguinte. Ao descriptografar, o AWS Encryption SDK ignora a distinção entre chaves geradoras e chaves adicionais. Ele pode usar qualquer um dos especificados AWS KMS keys para descriptografar uma chave de dados criptografada. A chamada para é AWS KMS bem-sucedida somente quando o chamador tem permissão para usá-la para AWS KMS key descriptografar dados.

C
struct aws_cryptosdk_keyring *kms_decrypt_keyring = 
       Aws::Cryptosdk::KmsKeyring::Builder().Build(generator_key, {additional_key, other_key});
C# / .NET

O exemplo a seguir usa a versão 4.x do AWS Encryption SDK para .NET.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Instantiate a KMS keyring for one AWS KMS key.
var kmsDecryptKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = generatorKey
};

var kmsDecryptKeyring = materialProviders.CreateAwsKmsKeyring(kmsDecryptKeyringInput);
JavaScript Browser
const clientProvider = getClient(KMS, { credentials })

const keyring = new KmsKeyringBrowser({
  clientProvider, 
  generatorKeyId, 
  keyIds: [additionalKey, otherKey]
})
JavaScript Node.js
const keyring = new KmsKeyringNode({
  generatorKeyId,
  keyIds: [additionalKey, otherKey]
})
Java
// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
        
String generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a AwsKmsKeyring
CreateAwsKmsKeyringInput kmsDecryptKeyringInput = CreateAwsKmsKeyringInput.builder()
        .generator(generatorKey)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(kmsDecryptKeyringInput);

Ao contrário de um chaveiro de criptografia que usa todos os itens especificados AWS KMS keys, você pode descriptografar uma mensagem criptografada usando um chaveiro de decodificação que inclui AWS KMS keys aqueles que não estão relacionados à mensagem criptografada e AWS KMS keys que o chamador não tem permissão para usar. Se ocorrer uma falha em uma chamada de descriptografia do AWS KMS , por exemplo, quando o chamador não tem a permissão necessária, o AWS Encryption SDK simplesmente pula para a próxima chave de dados criptografada.

Usando um chaveiro AWS KMS Discovery

Ao descriptografar, é uma prática recomendada especificar as chaves de encapsulamento que podem ser usadas. AWS Encryption SDK 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.

AWS Encryption SDK Fornece um chaveiro de AWS KMS descoberta padrão e um chaveiro de descoberta para chaves AWS KMS multirregionais. Para obter informações sobre o uso de chaves multirregionais com o AWS Encryption SDK, consulteUsar AWS KMS keys multirregionais.

Como não especifica nenhuma chave de encapsulamento, 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á. A exceção é a AWS Encryption SDK for C, em que a operação de criptografia ignora um chaveiro de descoberta padrão, mas falha se você especificar um chaveiro de descoberta de várias regiões, sozinho ou em um chaveiro com várias chaves.

Ao descriptografar, um chaveiro de descoberta permite que você solicite AWS Encryption SDK 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 decodificação múltipla, o chaveiro 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. Um chaveiro de AWS KMS descoberta não tem efeito na criptografia quando usado sozinho ou em um chaveiro múltiplo.

AWS Encryption SDK Ele fornece um chaveiro AWS KMS Discovery 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 chave usada para criptografar uma chave de dados na mensagem criptografada, apenas para AWS KMS key que o chamador tenha permissão para usá-la para descriptografar. AWS KMS key Essa pode não ser a 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 AWS Encryption SDK tenta descriptografar todas as chaves de dados criptografadas, incluindo aquelas criptografadas AWS KMS keys em 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 para limitar as chaves KMS que podem ser usadas para aquelas em partições Contas da AWS e partições especificadas. Os filtros de descoberta são compatíveis com as versões 1.7.x e posteriores do AWS Encryption SDK. Para obter ajuda para encontrar seu ID de conta e partição, consulte Seus identificadores da Conta da AWS e Formato de ARN no. Referência geral da AWS.

O código a seguir instancia um chaveiro de AWS KMS descoberta com um filtro de descoberta que limita as chaves KMS que AWS Encryption SDK podem ser usadas às da aws partição e da 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 suas chaves KMS estiverem inseridas AWS GovCloud (US) Regions, use o valor da aws-us-gov partição. Para todos os outros Regiões da AWS, use o valor da aws partição.

C

Para obter um exemplo completo, consulte: kms_discovery.cpp.

std::shared_ptr<KmsKeyring::> discovery_filter(
    KmsKeyring::DiscoveryFilter::Builder("aws")
        .AddAccount("111122223333")
        .Build());

struct aws_cryptosdk_keyring *kms_discovery_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
       .BuildDiscovery(discovery_filter));
C# / .NET

O exemplo a seguir usa a versão 4.x do AWS Encryption SDK para .NET.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

List<string> account = new List<string> { "111122223333" };
        
// In a discovery keyring, you specify an AWS KMS client and a discovery filter,
// but not a AWS KMS key
var kmsDiscoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    DiscoveryFilter = new DiscoveryFilter()
    {
        AccountIds = account,
        Partition = "aws"
    }
};
        
var kmsDiscoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(kmsDiscoveryKeyringInput);
JavaScript Browser

Em JavaScript, você deve especificar explicitamente a propriedade de descoberta.

const clientProvider = getClient(KMS, { credentials })

const discovery = true
const keyring = new KmsKeyringBrowser(clientProvider, {
    discovery,
    discoveryFilter: { accountIDs: [111122223333], partition: 'aws' }
})
JavaScript Node.js

Em JavaScript, você deve especificar explicitamente a propriedade de descoberta.

const discovery = true

const keyring = new KmsKeyringNode({
    discovery,
    discoveryFilter: { accountIDs: ['111122223333'], partition: '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);

Usando um chaveiro de descoberta AWS KMS regional

Um token de autenticação de descoberta regional AWS KMS é um token de autenticação que não especifica os ARNs das chaves do KMS. Em vez disso, ele permite que AWS Encryption SDK o decodifique usando somente as chaves KMS em particular. Regiões da AWS

Ao descriptografar com um chaveiro de descoberta AWS KMS regional, ele AWS Encryption SDK descriptografa qualquer chave de dados criptografada que tenha sido criptografada sob 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 token de autenticação de descoberta, o token de autenticação de descoberta regional não afeta a criptografia. Ele funciona somente ao descriptografar mensagens criptografadas. Se você usar um token de autenticação de descoberta regional em um multitoken de autenticação 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 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 chaveiro de AWS KMS descoberta não tem efeito na criptografia quando usado sozinho ou em um chaveiro múltiplo.

O chaveiro de descoberta regional nas AWS Encryption SDK for C tentativas de descriptografar somente com chaves KMS na região especificada. Ao usar um chaveiro de descoberta no AWS Encryption SDK para JavaScript e AWS Encryption SDK para.NET, você configura a região no AWS KMS cliente. Essas AWS Encryption SDK implementações não filtram as chaves KMS por região, mas AWS KMS falharão em uma solicitação de descriptografia de chaves 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 Os filtros de descoberta são compatíveis com as versões 1.7.x e posteriores do AWS Encryption SDK.

Por exemplo, o código a seguir cria um chaveiro de descoberta AWS KMS regional com um filtro de descoberta. Esse chaveiro limita as duas AWS Encryption SDK chaves KMS na conta 111122223333 na região Oeste dos EUA (Oregon) (us-west-2).

C

Para exibir esse token de autenticação e o método create_kms_client em um exemplo funcional, consulte kms_discovery.cpp.

std::shared_ptr<KmsKeyring::DiscoveryFilter> discovery_filter(
    KmsKeyring::DiscoveryFilter::Builder("aws")
        .AddAccount("111122223333")
        .Build());

struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
       .WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery(discovery_filter));
C# / .NET

O AWS Encryption SDK for.NET não tem um chaveiro de descoberta regional dedicado. Porém, você pode usar várias técnicas para limitar as chaves KMS usadas ao descriptografar para uma região específica.

A maneira mais eficiente de limitar as regiões em um token de autenticação de descoberta é usar um token de autenticação de descoberta compatível com várias regiões, mesmo que você tenha criptografado os dados usando somente chaves de uma única região. Quando encontra chaves de uma única região, o token de autenticação compatível com várias regiões não usa nenhum atributo multirregional.

O token de autenticação retornado pelo método CreateAwsKmsMrkDiscoveryKeyring() filtra as chaves do por região antes de chamar o AWS KMS. Ele envia uma solicitação de descriptografia AWS KMS somente quando a chave de dados criptografada foi criptografada por uma chave KMS na região especificada pelo Region parâmetro no objeto. CreateAwsKmsMrkDiscoveryKeyringInput

Os exemplos a seguir usam a versão 4. x do AWS Encryption SDK para o.NET.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

List<string> account = new List<string> { "111122223333" };

// Create the discovery filter
var filter = DiscoveryFilter = new DiscoveryFilter
{
    AccountIds = account,
    Partition = "aws"
};
                                
var regionalDiscoveryKeyringInput = new CreateAwsKmsMrkDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    Region = RegionEndpoint.USWest2,
    DiscoveryFilter = filter
};                                

var kmsRegionalDiscoveryKeyring = materialProviders.CreateAwsKmsMrkDiscoveryKeyring(regionalDiscoveryKeyringInput);

Você também pode limitar as chaves KMS a uma determinada Região da AWS especificando uma região na sua instância do AWS KMS cliente () AmazonKeyManagementServiceClient. No entanto, essa configuração é menos eficiente e potencialmente mais cara do que usar um token de autenticação de descoberta compatível com várias regiões. Em vez de filtrar as chaves KMS por região antes da chamada AWS KMS, o AWS Encryption SDK for.NET chama AWS KMS cada chave de dados criptografada (até decifrar uma) e se baseia em limitar as chaves KMS que usa AWS KMS à região especificada.

O exemplo a seguir usa a versão 4.x do AWS Encryption SDK para .NET.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

List<string> account = new List<string> { "111122223333" };
        
// Create the discovery filter,
// but not a AWS KMS key
var createRegionalDiscoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    DiscoveryFilter = new DiscoveryFilter()
    {
        AccountIds = account,
        Partition = "aws"
    }
};
        
var kmsRegionalDiscoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(createRegionalDiscoveryKeyringInput);
JavaScript Browser
const clientProvider = getClient(KMS, { credentials })

const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser(clientProvider, {
    discovery,
    discoveryFilter: { accountIDs: ['111122223333'], partition: 'aws' }
})
JavaScript Node.js

Para visualizar este token de autenticação e as limitRegions e a função, em um exemplo prático, consulte kms_regional_discovery.ts.

const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({
    clientProvider,
    discovery,
    discoveryFilter: { accountIDs: ['111122223333'], partition: 'aws' }
})
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);

Ele AWS Encryption SDK para JavaScript também exporta uma excludeRegions função para o Node.js e o navegador. Essa função cria um chaveiro de descoberta AWS KMS regional que é omitido AWS KMS keys em regiões específicas. O exemplo a seguir cria um chaveiro de descoberta AWS KMS regional que pode ser usado AWS KMS keys na conta 111122223333 em todos, Região da AWS exceto no Leste dos EUA (Norte da Virgínia) (us-east-1).

O AWS Encryption SDK for C não tem um método análogo, mas você pode implementá-lo criando um personalizado ClientSupplier.

Este exemplo mostra o código para Node.js.

const discovery = true
const clientProvider = excludeRegions(['us-east-1'], getKmsClient)
const keyring = new KmsKeyringNode({
    clientProvider,
    discovery,
    discoveryFilter: { accountIDs: [111122223333], partition: 'aws' }
})