Usar tokens de autenticação - SDK de criptografia da AWS

Se fornecermos uma tradução da versão em inglês do guia, a versão em inglês prevalecerá caso haja qualquer conflito entre as versões. A tradução é fornecida com o uso de tradução por máquina.

Usar tokens de autenticação

O AWS Encryption SDK para C e o AWS Encryption SDK para JavaScript usam tokens de autenticação para executar criptografia de envelope. Tokens de autenticação geram, criptografam e descriptografam chaves de dados. Os tokens de autenticação que você usa determinam a origem das chaves de dados exclusivas que protegem cada mensagem, bem como as chaves de empacotamento 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. Você pode usar os tokens de autenticação fornecidos pelo SDK ou elaborar seus próprios tokens de autenticação personalizados compatíveis.

É possível usar cada token individualmente ou combiná-los em um multitoken de autenticação. 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 utilize um keyring que proteja as suas chaves de empacotamento e realize operações criptográficas dentro de um limite seguro, como o Token de autenticação do AWS KMS, que utiliza AWS Key Management Service (AWS KMS) chaves mestras do cliente (CMKs) que nunca saem AWS KMS não encriptado. Você também pode escrever um token de autenticação que use chaves de empacotamento armazenadas em seus módulos de segurança de hardware (HSMs) ou sejam protegidas por outros serviços de chave mestra. Para obter detalhes, consulte o tópico Interface do token de autenticação na Especificação do SDK de criptografia da AWS.

Este tópico explica como usar o recurso de token de autenticação do SDK de criptografia da AWS e como escolher um token de autenticação. Para obter exemplos de criação e uso de tokens de autenticação, consulte os tópicos C e JavaScript.

Como os tokens de autenticação funcionam

Uma das tarefas mais importantes que você executa ao usar o AWS Encryption SDK para C ou o JavaScript é selecionar e configurar um token de autenticação. Um token de autenticação gera, criptografa e descriptografa chaves de dados. Em geral, cada token de autenticação está associado a uma chave de empacotamento ou a um serviço que fornece e protege chaves de empacotamento. Você pode usar os tokens de autenticação fornecidos pelo SDK de criptografia da AWS ou elaborar seus próprios tokens de autenticação personalizados compatíveis. Para obter ajuda ao escolher um token de autenticação, consulte as seções a seguir que descrevem cada token de autenticação.

Os tokens de autenticação facilitam determinar quais chaves de empacotamento são usadas para criptografar e descriptografar seus dados. Os tokens de autenticação substituem os provedores de chaves mestras nas implementações Java e Python do SDK de criptografia da AWS. Apesar dessa diferença arquitetônica, todas as implementações de linguagem são totalmente interoperáveis, sujeitas às restrições da linguagem. No entanto, você deve configurar o token de autenticação e o provedor de chaves mestras com as mesmas chaves de empacotamento correspondentes. Para obter mais detalhes, consulte Compatibilidade dos tokens de autenticação.

Você instancia e configura seu token de autenticação, mas não interage com ele diretamente. O gerenciador de materiais criptográficos (CMM) interage com o token de autenticação para você.

Quando você criptografa dados, o CMM solicita o material de criptografia ao token de autenticação. O token de autenticação retorna uma chave de texto simples e uma cópia da chave que é criptografada por cada uma das chaves de empacotamento no token de autenticação. O SDK de criptografia da AWS usa a chave de texto simples para criptografar os dados e armazena as chaves de dados criptografadas com os dados na mensagem criptografada que retorna.


                Encriptar com um CMM e keyring.

Quando você descriptografa os dados, o CMM transmite as chaves de criptografia da mensagem criptografada e solicita que o token de autenticação descriptografe 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 da AWS usa a chave de dados de 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á.


                Descodificação com um CMM e keyring.

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. 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. É possível descriptografar os dados usando um token de autenticação configurado com qualquer uma das chaves de empacotamento do multitoken de autenticação.

Compatibilidade dos tokens de autenticação

