SDK de cifrado de AWS para JavaScript ejemplos - AWS Encryption SDK
Cifrar datos con un anillo de claves AWS KMSDescifrar datos con un anillo de claves AWS KMS

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

SDK de cifrado de AWS para JavaScript ejemplos

En los siguientes ejemplos se muestra cómo utilizar el SDK de cifrado de AWS para JavaScript para cifrar y descifrar datos.

Puedes encontrar más ejemplos de su uso SDK de cifrado de AWS para JavaScript en los módulos example-node y example-browser del repositorio de. aws-encryption-sdk-javascript GitHub Estos módulos de ejemplo no se instalan al instalar los módulos client-browser o client-node.

Consulte los ejemplos de código completos: Nodo: kms_simple.ts, Navegador: kms_simple.ts

Cifrar datos con un anillo de claves AWS KMS

En el siguiente ejemplo, se muestra cómo utilizar el SDK de cifrado de AWS para JavaScript para cifrar y descifrar una cadena corta o una matriz de bytes.

Este ejemplo incluye un AWS KMS anillo de claves, un tipo de anillo de claves que utiliza un AWS KMS key para generar y cifrar claves de datos. Si necesitas ayuda para crear una AWS KMS key, consulta la sección Creación de claves en la AWS Key Management Service Guía para desarrolladores. Para obtener ayuda para identificarlas AWS KMS keys en un AWS KMS llavero, consulte Identificarse AWS KMS keys en un AWS KMS llavero

Paso 1: Establece la política de compromiso.

A partir de la versión 1.7. x del SDK de cifrado de AWS para JavaScript, puede establecer la política de compromiso al llamar a la nueva buildClient función que crea una instancia de un AWS Encryption SDK cliente. La función buildClient toma un valor enumerado que representa su política de compromiso. Devuelve funciones actualizadas encrypt y decrypt que hacen cumplir su política de compromiso al cifrar y descifrar.

En los siguientes ejemplos, se utiliza la buildClient función para especificar la política de compromiso predeterminada,. REQUIRE_ENCRYPT_REQUIRE_DECRYPT También puede utilizarla buildClient para limitar el número de claves de datos cifradas en un mensaje cifrado. Para obtener más información, consulte Limitar las claves de datos cifrados.

JavaScript Browser
import {
  KmsKeyringBrowser,
  KMS,
  getClient,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-browser'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
JavaScript Node.js
import {
  KmsKeyringNode,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-node'
                                
const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
Paso 2: crear el conjunto de claves.

Cree un conjunto de AWS KMS claves para el cifrado.

Al cifrar con un AWS KMS anillo de claves, debe especificar una clave generadora, es decir, una AWS KMS key que se utilice para generar la clave de datos en texto plano y cifrarla. También puede especificar cero o más claves adicionales que cifren la misma clave de datos en texto no cifrado. El anillo de claves devuelve la clave de datos en texto plano y una copia cifrada de esa clave de datos para cada AWS KMS key uno de los componentes del conjunto de claves, incluida la clave generadora. Para descifrar los datos, debe descifrar cualquiera de las claves de datos cifradas.

Para especificar el AWS KMS keys anillo de claves de cifrado en SDK de cifrado de AWS para JavaScript, puede utilizar cualquier identificador de clave compatible. AWS KMS En este ejemplo se utiliza una clave generadora, que se identifica por su alias ARN, y una clave adicional, que se identifica mediante una clave ARN.

nota

Si piensa reutilizar el conjunto de AWS KMS claves para descifrar, debe utilizar la clave para ARNs identificarlo AWS KMS keys en el conjunto de claves.

Antes de ejecutar este código, sustituya los identificadores de ejemplo por AWS KMS key identificadores válidos. Debe tener los permisos necesarios para usar el AWS KMS keys en el conjunto de claves.

JavaScript Browser

Comience por proporcionar sus credenciales al navegador. Los SDK de cifrado de AWS para JavaScript ejemplos utilizan el paquete web. DefinePlugin, que reemplaza las constantes de las credenciales por las credenciales reales. También puede usar cualquier otro método para proporcionar sus credenciales. A continuación, utilice las credenciales para crear un AWS KMS cliente.

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

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

A continuación, especifique AWS KMS keys la clave del generador y la clave adicional. A continuación, cree un AWS KMS conjunto de claves con el AWS KMS cliente y el 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 })
Paso 3: Defina el contexto de cifrado.

Un contexto de cifrado son datos autenticados adicionales que son arbitrarios y no son secretos. Al proporcionar un contexto de cifrado al cifrar, este vincula AWS Encryption SDK criptográficamente el contexto de cifrado al texto cifrado, de modo que se requiere el mismo contexto de cifrado para descifrar los datos. El uso de un contexto de cifrado es opcional, pero es una práctica recomendada que le aconsejamos.

Cree un objeto simple que incluya los pares de contexto de cifrado. La clave y el valor de cada par deben ser una cadena.

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'
}
Paso 4: Cifra los datos.

Para cifrar los datos en texto no cifrado, llame a la función encrypt. Introduzca el conjunto de AWS KMS claves, los datos en texto plano y el contexto de cifrado.

La función encrypt devuelve un mensaje cifrado (result) que contiene los datos cifrados, las claves de datos cifradas y los metadatos importantes, como el contexto de cifrado y la firma.

Puede descifrar este mensaje cifrado utilizando cualquier lenguaje AWS Encryption SDK de programación compatible.

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

