AWS-Verschlüsselungs-SDK for JavaScriptBeispiele für

Die folgenden Beispiele zeigen Ihnen, wie Sie mit dem AWS-Verschlüsselungs-SDK for JavaScript Daten verschlüsseln und entschlüsseln.

Weitere Beispiele zur Verwendung desAWS-Verschlüsselungs-SDK for JavaScriptimexample-nodeundexample-browser-Module imaws-encryption-sdk-javascript-Repository aufGitHubaus. Diese Beispielmodule werden nicht installiert, wenn Sie die Module client-browser oder client-node installieren.

Die vollständigen Codebeispiele finden Sie unter: Knoten:kms_simple.ts, Browser:kms_simple.ts

Verschlüsseln von Daten mit einemAWS KMSSchlüsselring

Das folgende Beispiel zeigt, wie Sie das AWS-Verschlüsselungs-SDK for JavaScript zum Verschlüsseln und Entschlüsseln eines kurzen Zeichenfolgen- oder Byte-Arrays verwenden.

In diesem Beispiel ist einAWS KMSSchlüsselring, eine Art Schlüsselbund, der einAWS KMS keyum Datenschlüssel zu generieren und zu verschlüsseln. Hilfe beim Erstellen einesAWS KMS key, finden Sie unterErstellen von SchlüsselnimAWS Key Management ServiceEntwicklerhandbuchaus. Hilfe bei der Identifizierung desAWS KMS keysin einemAWS KMSSchlüsselbund finden Sie unterIdentifizierung AWS KMS keys in einem AWS KMS Schlüsselbund

Schritt 1: Erstellen Sie den Schlüsselbund.

Erstellen einesAWS KMSSchlüsselbund für die Verschlüsselung.

Beim Verschlüsseln mit einemAWS KMSSchlüsselbund, müssen Sie einGeneratorschlüssel, das heißt einAWS KMS keyDer verwendet wird, um den Klartext-Datenschlüssel zu generieren und zu verschlüsseln. Sie können auch null oder mehr zusätzliche Schlüssel angeben, die denselben Klartext-Datenschlüssel verschlüsseln. Der Schlüsselbund gibt den Klartext-Datenschlüssel und eine verschlüsselte Kopie dieses Datenschlüssels für jeden AWS KMS key im Schlüsselbund, einschließlich des Generatorschlüssels, zurück. Um die Daten zu entschlüsseln, müssen Sie einen der verschlüsselten Datenschlüssel entschlüsseln.

Um die AWS KMS keys für einen Verschlüsselungsschlüsselbund im AWS-Verschlüsselungs-SDK for JavaScript anzugeben, können Sie einen beliebigen unterstützten AWS KMS-Schlüsselbezeichner verwenden. In diesem Beispiel wird ein Generatorschlüssel verwendet, der durch seinen Alias-ARN identifiziert wird, und ein zusätzlicher Schlüssel, der durch einen Schlüssel-ARN identifiziert wird.

Anmerkung

Wenn Sie vorhaben, Ihre wiederzuverwendenAWS KMSSchlüsselbund zum Entschlüsseln müssen Sie Schlüssel-ARNs verwenden, um dieAWS KMS keysIm Schlüsselbund.

Bevor Sie diesen Code ausführen, ersetzen Sie die AWS KMS key-Beispielbezeichner durch gültige Bezeichner. Sie müssen über die erforderlichen Berechtigungen verfügen, um die AWS KMS keys im Schlüsselbund zu verwenden.

JavaScript Browser

Geben Sie zunächst Ihre Anmeldeinformationen im Browser ein. DieAWS-Verschlüsselungs-SDK for JavaScript-Beispiele verwenden diewebpack.DefinePlugin, das die Anmeldeinformationskonstanten durch Ihre tatsächlichen Anmeldeinformationen ersetzt. Sie können jedoch jede Methode verwenden, um Ihre Anmeldeinformationen anzugeben. Verwenden Sie dann die Anmeldeinformationen, um einen AWS KMS-Client zu erstellen.

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

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