Embora as implementações de Java, Python, C e JavaScript do SDK de criptografia da AWS tenham algumas diferenças arquitetônicas, eles são projetados para serem totalmente compatíveis, sujeitos às restrições da linguagem. Você pode criptografar seus dados usando uma implementação de linguagem de programação e descriptografá-los em qualquer outra implementação de linguagem. No entanto, é necessário usar as mesmas chaves mestras ou correspondentes para criptografar e descriptografar suas chaves de dados. Para obter informações sobre as restrições de linguagem, consulte o tópico sobre cada implementação de linguagem, como Compatibilidade do AWS Encryption SDK para JavaScript no tópico AWS Encryption SDK para JavaScript.

A tabela a seguir mostra quais chaves mestras e provedores de chaves mestras são compatíveis com os tokens de autenticação fornecidos no AWS Encryption SDK para C e no AWS Encryption SDK para JavaScript. Qualquer pequena incompatibilidade devido às restrições de linguagem é explicada no tópico sobre a implementação de linguagem.

Tokens de autenticação e provedores de chaves mestras compatíveis
Keyring: C e JavaScript Provedor de chaves mestras: Java e Python
Token de autenticação do AWS KMS

KmsMasterKey (Java)

KmsMasterKeyProvider (Java)

KmsMasterKey (Python)

KmsMasterKeyProvider (Python)

Token de autenticação bruto do AES

Quando são usados com chaves de criptografia simétrica:

JceMasterKey (Java)

RawMasterKey (Python)

Token de autenticação bruto do RSA

Quando são usados com chaves de criptografia assimétrica:

JceMasterKey (Java)

RawMasterKey (Python)

Ao descriptografar, as implementações de Java e Python se comportam como o token de autenticação de descoberta do AWS KMS, ou seja, elas não limitam as CMKs que podem ser usadas para descriptografar as chaves de dados criptografadas. Além disso, os SDKs de Java e Python não fornecem um equivalente do token de autenticação de descoberta regional do AWS KMS, embora você possa criar seus próprios tokens de autenticação personalizados.

Tokens de autenticação do AWS KMS

Um Token de autenticação do AWS KMS usa as chaves mestras do cliente (CMKs) simétricas do AWS Key Management Service (AWS KMS) para gerar, criptografar e descriptografar chaves de dados. O AWS KMS protege suas chaves mestras e executa operações de criptografia dentro do limite 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.

nota

Todas as menções de tokens de autenticação do KMS no SDK de criptografia da AWS referem-se a Tokens de autenticação do AWS KMS.

Um Token de autenticação do AWS KMS pode ter uma chave geradora, que é a CMK que gera a chave de dados de texto simples que protege seus dados e os criptografa. Ele também pode ter CMKs adicionais que criptografam a mesma chave de dados de texto simples. Ao criptografar, o Token de autenticação do AWS KMS que você usa deve ter uma chave geradora. As chaves geradoras não são necessárias para descriptografar. Ao descriptografar, qualquer chave no Token de autenticação do AWS KMS pode ser usada para descriptografar uma chave de dados criptografada.

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 obrigatórias para os Tokens de autenticação do AWS KMS

O SDK de criptografia da AWS não requer uma conta da AWS e não depende de nenhum serviço da AWS. No entanto, para usar uma chave mestra de cliente (CMK) do AWS Key Management Service (AWS KMS) em um Token de autenticação do AWS KMS, você precisa de uma conta da AWS e das seguintes permissões mínimas nas CMKs em seu token de autenticação.

  • Para criptografar com um Token de autenticação do AWS KMS, você precisa da permissão KMS:GenerateDataKey na chave geradora. 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 multitoken de autenticação composto por Tokens de autenticação do AWS KMS, você precisa da permissão kms:GenerateDataKey na chave geradora no token de autenticação 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 chaves mestras do cliente do AWS KMS, consulte Autenticação e controle de acesso do AWS KMS no AWS Key Management Service Developer Guide.

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

