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-node e example-browser no repositório aws-encryption-sdk-javascript no GitHub. Esses módulos de exemplo não são instalados quando você instala os módulos client-browser ou client-node.

Consulte os exemplos de código completos: nó: kms_simple.ts, navegador: kms_simple.ts

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 Identificar AWS KMS keys em um token de autenticação do AWS KMS

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.

JavaScript Browser

Comece fornecendo suas credenciais para o navegador. Os exemplos do AWS Encryption SDK para JavaScript usam o webpack.DefinePlugin, que substitui as constantes de credenciais por suas credenciais reais. Mas você pode usar qualquer método para fornecer suas credenciais. Depois, use as credenciais para criar um cliente do AWS KMS.

declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }

const clientProvider = getClient(KMS, {
  credentials: {
    accessKeyId,
    secretAccessKey,
    sessionToken
  }
})

Especifique as AWS KMS keys para a chave geradora e a chave adicional. Crie um token de autenticação do AWS KMS usando o cliente do AWS KMS e as AWS KMS keys.

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

const keyring = new KmsKeyringBrowser({ clientProvider, generatorKeyId, keyIds })

JavaScript Node.js

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

const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })

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.

JavaScript Browser

const context = {
  stage: 'demo',
  purpose: 'simple demonstration app',
  origin: 'us-west-2'
}

JavaScript Node.js

const context = {
  stage: 'demo',
  purpose: 'simple demonstration app',
  origin: 'us-west-2'
}

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.

JavaScript Browser

const plaintext = new Uint8Array([1, 2, 3, 4, 5])

const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })

JavaScript Node.js

const plaintext = 'asdf'

const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })

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ção encrypt 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 Identificar AWS KMS keys em um token de autenticação do AWS KMS

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.

JavaScript Browser

Comece fornecendo suas credenciais para o navegador. Os exemplos do AWS Encryption SDK para JavaScript usam o webpack.DefinePlugin, que substitui as constantes de credenciais por suas credenciais reais. Mas você pode usar qualquer método para fornecer suas credenciais. Depois, use as credenciais para criar um cliente do AWS KMS.

declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }

const clientProvider = getClient(KMS, {
  credentials: {
    accessKeyId,
    secretAccessKey,
    sessionToken
  }
})

Em seguida, crie um token de autenticação do AWS KMS usando o cliente do AWS KMS. Este exemplo usa apenas uma das AWS KMS keys do token de autenticação de criptografia.

const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']

const keyring = new KmsKeyringBrowser({ clientProvider, keyIds })

JavaScript Node.js

const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']

const keyring = new KmsKeyringNode({ keyIds })

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ção encrypt 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 campo messageHeader contém metadados sobre o processo de descriptografia, incluindo o contexto de criptografia usado para descriptografar os dados.

JavaScript Browser

const { plaintext, messageHeader } = await decrypt(keyring, result)

JavaScript Node.js

const { plaintext, messageHeader } = await decrypt(keyring, result)

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ção decrypt 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).

JavaScript Browser

const { encryptionContext } = messageHeader

Object
  .entries(context)
  .forEach(([key, value]) => {
    if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})

JavaScript Node.js

const { encryptionContext } = messageHeader

Object
  .entries(context)
  .forEach(([key, value]) => {
    if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})

Se a verificação de contexto de criptografia for bem-sucedida, você poderá retornar os dados de texto simples.