Geben Sie als Nächstes dasAWS KMS keysfür den Generatorschlüssel und den zusätzlichen Schlüssel. Erstellen Sie dann einAWS KMSSchlüsselbund unter Verwendung desAWS KMSKunde und derAWS KMS keysaus.

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

Schritt 2: Legen Sie den Verschlüsselungskontext fest.

Ein Verschlüsselungskontext ist eine Art zufälliger, nicht geheimer, zusätzlich authentifizierter Daten. Wenn Sie beim Verschlüsseln einen Verschlüsselungskontext angegeben, bindet das AWS Encryption SDK den Verschlüsselungskontext kryptografisch an den Verschlüsselungstext. Daher ist zum Entschlüsseln der Daten derselbe Verschlüsselungskontext erforderlich. Die Verwendung eines Verschlüsselungskontexts ist optional, aber wir empfehlen dies als eine bewährte Methode.

Erstellen Sie ein einfaches Objekt, das die Verschlüsselungskontextpaare enthält. Der Schlüssel und der Wert in jedem Paar müssen eine Zeichenfolge sein.

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

Schritt 3: Verschlüsseln Sie die Daten.

Um die Klartextdaten zu verschlüsseln, rufen Sie die encrypt-Funktion auf. Übergeben Sie denAWS KMSSchlüsselbund, Klartextdaten und der Verschlüsselungskontext.

Die encrypt-Funktion gibt eine verschlüsselte Nachricht (result) zurück, die die verschlüsselten Daten, die verschlüsselten Datenschlüssel und wichtige Metadaten enthält, einschließlich des Verschlüsselungskontexts und der Signatur.

Sie können diese verschlüsselte Nachricht entschlüsseln, indem Sie das AWS Encryption SDK für jede unterstützte Programmiersprache verwenden.

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

Entschlüsseln von Daten mit einemAWS KMSSchlüsselring

Sie können das AWS-Verschlüsselungs-SDK for JavaScript verwenden, um die verschlüsselte Nachricht zu entschlüsseln und die ursprünglichen Daten wiederherzustellen.

In diesem Beispiel entschlüsseln wir die Daten, die wir im Verschlüsseln von Daten mit einemAWS KMSSchlüsselring-Beispiel verschlüsselt haben.

Schritt 1: Erstellen Sie den Schlüsselbund.

Um die Daten zu entschlüsseln, übergeben Sie die verschlüsselte Nachricht (result), die die encrypt-Funktion zurückgegeben hat. Die verschlüsselte Nachricht enthält die verschlüsselten Daten, die verschlüsselten Datenschlüssel und wichtige Metadaten, einschließlich des Verschlüsselungskontexts und der Signatur.

Sie müssen auch einen angebenAWS KMSSchlüsselringbeim Entschlüsseln. Sie können denselben Schlüsselbund verwenden, der zum Verschlüsseln der Daten verwendet wurde, oder einen anderen Schlüsselbund. Um erfolgreich zu sein, muss mindestens ein AWS KMS key im Entschlüsselungsschlüsselbund in der Lage sein, einen der verschlüsselten Datenschlüssel in der verschlüsselten Nachricht zu entschlüsseln. Da keine Datenschlüssel generiert werden, müssen Sie keinen Generatorschlüssel in einem Entschlüsselungsschlüsselbund angeben. Wenn Sie dies tun, werden der Generatorschlüssel und zusätzliche Schlüssel auf die gleiche Weise behandelt.

So geben Sie einAWS KMS keyfür einen Entschlüsselungsschlüsselring imAWS-Verschlüsselungs-SDK for JavaScriptverwenden Sie dieSchüssel-ARNaus. Andernfalls wird der AWS KMS key nicht erkannt. Hilfe bei der Identifizierung desAWS KMS keysin einemAWS KMSSchlüsselbund finden Sie unterIdentifizierung AWS KMS keys in einem AWS KMS Schlüsselbund

Anmerkung