Um Token de autenticação do AWS KMS pode incluir uma ou mais chaves mestras do cliente (CMKs) do AWS KMS. Para especificar uma CMK 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 CMK 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 CMK do AWS KMS, consulte Identificadores de chave no AWS Key Management Service Developer Guide.

  • Em um token de autenticação de criptografia, você pode usar um ARN de chave ou um ARN de alias para identificar CMKs. Algumas implementações de linguagem permitem outros formatos.

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

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

Criptografar com um Token de autenticação do AWS KMS

Você pode configurar cada Token de autenticação do AWS KMS com uma única CMK ou várias CMKs nas mesmas ou em outras contas e regiões da AWS. Você também pode configurar um token de autenticação de descoberta do AWS KMS sem CMKs. Como com todos os tokens de autenticação, é possível usar um ou mais Tokens de autenticação do AWS KMS e um multitoken de autenticação.

Quando você cria um Token de autenticação do AWS KMS para criptografar dados, você deve especificar uma chave geradora, que é uma CMK que gera uma chave de dados de texto simples e criptografa-a. Depois, se você optar, poderá especificar outras CMKs que criptografam a mesma chave de dados de texto simples. A mensagem criptografada retornada pelo SDK de criptografia da AWS incluirá o texto cifrado e todas as chaves de dados criptografadas. O chamador deve ter a permissão kms:GenerateDataKey para a CMK geradora e a permissão kms:Encrypt para todas as CMKs adicionais.

Por exemplo, o seguinte Token de autenticação do AWS KMS especifica uma chave geradora e uma chave adicional. Quando você usa esse token de autenticação para criptografar dados, ele retorna uma chave de dados de texto simples gerada pela chave geradora e duas chaves de dados criptografadas, uma criptografada sob a chave geradora e outra criptografada sob a chave adicional. Para descriptografar os dados protegidos por este token de autenticação, o token de autenticação que você usa deve incluir pelo menos uma das CMKs que criptografaram a chave de dados, ou não incluir CMKs. (Um Token de autenticação do AWS KMS sem CMKs é conhecido como um token de autenticação de descoberta do AWS KMS.)

nota

Se você planejar usar o mesmo token de autenticação para criptografar e descriptografar dados, use um ARN de chave para identificar cada CMK. Os ARNs de chave são necessários ao descriptografar.

C

Para identificar uma CMK do AWS KMS em um token de autenticação de criptografia, 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 mais detalhes, consulte Identificar CMKs 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});
Navegador JavaScript

Ao especificar uma CMK do AWS KMS para um token de autenticação de criptografia no SDK de criptografia da AWS para JavaScript, é possível usar qualquer identificador da CMK: um ID de chave, ARN de chave, nome de alias ou ARN de alias. Para ajudar a identificar CMKs em um Token de autenticação do AWS KMS, consulte Identificar CMKs em um token de autenticação do AWS KMS.

Para obter um exemplo completo, consulte kms_simple.ts.

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 CMK do AWS KMS para um token de autenticação de criptografia no SDK de criptografia da AWS para JavaScript, é possível usar qualquer identificador da CMK: um ID de chave, ARN de chave, nome de alias ou ARN de alias. Para ajudar a identificar CMKs em um Token de autenticação do AWS KMS, consulte Identificar CMKs em um token de autenticação do AWS KMS.

Para obter um exemplo completo, consulte kms_simple.ts.

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] })

Descriptografar com um Token de autenticação do AWS KMS

Você também especifica um Token de autenticação do AWS KMS ao descriptografar a mensagem criptografada retornada pelo SDK de criptografia da AWS. Você pode usar um token de autenticação de descriptografia para determinar quais chaves de dados criptografadas podem ser descriptografadas. Se o token de autenticação de descriptografia incluir CMKs, o SDK de criptografia da AWS só descriptografará chaves de dados criptografadas que foram criptografadas pelas CMKs no token de autenticação. (Você também pode usar um token de autenticação de descoberta do AWS KMS, que não especifica CMKs.)

