Tokens de autenticação do AWS KMS - AWS Encryption SDK

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 do AWS KMS

Um token de autenticação do AWS KMS usa criptografia simétrica do AWS KMS keys para gerar, criptografar e descriptografar chaves de dados. O AWS Key Management Service (AWS KMS) protege suas chaves do KMS e executa operações criptográficas dentro do limite do FIPS. É recomendável usar um token de autenticação do AWS KMS ou um token de autenticação 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 de tokens de autenticação do KMS no AWS Encryption SDK referem-se a tokens de autenticação do AWS KMS.

Os tokens de autenticação do AWS KMS podem incluir dois tipos de chaves de encapsulamento:

  • 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 criada pela chave do gerador. Os tokens de autenticação do AWS KMS podem ter zero ou mais chaves adicionais.

Ao criptografar, o token de autenticação do AWS KMS usado 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 token de autenticação de criptografia do AWS KMS tiver apenas uma chave do AWS KMS, essa chave será usada para gerar e criptografar a chave de dados.

Como todos os tokens de autenticação, os tokens de autenticação do AWS KMS podem ser usados de forma independente ou em um multitoken de autenticação com outros tokens de autenticação do mesmo ou de outro tipo.

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

O AWS Encryption SDK não requer uma Conta da AWS e não depende de nenhum AWS service (Serviço da AWS). No entanto, para usar um token de autenticação do AWS KMS você precisa de uma Conta da AWS e das seguintes permissões mínimas na AWS KMS keys no seu token token de autenticação.

  • 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 token de autenticação do AWS KMS.

  • Para descriptografar com um token de autenticação do AWS KMS, você precisa de permissão kms:Decrypt em pelo menos uma chave no token de autenticação do 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 desenvolvedor do AWS Key Management Service.

Identificar AWS KMS keys em um token de autenticação do AWS KMS

Um token de autenticação do AWS KMS pode incluir uma ou mais AWS KMS keys. Para especificar uma AWS KMS key em um token de autenticação do AWS KMS, use um identificador de chave do AWS KMS compatível. Os identificadores de chave que você pode usar para identificar uma AWS KMS key em um token de autenticação 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 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 token de autenticação de criptografia para o AWS Encryption SDK for C, você pode usar um ARN de chave ou um ARN de alias para identificar chaves do 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. Ela não salvará o alias. As alterações no alias não afetam a chave do KMS usada para descriptografar suas chaves de dados criptografadas.

Criar um token de autenticação do AWS KMS para criptografia

É possível configurar cada token de autenticação do AWS KMS com uma únicaAWS KMS key ou várias AWS KMS keys em Contas da AWS e Regiões da AWS diferentes ou iguais. 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.

Quando você cria um token de autenticação do AWS KMS para criptografar dados, deve especificar uma chave geradora, que é uma AWS KMS key que gera uma chave de dados de texto simples e a criptografa. A chave de dados não tem relação matemática com a chave do KMS. Depois, se você optar, poderá especificar outras AWS KMS keys que criptografam a mesma chave de dados de texto simples.

Para descriptografar a mensagem criptografada protegida por este token de autenticação, o token de autenticação que você usa deve incluir pelo menos uma das AWS KMS keys que criptografaram a chave de dados, ou não incluir nenhuma AWS KMS keys. (Um token de autenticação do AWS KMS sem a AWS KMS keys é conhecido como um token de autenticação de descoberta do AWS KMS.)

Nas implementações de linguagem do AWS Encryption SDK que não sejam AWS Encryption SDK for C, todas as chaves de encapsulamento em um token de autenticação ou em um multitoken de autenticação 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, onde a operação de criptografia ignora um token de autenticação de descoberta padrão, mas falha se você especificar um token de autenticação de descoberta de várias regiões, sozinho ou em um multitoken de autenticação.

Os exemplos a seguir criam um token de autenticação do AWS KMS 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 tokens de autenticação do AWS KMS usados para criptografia e é um requisito para tokens de autenticação do AWS KMS usados para descriptografia. Para obter detalhes, consulte Identificar AWS KMS keys em um token de autenticação do AWS KMS.

C

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

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 token de autenticação do AWS KMS com uma ou várias chaves do AWS KMS no AWS Encryption SDK para .NET, crie um multitoken. O AWS Encryption SDK para .NET inclui um multitoken somente para chaves do AWS KMS.

Ao especificar uma AWS KMS key para um token de autenticação de criptografia no AWS Encryption SDK para .NET, é possível usar qualquer identificador de chave válido: ID de chave, ARN de chave, nome de alias ou ARN de alias. . Para obter ajuda para identificar o AWS KMS keys em um token de autenticação do AWS KMS, consulte Identificar AWS KMS keys em um token de autenticação do AWS KMS.

