Kit SDK de chiffrement AWS pour JavaScript exemples

Les exemples suivants montrent comment utiliser le kit Kit SDK de chiffrement AWS pour JavaScript afin de chiffrer et de déchiffrer des données.

Vous trouverez d'autres exemples d'utilisation des modules Kit SDK de chiffrement AWS pour JavaScript example-node et example-browser du référentiel sur. aws-encryption-sdk-javascript GitHub Ces exemples de modules ne sont pas installés lorsque vous installez les modules client-browser ou client-node.

Voir les exemples de code complets : Nœud : kms_simple.ts, Navigateur : kms_simple.ts

Chiffrer des données à l'aide d'un trousseau de clés AWS KMS

L'exemple suivant montre comment utiliser le Kit SDK de chiffrement AWS pour JavaScript pour chiffrer et déchiffrer une chaîne courte ou un tableau d'octets.

Cet exemple présente un AWS KMS trousseau de clés, un type de porte-clés qui utilise un AWS KMS key pour générer et chiffrer des clés de données. Pour obtenir de l'aide sur la création d'un AWS KMS key, consultez la section Création de clés dans le guide du AWS Key Management Service développeur. Pour obtenir de l'aide pour identifier le contenu AWS KMS keys d'un AWS KMS trousseau de clés, voir Identification AWS KMS keys dans un AWS KMS porte-clés

Étape 1 : Définissez la politique d'engagement.

À partir de la version 1.7. x de Kit SDK de chiffrement AWS pour JavaScript, vous pouvez définir la politique d'engagement lorsque vous appelez la nouvelle buildClient fonction qui instancie un AWS Encryption SDK client. La buildClient fonction prend une valeur énumérée qui représente votre politique d'engagement. Il renvoie des decrypt fonctionnalités mises à jour encrypt et qui appliquent votre politique d'engagement lorsque vous cryptez et déchiffrez.

Les exemples suivants utilisent la buildClient fonction pour spécifier la politique d'engagement par défaut,REQUIRE_ENCRYPT_REQUIRE_DECRYPT. Vous pouvez également utiliser le buildClient pour limiter le nombre de clés de données chiffrées dans un message chiffré. Pour de plus amples informations, veuillez consulter Limiter les clés de données chiffrées.

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
)                                

Étape 2 : Construisez le porte-clés.

Créez un AWS KMS trousseau de clés pour le chiffrement.

Lorsque vous chiffrez avec un AWS KMS trousseau de clés, vous devez spécifier une clé génératrice, c' AWS KMS key est-à-dire une clé utilisée pour générer la clé de données en texte brut et la chiffrer. Vous pouvez également spécifier zéro ou plusieurs clés supplémentaires qui chiffrent la même clé de données en texte brut. Le porte-clés renvoie la clé de données en texte brut et une copie cryptée de cette clé de données pour chacun AWS KMS key des éléments du trousseau, y compris la clé du générateur. Pour déchiffrer les données, vous devez déchiffrer l'une des clés de données chiffrées.

Pour spécifier un jeu AWS KMS keys de clés de chiffrement dans le Kit SDK de chiffrement AWS pour JavaScript, vous pouvez utiliser n'importe quel identifiant de AWS KMS clé compatible. Cet exemple utilise une clé de générateur, identifiée par son alias ARN, et une clé supplémentaire, identifiée par une clé ARN.

Note

Si vous prévoyez de réutiliser votre AWS KMS trousseau de clés pour le déchiffrer, vous devez utiliser une clé pour identifier le AWS KMS keys contenu du trousseau ARNs de clés.

Avant d'exécuter ce code, remplacez les exemples AWS KMS key d'identifiants par des identifiants valides. Vous devez disposer des autorisations requises pour utiliser les AWS KMS keys dans le porte-clés.

JavaScript Browser

Commencez par fournir vos informations d'identification au navigateur. Les Kit SDK de chiffrement AWS pour JavaScript exemples utilisent le webpack. DefinePlugin, qui remplace les constantes d'identification par vos informations d'identification réelles. Mais vous pouvez utiliser n'importe quelle méthode pour fournir vos informations d'identification. Utilisez ensuite les informations d'identification pour créer un AWS KMS client.

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

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

Ensuite, spécifiez AWS KMS keys la clé du générateur et la clé supplémentaire. Créez ensuite un AWS KMS trousseau de clés à l'aide du AWS KMS client et du 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 })

Étape 3 : définissez le contexte de chiffrement.

Un contexte de chiffrement est un ensemble de données authentifiées supplémentaires non secrètes et arbitraires. Lorsque vous fournissez un contexte de chiffrement sur Encrypt, le contexte de chiffrement lie AWS Encryption SDK cryptographiquement le contexte de chiffrement au texte chiffré afin que le même contexte de chiffrement soit requis pour déchiffrer les données. L'utilisation d'un contexte de chiffrement est facultative, mais nous vous le recommandons dans le cadre des bonnes pratiques.

Créez un objet simple qui inclut les paires de contexte de chiffrement. La clé et la valeur de chaque paire doivent être une chaîne.

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

Étape 4 : crypter les données

Pour chiffrer les données en texte brut, appelez la fonction encrypt. Transmettez le AWS KMS trousseau de clés, les données en texte brut et le contexte de chiffrement.

La fonction encrypt renvoie un message chiffré (result) qui contient les données chiffrées, les clés de données chiffrées et les métadonnées importantes, y compris le contexte de chiffrement et la signature.

Vous pouvez déchiffrer ce message crypté à l'aide de n'importe quel langage AWS Encryption SDK de programmation pris en charge.

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

Déchiffrer des données à l'aide d'un trousseau de clés AWS KMS