Ao descriptografar, o SDK de criptografia da AWS pesquisa o Token de autenticação do AWS KMS para encontrar uma CMK que possa descriptografar uma das chaves de dados criptografadas. Especificamente, o SDK de criptografia da AWS usa o seguinte padrão para cada chave de dados criptografada em uma mensagem criptografada.

  • O SDK de criptografia da AWS analisa os metadados da chave de dados criptografada. Ele obtém o ARN da chave da CMK que criptografou a chave de dados.

  • O SDK de criptografia da AWS pesquisa o token de autenticação de descriptografia para encontrar uma CMK com um ARN de chave correspondente.

  • Se ele encontrar uma CMK com um ARN correspondente no token de autenticação, o SDK de criptografia da AWS solicitará ao AWS KMS para descriptografar a chave de dados criptografada.

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

O SDK de criptografia da AWS nunca tenta descriptografar uma chave de dados criptografada, a menos que o ARN da CMK 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 CMKs que criptografaram qualquer uma das chaves de dados, o SDK de criptografia da AWS não fará a chamada de descriptografia nem chamará o AWS KMS.

Uma chamada de descriptografia com um Token de autenticação do AWS KMS terá êxito quando, pelo menos, uma CMK 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 CMK. Esse comportamento permite criptografar dados em várias CMKs em diferentes regiões e contas da AWS, 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 CMK em um token de autenticação de descriptografia, você deve usar o ARN dessa chave. Caso contrário, a CMK não é reconhecida. Para obter ajuda para encontrar o ARN da chave, consulte Encontrar o ID e o ARN da chave no AWS Key Management Service Developer Guide.

nota

Se você reutilizar um token de autenticação de criptografia para descriptografar, verifique se as CMKs 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. 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);
Navegador JavaScript
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] })

Também é possível usar um Token de autenticação do AWS KMS que especifica uma chave geradora para descriptografia, como este a seguir. Na descriptografia, o SDK de criptografia da AWS ignora a distinção entre chaves geradoras e chaves adicionais. Ele pode usar qualquer uma das CMKs 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 CMK para descriptografar dados.

C
struct aws_cryptosdk_keyring *kms_decrypt_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(generator_key, {additional_key, other_cmk});
Navegador JavaScript
const clientProvider = getClient(KMS, { credentials }) const keyring = new KmsKeyringBrowser({ clientProvider, generatorKeyId, keyIds: [additionalKey, otherCmk] })
JavaScript Node.js
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds: [additionalKey, otherCmk] })

Ao contrário de um token de autenticação de criptografia que usa todas as CMKs especificadas, você pode descriptografar uma mensagem criptografada usando um token de autenticação de descriptografia que inclui CMKs não relacionadas à mensagem criptografada e CMKs 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 SDK de criptografia da AWS simplesmente pula para a próxima chave de dados criptografada.

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

Em geral, ao descriptografar, você fornece um Token de autenticação do AWS KMS que limita as CMKs que o SDK de criptografia da AWS pode usar à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 CMKs. Ele permite que o SDK de criptografia da AWS solicite que o AWS KMS descriptografe todas as chaves de dados criptografadas de uma mensagem criptografada usando a CMK que a criptografou, independentemente de quem seja o proprietário ou de quem tenha acesso a essa CMK. A chamada será bem-sucedida somente se o chamador tiver a permissão kms:Decrypt para a CMK.

O código a seguir instancia um token de autenticação de descoberta do AWS KMS.

C

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

struct kms_discovery_keyring = Aws::Cryptosdk::KmsKeyring::Builder().BuildDiscovery();
Navegador JavaScript

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

const clientProvider = getClient(KMS, { credentials }) const keyring = new KmsKeyringBrowser({discovery: true})
JavaScript Node.js

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

const keyring = new KmsKeyringNode({discovery: true})

Ao criptografar, um token de autenticação de descoberta do AWS KMS não tem efeito. Ele não retorna chaves de dados criptografadas. No entanto, talvez você queira incluir um token de autenticação de descoberta do AWS KMS em um multitoken de autenticação que será usado para criptografia e descriptografia.

