Exemples Kit SDK de chiffrement AWS pour JavaScript

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 duKit SDK de chiffrement AWS pour JavaScriptdans leexample-nodeetexample-browserModules dans le kitaws-encryption-sdk-javascriptrepository surGitHub. Ces exemples de modules ne sont pas installés lorsque vous installez les modules client-browser ou client-node.

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

Chiffrement des données à l'aide d'unAWS KMSPorte-clés

L'exemple suivant montre comment utiliser le kit 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 unAWS KMSPorte-clés, un type de porte-clés qui utilise unAWS KMS keypour générer et chiffrer des clés de données. Pour obtenir de l'aide pour créer unAWS KMS key, voirCréation de clésdans leAWS Key Management ServiceManuel du développeur. Pour obtenir de l'aide pour identifier leAWS KMS keysdans unAWS KMSporte-clés, voirIdentification de clés AWS KMS keys dans un porte-clés AWS KMS

Étape 1 : Construction du porte-clés.

Création d'unAWS KMSporte-clés pour le chiffrement.

Lors du chiffrement avec unAWS KMSporte-clés, vous devez spécifier unclé du générateur, c'est-à-dire unAWS KMS keyqui est utilisé 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 chiffrée de cette clé de données pour chaque AWS KMS key du porte-clés, y compris la clé de 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 les AWS KMS keys pour un porte- clés de chiffrement dans le kit Kit SDK de chiffrement AWS pour JavaScript, vous pouvez utiliser n'importe quel identificateur de clé AWS KMS pris en charge. Cet exemple utilise une clé de générateur, identifiée par son ARN d'alias, et une clé supplémentaire, identifiée par un ARN de clé.

Note

Si vous envisagez de réutiliser votreAWS KMSpour le déchiffrement, vous devez utiliser les ARN de clé pour identifier lesAWS KMS keysdans le porte-clés.

Avant d'exécuter ce code, remplacez les exemples d'identifiants AWS KMS key 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. LeKit SDK de chiffrement AWS pour JavaScriptExemples d'avecwebpack.DefinePlugin, qui remplace les constantes d'informations d'identification par vos informations d'identification réelles. Mais vous pouvez utiliser n'importe quelle méthode pour fournir vos informations d'identification. Ensuite, utilisez les informations d'identification pour créer un client AWS KMS.

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

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

Ensuite, spécifiez leAWS KMS keyspour la clé du générateur et la clé supplémentaire. Ensuite, créez unAWS KMSporte-clés utilisant leAWS KMSclient et leAWS 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 2 : 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 lors du chiffrement, le kit AWS Encryption SDK le lie de façon cryptographique au texte chiffré de sorte que le même contexte de chiffrement est 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 3 : Chiffrez les données.

Pour chiffrer les données en texte brut, appelez la fonction encrypt. Transmettre dans leAWS KMSle porte-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 à l'aide du kit AWS Encryption SDK pour n'importe quel langage 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échiffrement des données à l'aide d'unAWS KMSPorte-clés

Vous pouvez utiliser le kit Kit SDK de chiffrement AWS pour JavaScript pour déchiffrer le message chiffré 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 Chiffrement des données à l'aide d'unAWS KMSPorte-clés.

Étape 1 : Construction du 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 unAWS KMSPorte-cléslors 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 une AWS KMS key dans le porte-clés de déchiffrement doit être en mesure 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 unAWS KMS keypour un porte-clés de déchiffrement dans leKit SDK de chiffrement AWS pour JavaScript, vous devez utiliser leARN de clé. Sinon, la AWS KMS key n'est pas reconnue. Pour obtenir de l'aide pour identifier leAWS KMS keysdans unAWS KMSporte-clés, voirIdentification de clés AWS KMS keys dans un porte-clés AWS KMS

Note

Si vous utilisez le même porte-clés pour chiffrer et déchiffrer, utilisez des ARN de clé pour identifier les AWS KMS keys dans le porte-clés.

Dans cet exemple, nous créons un porte-clés qui inclut une seule des AWS KMS keys dans le porte-clés de chiffrement. Avant d'exécuter ce code, remplacez l'exemple d'ARN de clé par un ARN 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. LeKit SDK de chiffrement AWS pour JavaScriptExemples d'avecwebpack.DefinePlugin, qui remplace les constantes d'informations d'identification par vos informations d'identification réelles. Mais vous pouvez utiliser n'importe quelle méthode pour fournir vos informations d'identification. Ensuite, utilisez les informations d'identification pour créer un client AWS KMS.

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

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

Ensuite, créez unAWS KMSporte-clés utilisant leAWS KMSclient. Cet exemple utilise une seule des AWS KMS keys du porte-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 2 : Déchiffrement des 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). Le kit AWS Encryption SDK utilise le porte-clés pour déchiffrer l'une des clés de données chiffré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 3 : 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ériaux de chiffrement (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.