Descifrar datos con un anillo de claves AWS KMS

Puede usarlo SDK de cifrado de AWS para JavaScript para descifrar el mensaje cifrado y recuperar los datos originales.

En este ejemplo, desciframos los datos que hemos cifrado en el ejemplo Cifrar datos con un anillo de claves AWS KMS.

Paso 1: Establece la política de compromiso.

A partir de la versión 1.7. x del SDK de cifrado de AWS para JavaScript, puede establecer la política de compromiso al llamar a la nueva buildClient función que crea una instancia de un AWS Encryption SDK cliente. La función buildClient toma un valor enumerado que representa su política de compromiso. Devuelve funciones actualizadas encrypt y decrypt que hacen cumplir su política de compromiso al cifrar y descifrar.

En los siguientes ejemplos, se utiliza la buildClient función para especificar la política de compromiso predeterminada,. REQUIRE_ENCRYPT_REQUIRE_DECRYPT También puede utilizarla buildClient para limitar el número de claves de datos cifradas en un mensaje cifrado. Para obtener más información, consulte Limitar las claves de datos cifrados.

JavaScript Browser
import {
  KmsKeyringBrowser,
  KMS,
  getClient,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-browser'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
JavaScript Node.js
import {
  KmsKeyringNode,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-node'
                                
const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
Paso 2: crear el conjunto de claves.

Para descifrar los datos, pase el mensaje cifrado (result) que la función encrypt ha devuelto. El mensaje cifrado contiene los datos cifrados, las claves de datos cifradas y metadatos importantes, como el contexto de cifrado y la firma.

También debe especificar un conjunto de claves de AWS KMS al descifrar. Puede utilizar el mismo conjunto de claves que se utilizó para cifrar los datos u otro conjunto de claves. Para tener éxito, al menos una AWS KMS key de las claves de descifrado debe poder descifrar una de las claves de datos cifradas del mensaje cifrado. Dado que no se generan claves de datos, no es necesario especificar una clave generadora en un conjunto de claves de descifrado. Si lo hace, la clave generadora y las claves adicionales se tratarán de la misma manera.

Para especificar un conjunto AWS KMS key de claves de descifrado en el SDK de cifrado de AWS para JavaScript, debe utilizar la clave. ARN De lo contrario, no AWS KMS key se reconoce. Si necesita ayuda para identificarlo AWS KMS keys en un AWS KMS llavero, consulte Identificarse AWS KMS keys en un AWS KMS llavero

nota

Si utiliza el mismo anillo de claves para cifrar y descifrar, utilice la clave ARNs para identificar el AWS KMS keys conjunto de claves.

En este ejemplo, creamos un anillo de claves que incluye solo uno de los del anillo de claves de AWS KMS keys cifrado. Antes de ejecutar este código, sustituya la clave ARN del ejemplo por una válida. Debe tener permiso de kms:Decrypt sobre la AWS KMS key.

JavaScript Browser

Comience por proporcionar sus credenciales al navegador. Los SDK de cifrado de AWS para JavaScript ejemplos utilizan el paquete web. DefinePlugin, que reemplaza las constantes de las credenciales por las credenciales reales. También puede usar cualquier otro método para proporcionar sus credenciales. A continuación, utilice las credenciales para crear un AWS KMS cliente.

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

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

A continuación, cree un conjunto de AWS KMS claves con el AWS KMS cliente. En este ejemplo, se utiliza solo una de las del AWS KMS keys anillo de claves de cifrado.

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 })
Paso 3: Descifrar los datos.

A continuación, llame a la función decrypt. Pase el conjunto de claves de descifrado que acaba de crear (keyring) y el mensaje cifrado que la función encrypt ha devuelto (result). AWS Encryption SDK Utiliza el anillo de claves para descifrar una de las claves de datos cifradas. Luego, usa la clave de datos en texto no cifrado para descifrar los datos.

Si la llamada se realiza correctamente, el campo plaintext contiene los datos en texto no cifrado (descifrado). El campo messageHeader contiene metadatos sobre el proceso de descifrado, como el contexto de cifrado que se ha utilizado para descifrar los datos.

JavaScript Browser
const { plaintext, messageHeader } = await decrypt(keyring, result)
JavaScript Node.js
const { plaintext, messageHeader } = await decrypt(keyring, result)
Paso 4: Verificar el contexto de cifrado.

El contexto de cifrado utilizado para descifrar los datos se incluye en el encabezado del mensaje (messageHeader) que la función decrypt devuelve. Antes de que la aplicación devuelva los datos en texto no cifrado, compruebe que el contexto de cifrado que proporcionó durante el cifrado esté incluido en el contexto de cifrado que se utilizó al descifrar. Una discrepancia podría indicar que se han manipulado los datos o que no ha descifrado el texto cifrado correcto.

Al verificar el contexto de cifrado, no requiere una coincidencia exacta. Cuando se utiliza un algoritmo de cifrado con firma, el administrador de materiales criptográficos (CMM) añade la clave de firma pública al contexto de cifrado antes de cifrar el mensaje. Pero todos los pares de contexto de cifrado que ha enviado tienen que estar incluidos en el contexto de cifrado devuelto.

Primero, obtenga el contexto de cifrado del encabezado del mensaje. Luego compruebe que cada par clave-valor del contexto de cifrado original (context) coincida con un par clave-valor en el contexto de cifrado devuelto (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')
})

Si la comprobación del contexto de cifrado se realiza correctamente, puede devolver los datos en texto no cifrado.