Ao descriptografar com um token de autenticação de descoberta do AWS KMS, o SDK de criptografia da AWS chamará o AWS KMS para descriptografar cada uma das chaves de dados criptografadas da mensagem criptografada na ordem em que elas forem exibidas até que uma tenha êxito. Para obter êxito, o chamador deve ter a permissão kms:Decrypt para pelo menos uma das CMKs que criptografaram uma das chaves de dados criptografadas.

O SDK de criptografia da AWS 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: o token de autenticação de descoberta do AWS KMS pode usar qualquer CMK que foi usada para criptografar uma chave de dados na mensagem criptografada se o chamador tiver permissão para usar essa CMK para descriptografar. Essa pode não ser a CMK que o chamador pretende usar. Por exemplo, uma das chaves de dados criptografadas pode ter sido criptografada com uma CMK menos segura que qualquer pessoa possa usar.

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

Quando você usa um token de autenticação de descoberta do AWS KMS em um multitoken de autenticação, ele não tem efeito na criptografia. Ao descriptografar permitindo o uso de qualquer CMK, um token de autenticação de descoberta do AWS KMS substitui quaisquer limites da CMK que outros Tokens de autenticação do AWS KMS no multitoken de autenticação possam impor. Por exemplo, se você combinar um Token de autenticação do AWS KMS que usa uma CMK específica com um token de autenticação de descoberta do AWS KMS, o multitoken de autenticação resultante se comportará exatamente como o token de autenticação de descoberta do KMS. Ele permitirá que o SDK de criptografia da AWS solicite que o AWS KMS descriptografe qualquer chave de dados criptografada, mesmo que ela tenha sido criptografada por outra CMK.

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

Em vez de usar um Token de autenticação do AWS KMS que especifica CMKs específicas ou um token de autenticação de descoberta do AWS KMS que pode usar qualquer CMK, convém usar um token de autenticação de descoberta regional do AWS KMS que inclua ou exclua o SDK de criptografia da AWS para CMKs em uma determinada região da AWS.

Por exemplo, o código a seguir cria um token de autenticação de descoberta regional do AWS KMS que usa somente CMKs 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.

struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder() .WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery());
Navegador JavaScript
const clientProvider = getClient(KMS, { credentials }) const discovery = true const clientProvider = limitRegions(['us-west-2'], getKmsClient) const keyring = new KmsKeyringBrowser({ clientProvider, discovery })
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 })

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 CMKs em regiões específicas. O exemplo a seguir cria um token de autenticação de descoberta regional do AWS KMS que pode usar CMKs em todas as regiões da AWS, exceto na Leste dos EUA (Norte da Virgínia) (us-east-1).

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

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

Ao criptografar, um token de autenticação de descoberta regional do AWS KMS não tem efeito. Como ele não especifica nenhuma CMKs, ele não pode gerar nem criptografar chaves de dados. No entanto, você pode incluir um token de autenticação de descoberta regional do AWS KMS em um multitoken de autenticação que será usado para criptografia e descriptografia.

Ao descriptografar com um token de autenticação de descoberta regional do AWS KMS, o SDK de criptografia da AWS pode solicitar que o AWS KMS descriptografe todas as chaves de dados criptografadas com uma CMK na região especificada da AWS. Para ter êxito, o chamador deverá ter a permissão kms:Decrypt em, pelo menos, uma das CMKs na região especificada da AWS que criptografaram uma das chaves de dados da mensagem criptografada.

Em um multitoken de autenticação, como ele permite o uso de qualquer CMK na região da AWS, um token de autenticação de descoberta regional do AWS KMS pode substituir os limites de CMK que outros Tokens de autenticação do AWS KMS podem impor no multitoken de autenticação. Por exemplo, se você combinar um Token de autenticação do AWS KMS que permita o uso de uma CMK específica na Região Europa (Londres) e um token de autenticação de descoberta regional do KMS para a Região Europa (Londres), o multitoken de autenticação resultante se comportará da mesma forma que o token de autenticação de descoberta regional do AWS KMS isoladamente. Ele permite ao SDK de criptografia da AWS solicitar que o AWS KMS descriptografe todas as chaves de dados criptografadas por qualquer CMK na Região Europa (Londres).

