Crypto — Schnittstelle · JavaScript-Referenz

Signatur

interface Crypto

Beschreibung

Das Crypto-Interface stellt grundlegende Kryptografie-Funktionen des aktuellen Kontexts bereit. Du erreichst die Instanz über die globale Eigenschaft crypto (window.crypto im Hauptthread, self.crypto in Workern). Ein eigener Konstruktor existiert nicht – new Crypto() löst einen TypeError aus.

Das Interface besteht aus drei Bausteinen:

crypto.getRandomValues(typedArray) – füllt ein Integer-Typed-Array mit kryptografisch sicheren Zufallswerten, zum Beispiel für Tokens, Nonces oder Salts.
crypto.randomUUID() – liefert eine zufällige UUID der Version 4 als String mit 36 Zeichen.
crypto.subtle – ein SubtleCrypto-Objekt für Hashing, Signaturen, Ver- und Entschlüsselung sowie Schlüsselverwaltung (AES, RSA, ECDSA, HMAC, SHA-256 u. a.).

Nimm Crypto immer dann, wenn Zufall sicherheitsrelevant ist. Math.random() ist dafür nicht geeignet, weil seine Ausgabe vorhersagbar sein kann. Für echte kryptografische Operationen wie Hashes und Verschlüsselung nimmst du crypto.subtle statt selbst gebauter Algorithmen.

Rückgabewert

Typ

Crypto

Beschreibung

Die globale Instanz über globalThis.crypto. Sie hat die Eigenschaft subtle (SubtleCrypto) sowie die Methoden getRandomValues() (gibt dasselbe Typed Array zurück) und randomUUID() (gibt string zurück).

Beispiele

Sicheren Zufalls-Token erzeugen (getRandomValues)

// 32 zufällige Bytes als Hex-String, z. B. für CSRF-Tokens
const createToken = (byteLength = 32) => {
  const bytes = crypto.getRandomValues(new Uint8Array(byteLength));
  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
};

const token = createToken();
console.log(token.length);

64

Eindeutige IDs mit randomUUID()

// Client-seitige IDs für neue Einträge in einer Liste
const todos = [];
const addTodo = (text) => {
  const todo = { id: crypto.randomUUID(), text, done: false };
  todos.push(todo);
  return todo;
};

const todo = addTodo('Referenz schreiben');
console.log(/^[0-9a-f-]{36}$/.test(todo.id), todo.id[14]);

true 4

SHA-256-Hash über crypto.subtle berechnen

const sha256 = async (text) => {
  const data = new TextEncoder().encode(text);
  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
  return Array.from(new Uint8Array(hashBuffer), (b) => b.toString(16).padStart(2, '0')).join('');
};

console.log(await sha256('hallo'));

d3751d33f9cd5049c4af2b462735457e4d3baf130bcbb87f389e349fbaeb20b9

Zufällige Ganzzahl ohne Modulo-Verzerrung

// Gleichverteilte Zahl im Bereich [0, max) per Rejection Sampling
const secureRandomInt = (max) => {
  const limit = Math.floor(0x100000000 / max) * max;
  const buf = new Uint32Array(1);
  do {
    crypto.getRandomValues(buf);
  } while (buf[0] >= limit);
  return buf[0] % max;
};

// Würfelwurf 1–6
console.log(secureRandomInt(6) + 1);

z. B. 4

// Wichtig · Fallstricke

Sicherer Kontext: crypto.subtle und randomUUID() gibt es nur in sicheren Kontexten (HTTPS oder localhost). Über reines HTTP ist crypto.subtle undefined. getRandomValues() funktioniert dagegen überall.
Größenlimit: getRandomValues() akzeptiert höchstens 65.536 Bytes pro Aufruf, sonst kommt ein QuotaExceededError. Erlaubt sind nur Integer-Typed-Arrays. Float32Array und Float64Array lösen einen TypeMismatchError aus.
Kein Ersatz für Server-Sicherheit: Code im Client lässt sich einsehen und manipulieren. Geheime Schlüssel gehören nicht in den Browser-Quelltext.
Math.random() ist nicht sicher: Für Passwörter, Tokens oder Session-IDs musst du immer crypto nehmen.
Methoden nicht abtrennen: const { getRandomValues } = crypto; getRandomValues(arr) wirft einen TypeError (Illegal invocation). Rufe die Methoden immer über das crypto-Objekt auf oder binde sie mit .bind(crypto).
Node.js: Global verfügbar als globalThis.crypto ab Node.js 19. In älteren Versionen nutzt du require('node:crypto').webcrypto. Das Node-Modul node:crypto ist eine eigene, abweichende API.
Kompatibilität: getRandomValues() und subtle laufen in allen modernen Browsern. randomUUID() gibt es seit Chrome 92, Firefox 95 und Safari 15.4.

Siehe auch

Crypto.subtle Math.random() CryptoKey Attr BarProp