SubtleCrypto.encrypt() — Methode · JavaScript-Referenz

Signatur

SubtleCrypto.prototype.encrypt(algorithm, key, data)

Beschreibung

Mit crypto.subtle.encrypt() verschlüsseln Sie Binärdaten direkt im Browser oder in Node.js, ohne dass Sie externe Bibliotheken brauchen. Die Methode nimmt ein Algorithmus-Objekt, einen passenden CryptoKey und die Klartextdaten als ArrayBuffer, TypedArray oder DataView entgegen. Zurück kommt ein Promise, das mit dem Geheimtext als ArrayBuffer erfüllt wird.

Unterstützt werden diese Algorithmen:

AES-GCM: authentifizierte Verschlüsselung, für fast alle Fälle die empfohlene Wahl. Braucht einen eindeutigen iv (12 Byte).
AES-CBC: klassischer Blockmodus mit 16-Byte-iv, aber ohne Integritätsschutz.
AES-CTR: Zählermodus mit counter und length, ebenfalls ohne Authentifizierung.
RSA-OAEP: asymmetrisch. Eignet sich nur für kleine Datenmengen, typischerweise um einen symmetrischen Schlüssel zu verpacken.

Der Schlüssel muss zum angegebenen Algorithmus passen. Außerdem muss er mit der Verwendung "encrypt" in usages erzeugt oder importiert worden sein, zum Beispiel über generateKey() oder importKey(). Sonst wird das Promise mit einer InvalidAccessError-DOMException abgelehnt. Entschlüsselt wird mit decrypt(). Dafür brauchen Sie denselben Algorithmus und dieselben Parameter (IV, Zusatzdaten, Tag-Länge).

SubtleCrypto steht nur in sicheren Kontexten zur Verfügung, also über HTTPS oder localhost. In unsicheren Kontexten ist crypto.subtle undefined.

Parameter

Name	Typ	Beschreibung
$algorithm Pflicht	RsaOaepParams \| AesCtrParams \| AesCbcParams \| AesGcmParams	Objekt mit `name` (`"RSA-OAEP"`, `"AES-CTR"`, `"AES-CBC"`, `"AES-GCM"`) und den Parametern des jeweiligen Algorithmus: `iv` (GCM/CBC), `counter` + `length` (CTR), optional `additionalData` und `tagLength` (GCM, Standard 128) oder `label` (RSA-OAEP).
$key Pflicht	CryptoKey	Schlüssel für die Verschlüsselung. Er muss zum Algorithmus passen und `"encrypt"` in `usages` enthalten. Bei RSA-OAEP ist das der öffentliche Schlüssel.
$data Pflicht	ArrayBuffer \| TypedArray \| DataView	Die zu verschlüsselnden Klartextdaten. Text wandeln Sie vorher mit `TextEncoder` in Bytes um.

Rückgabewert

Typ

Promise<ArrayBuffer>

Beschreibung

Promise, das mit dem Geheimtext als ArrayBuffer erfüllt wird. Bei AES-GCM ist das Authentifizierungs-Tag an das Ende angehängt. Wenn der Schlüssel nicht passt oder die Parameter ungültig sind, wird das Promise mit einer DOMException (InvalidAccessError bzw. OperationError) abgelehnt.

Beispiele

Text mit AES-GCM verschlüsseln und entschlüsseln

const key = await crypto.subtle.generateKey(
  { name: 'AES-GCM', length: 256 },
  true,
  ['encrypt', 'decrypt']
);

// Für jede Verschlüsselung einen neuen, zufälligen IV erzeugen
const iv = crypto.getRandomValues(new Uint8Array(12));
const plaintext = new TextEncoder().encode('Geheime Nachricht');

const ciphertext = await crypto.subtle.encrypt(
  { name: 'AES-GCM', iv },
  key,
  plaintext
);
console.log('Geheimtext-Länge:', ciphertext.byteLength);

const decrypted = await crypto.subtle.decrypt(
  { name: 'AES-GCM', iv },
  key,
  ciphertext
);
console.log(new TextDecoder().decode(decrypted));

Geheimtext-Länge: 33 Geheime Nachricht

Verschlüsseltes Paket als Base64 speichern (IV + Geheimtext)

const toBase64 = (bytes) => btoa(String.fromCharCode(...bytes));

const encryptToString = async (key, text) => {
  const iv = crypto.getRandomValues(new Uint8Array(12));
  const ct = new Uint8Array(
    await crypto.subtle.encrypt(
      { name: 'AES-GCM', iv },
      key,
      new TextEncoder().encode(text)
    )
  );
  // IV vor den Geheimtext setzen, damit er beim Entschlüsseln verfügbar ist
  const packed = new Uint8Array(iv.length + ct.length);
  packed.set(iv);
  packed.set(ct, iv.length);
  return toBase64(packed);
};

const key = await crypto.subtle.generateKey(
  { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']
);
const stored = await encryptToString(key, JSON.stringify({ token: 'abc123' }));
localStorage.setItem('secret', stored);
console.log(stored.length > 0);

true

Passwortbasierter Schlüssel (PBKDF2) mit Zusatzdaten

const password = 'korrekt-pferd-batterie';
const salt = crypto.getRandomValues(new Uint8Array(16));

const baseKey = await crypto.subtle.importKey(
  'raw', new TextEncoder().encode(password), 'PBKDF2', false, ['deriveKey']
);

const aesKey = await crypto.subtle.deriveKey(
  { name: 'PBKDF2', salt, iterations: 600000, hash: 'SHA-256' },
  baseKey,
  { name: 'AES-GCM', length: 256 },
  false,
  ['encrypt', 'decrypt']
);

const iv = crypto.getRandomValues(new Uint8Array(12));
const ciphertext = await crypto.subtle.encrypt(
  {
    name: 'AES-GCM',
    iv,
    // Wird mit authentifiziert, aber nicht verschlüsselt
    additionalData: new TextEncoder().encode('user-42')
  },
  aesKey,
  new TextEncoder().encode('Notiz: Tresorcode 1234')
);
console.log(ciphertext instanceof ArrayBuffer);

true

Kleine Daten mit RSA-OAEP für einen öffentlichen Schlüssel verschlüsseln

const { publicKey, privateKey } = await crypto.subtle.generateKey(
  {
    name: 'RSA-OAEP',
    modulusLength: 2048,
    publicExponent: new Uint8Array([1, 0, 1]),
    hash: 'SHA-256'
  },
  true,
  ['encrypt', 'decrypt']
);

const ct = await crypto.subtle.encrypt(
  { name: 'RSA-OAEP' },
  publicKey,
  new TextEncoder().encode('Sitzungsschlüssel')
);
console.log(ct.byteLength);

const pt = await crypto.subtle.decrypt({ name: 'RSA-OAEP' }, privateKey, ct);
console.log(new TextDecoder().decode(pt));

256 Sitzungsschlüssel

Siehe auch

SubtleCrypto.decrypt() SubtleCrypto.digest() SubtleCrypto.unwrapKey() SubtleCrypto.verify() SubtleCrypto.exportKey() PushSubscription.unsubscribe() new TextFormat()