Tokens de autenticação AES Raw

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. Você pode especificar somente uma chave de empacotamento em cada token de autenticação bruto do AES, mas pode incluir vários tokens de autenticação brutos do AES em cada multitoken de autenticação.

O token de autenticação bruto do AES é equivalente a e interopera com a JceMasterKey no AWS Encryption SDK para Java e com a RawMasterKey no AWS Encryption SDK para Python quando são usadas com chaves de criptografia simétrica. Você pode criptografar dados com uma implementação e descriptografá-los com qualquer outra implementação usando a mesma chave de empacotamento.

Use um token de autenticação bruto do AES quando precisar fornecer a chave de empacotamento e criptografar as chaves de dados localmente ou quando escrever um aplicativo que seja compatível com o AWS Encryption SDK para Java ou o AWS Encryption SDK para Python. Sempre que possível, recomendamos usar um módulo de segurança de hardware (HSM) ou um serviço, como o AWS KMS, que não exponha chaves de empacotamento e criptografe chaves de dados em um limite seguro.

Para identificar a chave de empacotamento, o token de autenticação bruto do AES usa um namespace e um nome fornecidos por você. Estes são equivalentes aos campos Provider ID e Key ID no AWS Encryption SDK para Java e no AWS Encryption SDK para Python. Esses valores não são secretos. Eles aparecem em texto simples no cabeçalho da mensagem criptografada que o SDK de criptografia da AWS retorna. No entanto, são críticos. Você precisa usar para uma chave em seu token de autenticação de descriptografia os mesmos namespace e nome que usou para essa chave no token de autenticação de criptografia. Se o namespace e o nome não forem uma correspondência exata, que diferencie letras maiúsculas de minúsculas, o SDK de criptografia da AWS não reconhecerá que as chaves de empacotamento são equivalentes, mesmo se os bytes forem idênticos, e não conseguirá descriptografar as chaves de dados criptografadas.

Para obter um exemplo de como usar um token de autenticação bruto do AES, consulte:

Tokens de autenticação brutos do RSA

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 especificadas. 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. Você pode 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. Mas você pode 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. Além disso, é possível incluir qualquer token de autenticação bruto do RSA em um multitoken de autenticação. O token de autenticação bruto do RSA é equivalente a e interopera com a JceMasterKey no AWS Encryption SDK para Java e a RawMasterKey no AWS Encryption SDK para Python quando são usadas com chaves de criptografia assimétricas. Você pode criptografar dados com uma implementação e descriptografá-los com qualquer outra implementação usando a mesma chave de empacotamento.

Use um token de autenticação bruto do RSA quando quiser usar um par de chaves assimétricas e fornecer a chave de empacotamento e chaves de desempacotamento ou precisar ser compatível com o SDK de criptografia da AWS em outra linguagem de programação.

Para identificar o par de chaves, o token de autenticação bruto do RSA usa um namespace e um nome fornecidos por você. Esses valores não são secretos. Eles aparecem em texto simples no cabeçalho da mensagem criptografada que o SDK de criptografia da AWS retorna. No entanto, são críticos. Se você usar o mesmo par de chaves no token de autenticação de criptografia e um token de autenticação de descriptografia, use os mesmos namespace e nome para o par de chaves nos dois tokens. Se o namespace e o nome não forem uma correspondência exata, que diferencie letras maiúsculas de minúsculas, o SDK de criptografia da AWS não reconhecerá que as chaves assimétricas são um par e não conseguirá descriptografar as chaves de dados criptografadas.

Ao criar um token de autenticação bruto do RSA no AWS Encryption SDK para C, forneça o conteúdo do arquivo PEM que inclui cada chave como uma string C com terminação nula, não um caminho nem um nome de arquivo. Ao criar um token de autenticação bruto do RSA no JavaScript, lembre-se da potencial incompatibilidade com outras implementações de linguagem.

Para obter um exemplo de como usar um token de autenticação bruto do RSA, consulte:

