AWS-Verschlüsselungs-SDK for JavaScript Beispiele - AWS Encryption SDK
AWS KMS Daten mit einem Schlüsselbund verschlüsselnDaten mit einem Schlüsselbund entschlüsseln AWS KMS

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

AWS-Verschlüsselungs-SDK for JavaScript Beispiele

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

Weitere Beispiele für die Verwendung der Module AWS-Verschlüsselungs-SDK for JavaScript in den Modulen example-node und example-browser im Repository finden Sie unter. aws-encryption-sdk-javascript GitHub Diese Beispielmodule werden nicht installiert, wenn Sie die Module client-browser oder client-node installieren.

Die vollständigen Codebeispiele anzeigen: Knoten: kms_simple.ts, Browser: kms_simple.ts

AWS KMS Daten mit einem Schlüsselbund verschlüsseln

Das folgende Beispiel zeigt Ihnen, wie Sie mit dem eine kurze Zeichenfolge AWS-Verschlüsselungs-SDK for JavaScript oder ein Byte-Array verschlüsseln und entschlüsseln können.

Dieses Beispiel zeigt einen AWS KMS Schlüsselbund, eine Art von Schlüsselbund, der AWS KMS key zum Generieren und Verschlüsseln von Datenschlüsseln verwendet wird. Hilfe bei der Erstellung eines AWS KMS key finden Sie unter Creating Keys im AWS Key Management Service Developer Guide. Hilfe bei der Identifizierung von AWS KMS keys in einem AWS KMS Schlüsselbund finden Sie unter Identifizierung AWS KMS keys in einem AWS KMS Schlüsselbund

Schritt 1: Legen Sie die Verpflichtungsrichtlinie fest.

Ab Version 1.7. x von AWS-Verschlüsselungs-SDK for JavaScript, Sie können die Commitment-Richtlinie festlegen, wenn Sie die neue buildClient Funktion aufrufen, die einen AWS Encryption SDK Client instanziiert. Die buildClient Funktion verwendet einen Aufzählungswert, der Ihre Commitment-Richtlinie darstellt. Sie gibt aktualisierte decrypt Funktionen encrypt und Funktionen zurück, die Ihre Verpflichtungsrichtlinie beim Verschlüsseln und Entschlüsseln durchsetzen.

In den folgenden Beispielen wird die buildClient Funktion verwendet, um die Standard-Commitment-Richtlinie anzugeben,. REQUIRE_ENCRYPT_REQUIRE_DECRYPT Sie können die auch verwendenbuildClient, um die Anzahl der verschlüsselten Datenschlüssel in einer verschlüsselten Nachricht zu begrenzen. Weitere Informationen finden Sie unter Beschränkung verschlüsselter Datenschlüssel.

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
)
Schritt 2: Konstruieren Sie den Schlüsselbund.

Erstellen Sie einen AWS KMS Schlüsselbund für die Verschlüsselung.

Bei der Verschlüsselung mit einem AWS KMS Schlüsselbund müssen Sie einen Generatorschlüssel angeben, d. h. einen, der verwendet wird AWS KMS key , 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 zurück, einschließlich des Generatorschlüssels. Um die Daten zu entschlüsseln, müssen Sie einen der verschlüsselten Datenschlüssel entschlüsseln.

Um den Schlüsselbund AWS KMS keys für die Verschlüsselung in der anzugeben AWS-Verschlüsselungs-SDK for JavaScript, können Sie eine beliebige unterstützte Schlüssel-ID verwenden. AWS KMS In diesem Beispiel werden ein Generatorschlüssel verwendet, der durch seinen Alias identifiziert wirdARN, und ein zusätzlicher Schlüssel, der durch einen Schlüssel ARN identifiziert wird.

Anmerkung

Wenn Sie Ihren AWS KMS Schlüsselbund zum Entschlüsseln wiederverwenden möchten, müssen Sie den Schlüssel verwenden, ARNs um ihn AWS KMS keys im Schlüsselbund zu identifizieren.