Wenn Sie denselben Schlüsselbund zum Verschlüsseln und Entschlüsseln verwenden, verwenden Sie Schlüssel-ARNs, um die AWS KMS keys im Schlüsselbund zu identifizieren.

In diesem Beispiel erstellen wir einen Schlüsselbund, der nur einen der AWS KMS keys im Verschlüsselungsschlüsselbund enthält. Ersetzen Sie vor Ausführung dieses Codes den ARN des Beispiel-Schlüssels durch einen gültigen. Sie müssen über die kms:Decrypt-Berechtigung für den AWS KMS key verfügen.

JavaScript Browser

Geben Sie zunächst Ihre Anmeldeinformationen im Browser ein. DieAWS-Verschlüsselungs-SDK for JavaScript-Beispiele verwenden diewebpack.DefinePlugin, das die Anmeldeinformationskonstanten durch Ihre tatsächlichen Anmeldeinformationen ersetzt. Sie können jedoch jede Methode verwenden, um Ihre Anmeldeinformationen anzugeben. Verwenden Sie dann die Anmeldeinformationen, um einen AWS KMS-Client zu erstellen.

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

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

Erstellen Sie als Nächstes eineAWS KMSSchlüsselbund unter Verwendung desAWS KMS-Client. In diesem Beispiel wird nur einer der AWS KMS keys aus dem Verschlüsselungsschlüsselbund verwendet.

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

Schritt 2: Entschlüsseln Sie die Daten.

Rufen Sie als Nächstes die decrypt-Funktion auf. Übergeben Sie den gerade erstellten Entschlüsselungsschlüsselbund (keyring) und die verschlüsselte Nachricht, die die encrypt-Funktion zurückgegeben hat (result). Das AWS Encryption SDK verwendet den Schlüsselbund, um einen der verschlüsselten Datenschlüssel zu entschlüsseln. Dann verwendet es den Klartext-Datenschlüssel, um die Daten zu entschlüsseln.

Wenn der Aufruf erfolgreich ist, enthält das plaintext-Feld die Klartextdaten (entschlüsselt). Das messageHeader-Feld enthält Metadaten über den Entschlüsselungsprozess, einschließlich des Verschlüsselungskontexts, der zum Entschlüsseln der Daten verwendet wurde.

JavaScript Browser

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

JavaScript Node.js

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

Schritt 3: Überprüfen Sie den Verschlüsselungskontext.

Der Verschlüsselungskontext, der zum Entschlüsseln der Daten verwendet wurde, ist im Nachrichten-Header (messageHeader) enthalten, den die decrypt-Funktion zurückgibt. Bevor Ihre Anwendung die Klartextdaten zurückgibt, stellen Sie sicher, dass der Verschlüsselungskontext, den Sie beim Verschlüsseln angegeben haben, im Verschlüsselungskontext enthalten ist, der bei der Entschlüsselung verwendet wurde. Eine Nichtübereinstimmung kann darauf hindeuten, dass die Daten manipuliert wurden oder dass Sie nicht den richtigen Verschlüsselungstext entschlüsselt haben.

Bei der Überprüfung des Verschlüsselungskontexts ist keine genaue Übereinstimmung erforderlich. Wenn Sie einen Verschlüsselungsalgorithmus mit Signatur verwenden, fügt der Manager von kryptographischen Materialien (CMM) den öffentlichen Signaturschlüssel zum Verschlüsselungskontext hinzu, bevor die Nachricht verschlüsselt wird. Aber alle Verschlüsselungskontextpaare, die Sie übermittelt haben, sollten in den zurückgegebenen Verschlüsselungskontext aufgenommen werden.

Holen Sie sich zuerst den Verschlüsselungskontext aus dem Nachrichten-Header. Stellen Sie dann sicher, dass jedes Schlüssel-Wert-Paar im ursprünglichen Verschlüsselungskontext (context) mit einem Schlüssel-Wert-Paar im zurückgegebenen Verschlüsselungskontext (encryptionContext) übereinstimmt.

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

Wenn die Verschlüsselungskontext-Prüfung erfolgreich ist, können Sie die Klartextdaten zurückgeben.