Multitokens de autenticação

Você pode 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, você pode 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 você criar um multitoken de autenticação sem um token gerador, poderá usá-lo para descriptografar dados, mas não para criptografá-los. Se o token de autenticação gerador for um token de autenticação do KMS, a chave geradora no Token de autenticação do AWS KMS gerará e criptografará a chave de texto simples. Depois, todas as CMKs adicionais no Token de autenticação do AWS KMS e todas as chaves de empacotamento em todos os tokens de autenticação filho no multitoken de autenticação criptografarão a mesma chave de texto simples.

Na descriptografia, o SDK de criptografia da AWS usará os mesmos tokens de autenticação para 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 ver um exemplo prático de um multitoken de autenticação, consulte:

Para criar um multitoken de autenticação, primeiro instancie os tokens de autenticação filho. Neste exemplo, usamos um Token de autenticação do AWS KMS e um token de autenticação bruto do AES, mas é possível combinar qualquer token de autenticação compatível em um multitoken de autenticação.

C
// Define an Token de autenticação do AWS KMS. For details, see string.cpp. struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(example_CMK); // Define a Raw AES keyring. For details, see raw_aes_keyring.c. struct aws_cryptosdk_keyring *aes_keyring = aws_cryptosdk_raw_aes_keyring_new( alloc, wrapping_key_namespace, wrapping_key_name, wrapping_key, AWS_CRYPTOSDK_AES256);
Navegador JavaScript
const clientProvider = getClient(KMS, { credentials }) // Define an Token de autenticação do AWS KMS. For details, see kms_simple.ts. const kmsKeyring = new KmsKeyringBrowser({ generatorKeyId: exampleCmk }) // Define a Raw AES keyring. For details, see aes_simple.ts. const aesKeyring = new RawAesKeyringWebCrypto({ keyName, keyNamespace, wrappingSuite, masterKey })
JavaScript Node.js
// Define an Token de autenticação do AWS KMS. For details, see kms_simple.ts. const kmsKeyring = new KmsKeyringNode({ generatorKeyId: exampleCmk }) // Define a Raw AES keyring. For details, see raw_aes_keyring_node.ts. const aesKeyring = new RawAesKeyringNode({ keyName, keyNamespace, wrappingSuite, unencryptedMasterKey })

Em seguida, crie o multitoken de autenticação e especifique seu token gerador, se houver. Neste exemplo, criamos um multitoken de autenticação em que Token de autenticação do AWS KMS é o token de autenticação gerador e o token de autenticação do AES é o token de autenticação filho.

C

No construtor de multitoken de autenticação no C, você especifica apenas seu token de autenticação gerador.

struct aws_cryptosdk_keyring *multi_keyring = aws_cryptosdk_multi_keyring_new(alloc, kms_keyring);

Para adicionar um token de autenticação filho ao multitoken de autenticação, use o método aws_cryptosdk_multi_keyring_add_child. Você precisa chamar o método uma vez para cada token de autenticação filho que adicionar.

// Add the Raw AES keyring (C only) aws_cryptosdk_multi_keyring_add_child(multi_keyring, aes_keyring);
Navegador JavaScript

Os multitokens de autenticação do JavaScript são imutáveis. O construtor de multitoken de autenticação do JavaScript permite que você especifique o token de autenticação gerador e vários tokens de autenticação filho.

const clientProvider = getClient(KMS, { credentials }) const multiKeyring = new MultiKeyringWebCrypto(generator: kmsKeyring, children: [aesKeyring]);
JavaScript Node.js

Os multitokens de autenticação do JavaScript são imutáveis. O construtor de multitoken de autenticação do JavaScript permite que você especifique o token de autenticação gerador e vários tokens de autenticação filho.

const multiKeyring = new MultiKeyringNode(generator: kmsKeyring, children: [aesKeyring]);

Agora, você pode usar o multitoken de autenticação para criptografar e descriptografar dados.

Para obter um exemplo completo de como criar e usar um multitoken de autenticação no C, consulte multi_keyring.cpp.