O exemplo a seguir usa a versão 4.x do AWS Encryption SDK para .NET a fim de criar um token de autenticação do AWS KMS 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 uma AWS KMS key para um token de autenticação de criptografia no AWS Encryption SDK para JavaScript , é possível 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 token de autenticação do AWS KMS, consulte Identificar AWS KMS keys em um token de autenticação do AWS KMS.

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 uma AWS KMS key para um token de autenticação de criptografia no AWS Encryption SDK para JavaScript , é possível 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 token de autenticação do AWS KMS, consulte Identificar AWS KMS keys em um token de autenticação do AWS KMS.

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 noAWS Encryption SDK for Java, crie um chaveiro múltiplo. AWS Encryption SDK for JavaInclui um chaveiro múltiplo apenas para AWS KMS chaves.

Ao especificar uma AWS KMS key para um token de autenticação de criptografia no AWS Encryption SDK for Java , é possível 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 token de autenticação do AWS KMS, consulte Identificar AWS KMS keys em um token de autenticação do AWS KMS.

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);

Criar um token de autenticação do AWS KMS para descriptografia

Você também especifica um token de autenticação do AWS KMS ao descriptografar a mensagem criptografada retornada pelo AWS Encryption SDK. Se o chaveiro de descriptografia especificar as AWS KMS keys, o AWS Encryption SDK usará somente essas chaves de encapsulamento para descriptografar as chaves de dados criptografadas na mensagem criptografada. (Você também pode usar um token de autenticação de descoberta do AWS KMS, que não especifica AWS KMS keys.)

Ao descriptografar, o AWS Encryption SDK pesquisa o token de autenticação do AWS KMS para encontrar 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 AWS KMS key que criptografou a chave de dados a partir dos metadados da mensagem criptografada.

  • O AWS Encryption SDK pesquisa o token de autenticação de descriptografia para encontrar uma AWS KMS key com um ARN de chave correspondente.

  • Se ele encontrar uma AWS KMS key com um ARN de chave correspondente no token de autenticação, o AWS Encryption SDK solicitará que o AWS KMS use a chave KMS para descriptografar a chave de dados criptografada.

  • Caso contrário, ele passará para a próxima chave de dados criptografada, se houver.

O AWS Encryption SDK nunca tenta descriptografar uma chave de dados criptografada, a menos que o ARN da AWS KMS key que a criptografou esteja incluído no token de autenticação de descriptografia. Se o token de autenticação de descriptografia não incluir os ARNs de nenhuma das AWS KMS keys que criptografaram qualquer uma das chaves de dados, o AWS Encryption SDK não fará a chamada de descriptografia nem chamará o AWS KMS.

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

Uma chamada de descriptografia com um AWS KMS será bem sucedida quando pelo menos uma AWS KMS key no token de autenticação de descriptografia puder descriptografar uma das chaves de dados criptografadas na mensagem criptografada. Além disso, o chamador deve ter a permissão kms:Decrypt para essa AWS KMS key. Esse comportamento permite criptografar dados em várias AWS KMS keys em diferentes Regiões da AWS e contas, mas fornece um token de autenticação de descriptografia mais limitado, personalizado para uma conta, região, usuário, grupo ou função específicos.

Ao especificar uma AWS KMS key em um token de autenticação de descriptografia, você deve usar o ARN de chave dessa chave. Caso contrário, a AWS KMS key não é reconhecida. 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 seguinte token de autenticação do AWS KMS inclui apenas a chave adicional que foi utilizada no token de autenticação 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 token de autenticação de descriptografia inclui somente uma chave do AWS KMS, o exemplo usa o método CreateAwsKmsKeyring() com uma instância do seu objeto CreateAwsKmsKeyringInput. Para criar um token de autenticação do AWS KMS com uma chave do AWS KMS, você pode usar um token de autenticação chave única ou de várias chaves. 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 .NET para criar um token de autenticação do AWS KMS para descriptografia.

// 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 token de autenticação de descriptografia inclui somente uma chave do AWS KMS, o exemplo usa o método CreateAwsKmsKeyring() com uma instância do seu objeto CreateAwsKmsKeyringInput. Para criar um token de autenticação do AWS KMS com uma chave do AWS KMS, você pode usar um token de autenticação chave única ou de várias chaves.

// 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);

Também é possível usar um token de autenticação do AWS KMS que especifica uma chave geradora para a descriptografia, como este a seguir. Na descriptografia, o AWS Encryption SDK ignora a distinção entre chaves geradoras e chaves adicionais. Ele pode usar qualquer uma das AWS KMS keys especificadas para descriptografar uma chave de dados criptografada. A chamada para o AWS KMS terá êxito apenas quando o chamador tiver permissão para usar essa AWS KMS key para 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 token de autenticação de criptografia que usa todas as AWS KMS keys especificadas, você pode descriptografar uma mensagem criptografada usando um token de autenticação de descriptografia que inclui AWS KMS keys não relacionadas à 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.

Usar um token de autenticação de descoberta do AWS KMS

Ao descriptografar, é uma prática recomendada especificar as chaves de encapsulamento que o AWS Encryption SDK pode usar. Para seguir essa prática recomendada, use um token de autenticação de descriptografia do AWS KMS que limite as chaves de encapsulamento do AWS KMS àquelas que você especificar. No entanto, você também pode criar um token de autenticação de descoberta do AWS KMS, ou seja, um token de autenticação do AWS KMS que não especifique chaves de encapsulamento.

