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](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) y [example-browser del repositorio](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) de. [aws-encryption-sdk-javascript](https://github.com/aws/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\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_simple.ts), Navegador: [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/kms_simple.ts) **Topics** + [Cifrar datos con un anillo de claves AWS KMS](#javascript-example-encrypt) + [Descifrar datos con un anillo de claves AWS KMS](#javascript-example-decrypt) ## 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](use-kms-keyring.md), 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](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) 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](use-kms-keyring.md#kms-keyring-id) 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](migrate-commitment-policy.md),. `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](configure.md#config-limit-keys). ``` import { KmsKeyringBrowser, KMS, getClient, buildClient, CommitmentPolicy, } from '@aws-crypto/client-browser' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) ``` ``` 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](use-kms-keyring.md#kms-keyring-id) identificador de clave compatible. AWS KMS En este ejemplo se utiliza una clave generadora, que se identifica mediante su [ARN de alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN) y una clave adicional, que se identifica mediante un [ARN de clave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN). Si piensa reutilizar el AWS KMS anillo de claves para descifrar, debe utilizar la clave para ARNs identificarlo AWS KMS keys en el anillo 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](use-kms-keyring.md#kms-keyring-permissions) en el conjunto de claves. Comience por proporcionar sus credenciales al navegador. [Los SDK de cifrado de AWS para JavaScript ejemplos utilizan el paquete web. DefinePlugin](https://webpack.js.org/plugins/define-plugin/), 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 }) ``` ``` 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](concepts.md#encryption-context) 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. ``` const context = { stage: 'demo', purpose: 'simple demonstration app', origin: 'us-west-2' } ``` ``` 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](concepts.md#message) (`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](#javascript-example-decrypt) utilizando cualquier lenguaje AWS Encryption SDK de programación compatible. ``` const plaintext = new Uint8Array([1, 2, 3, 4, 5]) const { result } = await encrypt(keyring, plaintext, { encryptionContext: context }) ``` ``` 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](#javascript-example-encrypt). 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](migrate-commitment-policy.md),. `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](configure.md#config-limit-keys). ``` import { KmsKeyringBrowser, KMS, getClient, buildClient, CommitmentPolicy, } from '@aws-crypto/client-browser' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) ``` ``` 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](concepts.md#message) (`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](use-kms-keyring.md) 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 AWS KMS key anillo de claves de descifrado en SDK de cifrado de AWS para JavaScript, debe utilizar la clave [ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-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](use-kms-keyring.md#kms-keyring-id) 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, reemplace el ARN de clave de ejemplo por uno válido. Debe tener permiso de `kms:Decrypt` sobre la AWS KMS key. Comience por proporcionar sus credenciales al navegador. [Los SDK de cifrado de AWS para JavaScript ejemplos utilizan el paquete web. DefinePlugin](https://webpack.js.org/plugins/define-plugin/), 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 }) ``` ``` 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](concepts.md#message) 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. ``` const { plaintext, messageHeader } = await decrypt(keyring, result) ``` ``` const { plaintext, messageHeader } = await decrypt(keyring, result) ``` Paso 4: Verificar el contexto de cifrado. El [contexto de cifrado](concepts.md#encryption-context) 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 la firma, el [administrador de materiales criptográficos](concepts.md#crypt-materials-manager) (CMM) agrega 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`). ``` const { encryptionContext } = messageHeader Object .entries(context) .forEach(([key, value]) => { if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values') }) ``` ``` 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.