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á.
Exemplos do AWS Encryption SDK para JavaScript
Os exemplos a seguir mostram como usar o AWS Encryption SDK para JavaScript para criptografar e descriptografar dados.
Você pode encontrar mais exemplos de uso do AWS Encryption SDK para JavaScript nos módulos example-nodeclient-browser
ou client-node
.
Consulte os exemplos de código completos: nó: kms_simple.ts
Tópicos
Criptografar dados com um token de autenticação do AWS KMS
O exemplo a seguir mostra como usar o AWS Encryption SDK para JavaScript para criptografar e descriptografar uma string curta ou uma matriz de bytes.
Este exemplo apresenta o token de autenticação do AWS KMS, um tipo de token de autenticação que usa uma AWS KMS key para gerar e criptografar chaves de dados. Para obter ajuda na criação de uma AWS KMS key, consulte Criação de chaves no Guia do desenvolvedor do AWS Key Management Service. Para obter ajuda para identificar a AWS KMS keys em um token de autenticação do AWS KMS, consulte Identificação AWS KMS keys em um AWS KMS chaveiro
- Etapa 1: Criar o token de autenticação.
-
Criar um token de autenticação do AWS KMS para criptografia.
Ao criptografar com um token de autenticação do AWS KMS, você deve especificar uma chave geradora, ou seja, uma AWS KMS key do que é usada para gerar a chave de dados de texto simples e criptografá-la. Você também pode especificar zero ou mais chaves adicionais que criptografam a mesma chave de dados de texto simples. O token de autenticação retorna a chave de dados de texto simples e uma cópia criptografada dessa chave de dados para cada AWS KMS key no token de autenticação, incluindo a chave geradora. Para descriptografar os dados, você precisa descriptografar qualquer uma das chaves de dados criptografadas.
Para especificar as AWS KMS keys para um token de autenticação de criptografia no AWS Encryption SDK para JavaScript, você pode usar qualquer identificador de chave do AWS KMS compatível. Este exemplo usa uma chave geradora, que é identificada por seu ARN de alias, e uma chave adicional, que é identificada por um ARN de chave.
nota
Se você planeja reutilizar o token de autenticação do AWS KMS para descriptografar, deverá usar ARNs de chave para identificar as AWS KMS keys no token de autenticação.
Antes de executar esse código, substitua os identificadores da AWS KMS key de exemplo por identificadores válidos. Você deve ter as permissões necessárias para usar as AWS KMS keys no token de autenticação.
- Etapa 2: Definir o contexto de criptografia.
-
Um contexto de criptografia são dados autenticados adicionais arbitrários e que não são secretos. Quando você fornece um contexto de criptografia na criptografia, o AWS Encryption SDK vincula de forma criptográfica o contexto ao texto cifrado, de forma que o mesmo contexto de criptografia seja necessário para descriptografar os dados. O uso de um contexto de criptografia é opcional, mas o recomendamos como uma melhor prática.
Crie um objeto simples que inclua os pares de contexto de criptografia. A chave e o valor em cada par devem ser uma string.
- Etapa 3: Criptografar os dados.
-
Para criptografar os dados de texto simples, chame a função
encrypt
. Passe o token de autenticação do AWS KMS, os dados de texto simples e o contexto de criptografia.A função
encrypt
retorna uma mensagem criptografada (result
) que contém os dados criptografados, as chaves de dados criptografadas e metadados importantes, incluindo o contexto de criptografia e a assinatura.Você pode descriptografar essa mensagem criptografada usando o AWS Encryption SDK em qualquer linguagem de programação compatível.
Descriptografar dados com um token de autenticação do AWS KMS
Você pode usar o AWS Encryption SDK para JavaScript para descriptografar a mensagem criptografada e recuperar os dados originais.
Neste exemplo, descriptografamos os dados que criptografamos no exemplo Criptografar dados com um token de autenticação do AWS KMS.
- Etapa 1: Criar o token de autenticação.
-
Para descriptografar os dados, passe a mensagem criptografada (
result
) que a funçãoencrypt
retornou. A mensagem criptografada inclui os dados criptografados, as chaves de dados criptografadas e metadados importantes, incluindo o contexto de criptografia e a assinatura.Você também deve especificar um token de autenticação do AWS KMS ao descriptografar. Você pode usar o mesmo token de autenticação usado para criptografar os dados ou um token de autenticação diferente. Para ter êxito, pelo menos uma AWS KMS key no token de autenticação de descriptografia deve poder descriptografar uma das chaves de dados criptografadas na mensagem criptografada. Como nenhuma chave de dados é gerada, você não precisa especificar uma chave geradora em um token de autenticação de descriptografia. Se você fizer isso, a chave geradora e as chaves adicionais serão tratadas da mesma maneira.
Para especificar uma AWS KMS key para um token de autenticação de descriptografia no AWS Encryption SDK para JavaScript, você deve usar o ARN da chave. Caso contrário, a AWS KMS key não é reconhecida. Para obter ajuda para identificar a AWS KMS keys em um token de autenticação do AWS KMS, consulte Identificação AWS KMS keys em um AWS KMS chaveiro
nota
Se você usar o mesmo token de autenticação para criptografar e descriptografar, use ARNs de chave para identificar as AWS KMS keys no token de autenticação.
Neste exemplo, criamos um token de autenticação que inclui apenas uma das AWS KMS keys no token de autenticação de criptografia. Antes de executar esse código, substitua o ARN da chave de exemplo por um válido. Você deve ter a permissão
kms:Decrypt
na AWS KMS key. - Etapa 2: Descriptografar os dados.
-
Chame a função
decrypt
. Passe o token de autenticação de descriptografia que você acabou de criar (keyring
) e a mensagem criptografada que a funçãoencrypt
retornou (result
). O AWS Encryption SDK usa o token de autenticação para descriptografar uma das chaves de dados criptografadas. Ele usa a chave de dados de texto simples para descriptografar os dados.Se a chamada for bem-sucedida, o campo
plaintext
conterá os dados de texto simples (descriptografados). O campomessageHeader
contém metadados sobre o processo de descriptografia, incluindo o contexto de criptografia usado para descriptografar os dados. - Etapa 3: Verificar o contexto de criptografia.
-
O contexto de criptografia que foi usado para descriptografar os dados é incluído no cabeçalho da mensagem (
messageHeader
) que a funçãodecrypt
retorna. Antes do aplicativo retornar os dados de texto simples, verifique se o contexto de criptografia fornecido durante a criptografia está incluído no contexto de criptografia usado ao descriptografar. Uma incompatibilidade pode indicar que os dados foram adulterados ou que você não descriptografou o texto cifrado correto.Ao verificar o contexto de criptografia, não exija uma correspondência exata. Ao usar um algoritmo de criptografia com a assinatura, o gerenciador de material de criptografia (CMM) adiciona a chave de assinatura pública ao contexto de criptografia antes de criptografar a mensagem. Mas todos os pares de contexto de criptografia que você enviou devem ser incluídos no contexto de criptografia que foi retornado.
Primeiro, obtenha o contexto de criptografia do cabeçalho da mensagem. Depois, verifique se cada par de chave-valor no contexto de criptografia original (
context
) corresponde a um par de chave-valor no contexto de criptografia retornado (encryptionContext
).Se a verificação de contexto de criptografia for bem-sucedida, você poderá retornar os dados de texto simples.