Bevor Sie diesen Code ausführen, ersetzen Sie die Beispielbezeichner durch gültige AWS KMS key 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. Die AWS-Verschlüsselungs-SDK for JavaScript Beispiele verwenden das Webpack. DefinePlugin, wodurch die Credential-Konstanten durch Ihre tatsächlichen Anmeldeinformationen ersetzt werden. 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 den Schlüssel und den Zusatzschlüssel AWS KMS keys für den Generator an. Erstellen Sie dann einen AWS KMS Schlüsselbund mit dem AWS KMS Client und dem 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 })
Schritt 3: Stellen Sie den Verschlüsselungskontext ein.

Ein Verschlüsselungskontext ist eine Art zufälliger, nicht geheimer, zusätzlich authentifizierter Daten. Wenn Sie bei Encrypt einen Verschlüsselungskontext angeben, bindet der Verschlüsselungskontext AWS Encryption SDK kryptografisch an den Chiffretext, sodass derselbe Verschlüsselungskontext zum Entschlüsseln der Daten erforderlich ist. 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 4: Verschlüsseln Sie die Daten.

Um die Klartextdaten zu verschlüsseln, rufen Sie die encrypt-Funktion auf. Übergeben Sie den AWS KMS Schlüsselbund, die Klartextdaten und den 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 })

Daten mit einem Schlüsselbund entschlüsseln AWS KMS

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

In diesem Beispiel entschlüsseln wir die Daten, die wir im AWS KMS Daten mit einem Schlüsselbund verschlüsseln-Beispiel verschlüsselt haben.

Schritt 1: Legen Sie die Verpflichtungsrichtlinie fest.

Ab Version 1.7. x von AWS-Verschlüsselungs-SDK for JavaScript, Sie können die Commitment-Richtlinie festlegen, wenn Sie die neue buildClient Funktion aufrufen, die einen AWS Encryption SDK Client instanziiert. Die buildClient Funktion verwendet einen Aufzählungswert, der Ihre Commitment-Richtlinie darstellt. Sie gibt aktualisierte decrypt Funktionen encrypt und Funktionen zurück, die Ihre Verpflichtungsrichtlinie beim Verschlüsseln und Entschlüsseln durchsetzen.

In den folgenden Beispielen wird die buildClient Funktion verwendet, um die Standard-Commitment-Richtlinie anzugeben,. REQUIRE_ENCRYPT_REQUIRE_DECRYPT Sie können die auch verwendenbuildClient, um die Anzahl der verschlüsselten Datenschlüssel in einer verschlüsselten Nachricht zu begrenzen. Weitere Informationen finden Sie unter Beschränkung verschlüsselter Datenschlüssel.

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
)
Schritt 2: Konstruieren 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 beim Entschlüsseln auch einen AWS KMS Schlüsselbund angeben. 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 einer der AWS KMS key Schlüsselbunde 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.

Um einen Schlüsselbund AWS KMS key für die Entschlüsselung in der anzugeben AWS-Verschlüsselungs-SDK for JavaScript, müssen Sie den Schlüssel verwenden. ARN Andernfalls AWS KMS key wird der nicht erkannt. Hilfe bei der Identifizierung von AWS KMS keys in einem AWS KMS Schlüsselbund finden Sie unter Identifizierung AWS KMS keys in einem AWS KMS Schlüsselbund

Anmerkung

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

In diesem Beispiel erstellen wir einen Schlüsselbund, der nur einen der im Verschlüsselungsschlüsselbund enthaltenen Schlüssel enthält. AWS KMS keys Bevor Sie diesen Code ausführen, ersetzen Sie den Beispielschlüssel ARN 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. Die AWS-Verschlüsselungs-SDK for JavaScript Beispiele verwenden das Webpack. DefinePlugin, wodurch die Credential-Konstanten durch Ihre tatsächlichen Anmeldeinformationen ersetzt werden. 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 mithilfe des AWS KMS Clients einen AWS KMS Schlüsselbund. In diesem Beispiel wird nur einer der Schlüsselbunde 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 3: 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). Der 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 4: Ü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 Cryptographic Materials Manager (CMM) den öffentlichen Signaturschlüssel dem 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.