HmacKeyGenParams — Schnittstelle · JavaScript-Referenz

Signatur

interface HmacKeyGenParams extends Algorithm

Beschreibung

HmacKeyGenParams ist keine Klasse, die man mit new erzeugt, sondern ein einfaches Objekt (Dictionary), das die Web Crypto API beim Aufruf von crypto.subtle.generateKey() auswertet. Es legt fest, dass ein geheimer Schlüssel für den HMAC-Algorithmus (Hash-based Message Authentication Code) erzeugt wird, welche Hash-Funktion dabei verwendet wird und optional, wie lang der Schlüssel in Bit sein soll.

HMAC-Schlüssel braucht man, wenn Daten gegen Manipulation geschützt werden sollen und Sender und Empfänger ein gemeinsames Geheimnis haben – etwa beim Signieren von Tokens (z. B. JWT mit HS256), beim Prüfen von Webhook-Signaturen oder beim Absichern lokal gespeicherter Daten. Der erzeugte CryptoKey wird anschließend mit crypto.subtle.sign() und crypto.subtle.verify() verwendet.

Wird length weggelassen, entspricht die Schlüssellänge der Blockgröße der gewählten Hash-Funktion (512 Bit für SHA-1 und SHA-256, 1024 Bit für SHA-384 und SHA-512). Das ist in fast allen Fällen die richtige Wahl.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Muss `"HMAC"` sein.
$hash Pflicht	string\|{ name: string }		Name der Hash-Funktion: `"SHA-1"`, `"SHA-256"`, `"SHA-384"` oder `"SHA-512"`. Alternativ als Objekt, z. B. `{ name: "SHA-256" }`.
$length	number	Blockgröße der Hash-Funktion	Länge des Schlüssels in Bit. Ohne Angabe wird die Blockgröße des Hash-Algorithmus verwendet.

Beispiele

HMAC-Schlüssel mit SHA-256 erzeugen

const key = await crypto.subtle.generateKey(
  { name: "HMAC", hash: "SHA-256" }, // HmacKeyGenParams
  true,                               // exportierbar
  ["sign", "verify"]
);

console.log(key.type, key.algorithm.name, key.algorithm.hash.name, key.algorithm.length);

secret HMAC SHA-256 512

Nachricht signieren und verifizieren

const key = await crypto.subtle.generateKey(
  { name: "HMAC", hash: { name: "SHA-512" } },
  false,
  ["sign", "verify"]
);

const data = new TextEncoder().encode("Bestellung #4711: 99,90 EUR");
const signature = await crypto.subtle.sign("HMAC", key, data);

const ok = await crypto.subtle.verify("HMAC", key, signature, data);
console.log(signature.byteLength, ok);

64 true

Schlüssel mit eigener Länge erzeugen und exportieren

const key = await crypto.subtle.generateKey(
  { name: "HMAC", hash: "SHA-256", length: 256 }, // 256 Bit statt 512
  true,
  ["sign", "verify"]
);

const raw = await crypto.subtle.exportKey("raw", key);
const hex = [...new Uint8Array(raw)]
  .map((b) => b.toString(16).padStart(2, "0"))
  .join("");
console.log(raw.byteLength, hex.length);

32 64

// Wichtig · Fallstricke

length wird in Bit angegeben, nicht in Byte – length: 32 ergibt einen unsicher kurzen 4-Byte-Schlüssel.
Schlüssel kürzer als die Ausgabelänge des Hashs (z. B. unter 256 Bit bei SHA-256) schwächen die Sicherheit; am besten length einfach weglassen.
SHA-1 wird zwar unterstützt und ist für HMAC noch nicht gebrochen, sollte in neuen Projekten aber nicht mehr eingesetzt werden.
crypto.subtle steht nur in sicheren Kontexten (HTTPS, localhost) zur Verfügung; in Node.js über globalThis.crypto (ab 19) bzw. require(\"node:crypto\").webcrypto.
Nur \"sign\" und \"verify\" sind als Verwendungszwecke erlaubt; andere Werte führen zu einem SyntaxError.
Setzen Sie extractable auf false, wenn der Schlüssel nie exportiert werden muss – so kann er nicht per Skript ausgelesen werden.
Zum Importieren eines bestehenden Schlüssels wird stattdessen HmacImportParams mit importKey() verwendet.

Siehe auch

SubtleCrypto.generateKey() SubtleCrypto.sign() SubtleCrypto.verify() HmacImportParams CryptoKey SubtleCrypto EcdhKeyDeriveParams