Vous pouvez utiliser le Kit SDK de chiffrement AWS pour JavaScript pour déchiffrer le message crypté et récupérer les données d'origine.

Dans cet exemple, nous déchiffrons les données que nous avons chiffrées dans l'exemple Chiffrer des données à l'aide d'un trousseau de clés AWS KMS.

Étape 1 : Définissez la politique d'engagement.

À partir de la version 1.7. x de Kit SDK de chiffrement AWS pour JavaScript, vous pouvez définir la politique d'engagement lorsque vous appelez la nouvelle buildClient fonction qui instancie un AWS Encryption SDK client. La buildClient fonction prend une valeur énumérée qui représente votre politique d'engagement. Il renvoie des decrypt fonctionnalités mises à jour encrypt et qui appliquent votre politique d'engagement lorsque vous cryptez et déchiffrez.

Les exemples suivants utilisent la buildClient fonction pour spécifier la politique d'engagement par défaut,REQUIRE_ENCRYPT_REQUIRE_DECRYPT. Vous pouvez également utiliser le buildClient pour limiter le nombre de clés de données chiffrées dans un message chiffré. Pour de plus amples informations, veuillez consulter Limiter les clés de données chiffrées.

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
)                                

Étape 2 : Construisez le porte-clés.

Pour déchiffrer les données, transmettez le message chiffré (result) renvoyé par la fonction encrypt. Le message chiffré inclut les données chiffrées, les clés de données chiffrées et les métadonnées importantes, y compris le contexte de chiffrement et la signature.

Vous devez également spécifier un AWS KMS trousseau de clés lors du déchiffrement. Vous pouvez utiliser le même porte-clés que celui utilisé pour chiffrer les données ou un autre porte-clés. Pour réussir, au moins l'un des AWS KMS key éléments du jeu de clés de déchiffrement doit être capable de déchiffrer l'une des clés de données chiffrées du message chiffré. Étant donné qu'aucune clé de données n'est générée, vous n'avez pas besoin de spécifier une clé de générateur dans un porte-clés de déchiffrement. Si vous le faites, la clé de générateur et les clés supplémentaires sont traitées de la même manière.

Pour spécifier un AWS KMS key jeu de clés de déchiffrement dans le Kit SDK de chiffrement AWS pour JavaScript, vous devez utiliser la clé. ARN Dans le cas contraire, le n' AWS KMS key est pas reconnu. Pour obtenir de l'aide pour identifier le contenu AWS KMS keys d'un AWS KMS trousseau de clés, voir Identification AWS KMS keys dans un AWS KMS porte-clés

Note

Si vous utilisez le même trousseau de clés pour le chiffrement et le déchiffrement, utilisez la clé pour identifier celui qui se trouve dans le trousseau ARNs de clés. AWS KMS keys

Dans cet exemple, nous créons un jeu de clés qui inclut uniquement l'un des éléments du jeu AWS KMS keys de clés de chiffrement. Avant d'exécuter ce code, remplacez l'exemple de clé ARN par une clé valide. Vous devez bénéficier de l'autorisation kms:Decrypt sur la AWS KMS key.

JavaScript Browser

Commencez par fournir vos informations d'identification au navigateur. Les Kit SDK de chiffrement AWS pour JavaScript exemples utilisent le webpack. DefinePlugin, qui remplace les constantes d'identification par vos informations d'identification réelles. Mais vous pouvez utiliser n'importe quelle méthode pour fournir vos informations d'identification. Utilisez ensuite les informations d'identification pour créer un AWS KMS client.

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

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

Créez ensuite un AWS KMS trousseau de clés à l'aide du AWS KMS client. Cet exemple n'utilise que l'un des éléments AWS KMS keys du jeu de clés de chiffrement.

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

Étape 3 : décrypter les données

Appelez ensuite la fonction decrypt. Transmettez le porte-clés de déchiffrement que vous venez de créer (keyring) et le message chiffré renvoyé par la fonction encrypt (result). Il AWS Encryption SDK utilise le trousseau de clés pour déchiffrer l'une des clés de données cryptées. Il utilise ensuite la clé de données en texte brut pour déchiffrer les données.

Si l'appel réussit, le champ plaintext contient les données en texte brut (déchiffrées). Le champ messageHeader contient des métadonnées sur le processus de déchiffrement, y compris le contexte de chiffrement utilisé pour déchiffrer les données.

JavaScript Browser

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

JavaScript Node.js

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

Étape 4 : Vérifiez le contexte de chiffrement.

Le contexte de chiffrement utilisé pour déchiffrer les données est inclus dans l'en-tête de message (messageHeader) renvoyé par la fonction decrypt. Avant que votre application renvoie les données en texte brut, vérifiez que le contexte de chiffrement que vous avez fourni lors du chiffrement est inclus dans le contexte de chiffrement utilisé lors du déchiffrement. Une incompatibilité peut indiquer que les données ont été altérées ou que vous n'avez pas déchiffré le bon texte chiffré.

Lors de la vérification du contexte de chiffrement, la correspondance exacte n'est pas obligatoire. Lorsque vous utilisez un algorithme de chiffrement avec signature, le gestionnaire de matériel cryptographique (CMM) ajoute la clé de signature publique au contexte de chiffrement avant de chiffrer le message. Cependant, toutes les paires de contexte de chiffrement que vous avez soumises doivent être incluses dans le contexte de chiffrement qui a été renvoyé.

Tout d'abord, récupérez le contexte de chiffrement à partir de l'en-tête du message. Vérifiez ensuite que chaque paire clé-valeur du contexte de chiffrement d'origine (context) correspond à une paire clé-valeur dans le contexte de chiffrement renvoyé (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 vérification du contexte de chiffrement aboutit, vous pouvez renvoyer les données en texte brut.