AesKeyGenParams — Schnittstelle · JavaScript-Referenz

Signatur

interface AesKeyGenParams extends Algorithm

Beschreibung

AesKeyGenParams ist ein Wörterbuch (Dictionary) der Web Crypto API und keine Klasse, die man instanziiert. Gemeint ist ein einfaches JavaScript-Objekt mit den Eigenschaften name und length. Du übergibst es als algorithm-Argument an crypto.subtle.generateKey(), wenn ein symmetrischer AES-Schlüssel entstehen soll. Das gilt für die Algorithmen AES-CBC, AES-CTR, AES-GCM und AES-KW.

Mit name legst du fest, für welchen AES-Modus der Schlüssel gebunden ist. Ein AES-GCM-Schlüssel lässt sich also nicht mit AES-CBC verwenden. Mit length bestimmst du die Schlüssellänge in Bit: 128, 192 oder 256. Ergebnis ist ein CryptoKey vom Typ "secret".

In der Praxis ist AES-GCM mit 256 Bit die übliche Wahl. Es verschlüsselt authentifiziert, erkennt also Manipulationen, und wird von allen Umgebungen unterstützt. AES-KW dient nur dazu, andere Schlüssel einzupacken (wrapKey() / unwrapKey()). Dasselbe Wörterbuch-Format (name + length) nutzt du auch als derivedKeyType bei deriveKey(), zum Beispiel wenn du mit PBKDF2 aus einem Passwort einen AES-Schlüssel ableitest.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des Algorithmus: `"AES-CBC"`, `"AES-CTR"`, `"AES-GCM"` oder `"AES-KW"`. Groß- und Kleinschreibung spielt keine Rolle.
$length Pflicht	number		Länge des Schlüssels in Bit. Erlaubt sind nur `128`, `192` oder `256`.

Rückgabewert

Typ

Object (Wörterbuch)

Beschreibung

Kein Rückgabewert im eigentlichen Sinn: AesKeyGenParams ist ein Konfigurationsobjekt. Der Aufruf generateKey(), dem du es übergibst, liefert ein Promise<CryptoKey>.

Beispiele

AES-GCM-Schlüssel mit 256 Bit erzeugen

const params = { name: 'AES-GCM', length: 256 }; // AesKeyGenParams

const key = await crypto.subtle.generateKey(
  params,
  true,                    // exportierbar
  ['encrypt', 'decrypt']
);

console.log(key.type, key.algorithm);

secret { name: 'AES-GCM', length: 256 }

Text verschlüsseln und wieder entschlüsseln

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

const iv = crypto.getRandomValues(new Uint8Array(12)); // pro Nachricht neu!
const data = new TextEncoder().encode('Geheime Nachricht');

const cipher = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, data);
const plain = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, cipher);

console.log(cipher.byteLength, new TextDecoder().decode(plain));

33 Geheime Nachricht

AES-KW-Schlüssel zum Einpacken eines anderen Schlüssels

const wrappingKey = await crypto.subtle.generateKey(
  { name: 'AES-KW', length: 256 },
  false,
  ['wrapKey', 'unwrapKey']
);

const dataKey = await crypto.subtle.generateKey(
  { name: 'AES-GCM', length: 128 },
  true, // muss exportierbar sein, sonst schlägt wrapKey fehl
  ['encrypt', 'decrypt']
);

const wrapped = await crypto.subtle.wrapKey('raw', dataKey, wrappingKey, 'AES-KW');
console.log(wrapped.byteLength); // 16 Byte Schlüssel + 8 Byte Integritätsblock

24

Rohen Schlüssel exportieren und Länge prüfen

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

const raw = await crypto.subtle.exportKey('raw', key);
console.log(raw.byteLength * 8);

192

// Wichtig · Fallstricke

Nur sichere Kontexte: crypto.subtle gibt es nur unter HTTPS oder auf localhost. Ansonsten ist der Wert undefined.
Ungültige Länge: Jeder andere Wert als 128, 192 oder 256 lässt das Promise mit einer OperationError scheitern. Bei einem unbekannten name gibt es einen NotSupportedError.
Unpassende Verwendungszwecke erzeugen einen SyntaxError, etwa 'sign' bei einem AES-Schlüssel oder 'encrypt' bei AES-KW.
192 Bit in Chromium: Chrome und Edge unterstützen keine 192-Bit-AES-Schlüssel und werfen einen OperationError. Nimm aus Kompatibilitätsgründen 128 oder 256 Bit.
IV / Nonce: Bei AES-GCM darfst du mit demselben Schlüssel niemals denselben IV zweimal verwenden, sonst ist die Sicherheit vollständig verloren. Nimm 12 zufällige Byte aus crypto.getRandomValues().
AES-CBC und AES-CTR schützen nicht vor Manipulation. Bevorzuge AES-GCM oder kombiniere den Modus mit HMAC.
Setze extractable auf false, wenn du den Schlüssel nicht exportieren musst. Einen nicht exportierbaren CryptoKey kannst du trotzdem in IndexedDB speichern.

Siehe auch

SubtleCrypto.generateKey() CryptoKey SubtleCrypto AesGcmParams AesCbcParams AesCtrParams SubtleCrypto.deriveKey() Crypto.getRandomValues()