O AWS Encryption SDK fornece um token de autenticação do AWS KMS descoberta padrão e um token de autenticação de descoberta para chaves multirregionais da AWS KMS. Para obter informações sobre como usar chaves de várias regiões com o AWS Encryption SDK, consulte Usar 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, onde a operação de criptografia ignora um token de autenticação de descoberta padrão, mas falha se você especificar um token de autenticação de descoberta de várias regiões, sozinho ou em um multitoken de autenticação.

Ao descriptografar, um token de autenticação de descoberta permite que o AWS Encryption SDK solicite que o AWS KMS descriptografe todas as chaves de dados criptografadas de uma mensagem criptografada usando a AWS KMS key que a criptografou, independentemente de quem seja o proprietário ou de quem tenha acesso a essa 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 token de autenticação de descoberta do AWS KMS em um multitoken de autenticação, ele substituirá todas as restrições de chave do KMS especificadas por outros tokens de autenticação no multitoken de autenticação. O multitoken de autenticação se comporta como o token de autenticação menos restritivo presente nele. 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 AWS Encryption SDK fornece um token de autenticação de descoberta do AWS KMS para fins de 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 token de autenticação de descoberta do AWS KMSpode usar qualquer AWS KMS key utilizada para criptografar uma chave de dados na mensagem criptografada, desde que o chamador tenha permissão para usar essa AWS KMS key para descriptografar. 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 com uma AWS KMS key menos segura que qualquer pessoa possa usar.

  • Latência e performance: um token de autenticação de descoberta do AWS KMS pode ser perceptivelmente mais lento do que outros tokens de autenticação porque o AWS Encryption SDK tenta descriptografar todas as chaves de dados criptografadas, inclusive as criptografadas por AWS KMS keys em outras regiões e Contas da AWS, e AWS KMS keys que o autor da chamada não tem permissão para usar para descriptografia.

Se você usar um token de autenticação de descoberta, recomendamos que você use um filtro de descoberta para limitar as chaves do KMS que podem ser utilizadas às chaves em 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 token de autenticação de descoberta do AWS KMS com um filtro de descoberta que limita as chaves do AWS Encryption SDK que podem ser usadas às chaves na partição aws e na conta de exemplo 111122223333.

Antes de usar esse código, substitua os valores de exemplo da Conta da AWS e de partição por valores válidos para sua partição Conta da AWS. Se suas chaves KMS estiverem em regiões da China, use o valor de partição aws-cn. Se suas chaves 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.

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);

Usar um token de autenticação de descoberta regional do AWS KMS

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

Ao descriptografar com um token de autenticação de descoberta regional do AWS KMS, o AWS Encryption SDK descriptografa todas as chaves de dados criptografadas com uma AWS KMS key na Região da AWS especificada. Para ser bem-sucedido, o chamador deverá ter a permissão kms:Decrypt em, pelo menos, uma das AWS KMS keys na Região da AWS especificada 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 multitoken, a operação de criptografia falhará.

Importante

Se você incluir um token de autenticação de descoberta regional do AWS KMSem um multitoken de autenticação de descriptografia, o token de autenticação de descoberta regional substituirá todas as restrições de chave do KMS especificadas por outros tokens de autenticação no multitoken de autenticação. O multitoken de autenticação se comporta como o token de autenticação menos restritivo presente nele. 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 token de autenticação de descoberta regional nas tentativas do AWS Encryption SDK for C de descriptografar somente com chaves do KMS na região especificada. Ao usar um token de autenticação de descoberta no AWS Encryption SDK para JavaScript e AWS Encryption SDK para .NET, você configura a região no cliente de AWS KMS. Essas implementações do AWS Encryption SDK não filtram as chaves KMS por região, mas o AWS KMS falhará uma soclicitação de descriptografia de chaves KMS fora da região especificada.

Se você usa um token de autenticação de descoberta, recomendamos que você use um filtro de descoberta para limitar as chaves KMS usadas na descriptografia àquelas na 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.

Por exemplo, o código a seguir cria um token de autenticação de descoberta regional AWS KMS com um filtro de descoberta. Esse token de autenticação limita o AWS Encryption SDK às chaves do 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 para .NET não tem um token de autenticação 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 ao AWS KMS somente quando a chave de dados criptografada foi criptografada por uma chave KMS na região especificada pelo parâmetro Regionno objeto.CreateAwsKmsMrkDiscoveryKeyringInput.

Os exemplos a seguir usam 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 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 de chamar o AWS KMS, o AWS Encryption SDK para .NET chama o AWS KMS para cada chave de dados criptografada (até descriptografar uma) e depende do AWS KMSpara limitar as chaves KMS que ele usa para a 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);

O AWS Encryption SDK para JavaScript também exporta uma função excludeRegions para o Node.js e o navegador. Esta função cria um token de autenticação de descoberta regional do AWS KMS que omite as AWS KMS keys em regiões específicas. O exemplo a seguir cria um token de autenticação de descoberta regional do AWS KMS que pode usar AWS KMS keys a conta 111122223333 em todas as 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' } })