CryptoKey.usages — Eigenschaft · JavaScript-Referenz

Signatur

CryptoKey.usages

Beschreibung

Die Eigenschaft usages eines CryptoKey enthält ein Array von Strings, das festlegt, welche Operationen der Web Crypto API mit diesem Schlüssel erlaubt sind. Mögliche Werte sind "encrypt", "decrypt", "sign", "verify", "deriveKey", "deriveBits", "wrapKey" und "unwrapKey".

Die Verwendungszwecke werden beim Erzeugen oder Importieren des Schlüssels über den Parameter keyUsages von SubtleCrypto.generateKey(), importKey(), deriveKey() oder unwrapKey() festgelegt. Danach lassen sie sich nicht mehr ändern. Ruft man eine Operation auf, die nicht in usages steht (z. B. subtle.sign() mit einem Schlüssel, der nur ["verify"] erlaubt), wird das Promise mit einer InvalidAccessError-DOMException abgelehnt.

In der Praxis dient usages vor allem dazu, das Prinzip der minimalen Rechte umzusetzen. Ein Schlüssel sollte nur die Operationen erlauben, die er wirklich braucht. Beim Prüfen von Schlüsseln, etwa vor dem Speichern in IndexedDB oder in Hilfsfunktionen, kann man anhand von usages vorab feststellen, ob eine Operation erlaubt ist.

Bei asymmetrischen Schlüsselpaaren (CryptoKeyPair) verteilt der Browser die angegebenen Verwendungszwecke automatisch: Der öffentliche Schlüssel bekommt z. B. "encrypt"/"verify"/"wrapKey", der private "decrypt"/"sign"/"unwrapKey"/"deriveKey"/"deriveBits".

Rückgabewert

Typ

string[]

Beschreibung

Ein Array mit den erlaubten Verwendungszwecken, z. B. ["encrypt", "decrypt"]. Kann leer sein, etwa bei öffentlichen ECDH-Schlüsseln.

Beispiele

Verwendungszwecke eines AES-Schlüssels auslesen

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

console.log(key.usages);

["encrypt", "decrypt"]

Automatische Aufteilung bei einem Schlüsselpaar

const { publicKey, privateKey } = await crypto.subtle.generateKey(
  { name: 'ECDSA', namedCurve: 'P-256' },
  false,
  ['sign', 'verify']
);

console.log('öffentlich:', publicKey.usages);
console.log('privat:', privateKey.usages);

öffentlich: ["verify"] privat: ["sign"]

Operation vorab prüfen statt Fehler abfangen

const canUse = (key, usage) => key.usages.includes(usage);

const key = await crypto.subtle.generateKey(
  { name: 'HMAC', hash: 'SHA-256' },
  false,
  ['verify'] // bewusst nur Prüfen erlaubt
);

if (!canUse(key, 'sign')) {
  console.log('Schlüssel darf nicht signieren');
}

try {
  await crypto.subtle.sign('HMAC', key, new TextEncoder().encode('Hallo'));
} catch (err) {
  console.log(err.name);
}

Schlüssel darf nicht signieren InvalidAccessError

Verwendungszwecke beim Import einschränken

const rawKey = crypto.getRandomValues(new Uint8Array(32));

// Nur zum Entschlüsseln importieren – Verschlüsseln ist damit ausgeschlossen
const decryptOnly = await crypto.subtle.importKey(
  'raw',
  rawKey,
  'AES-GCM',
  false,
  ['decrypt']
);

console.log(decryptOnly.usages, decryptOnly.extractable);

["decrypt"] false

// Wichtig · Fallstricke

Schreibgeschützt: usages kann nach der Erzeugung nicht geändert werden. Wer andere Verwendungszwecke braucht, muss den Schlüssel neu erzeugen oder, falls extractable gesetzt ist, exportieren und mit anderen keyUsages neu importieren.
Ungültige Kombinationen: Gibt man Verwendungszwecke an, die der Algorithmus nicht unterstützt (z. B. "sign" bei AES-GCM), lehnt generateKey()/importKey() mit einem SyntaxError ab. Das passiert auch bei einem leeren keyUsages-Array für geheime oder private Schlüssel.
Reihenfolge: Die Reihenfolge der Einträge ist nicht garantiert. Deshalb mit includes() prüfen und nicht per Index oder Array-Vergleich.
Sicherheit: usages schränkt nur die Nutzung über die Web Crypto API ein. Ist ein Schlüssel extractable, kann das Schlüsselmaterial trotzdem exportiert und anderswo beliebig genutzt werden. Für echte Einschränkung extractable: false mit minimalen usages kombinieren.
Kompatibilität: Wird in allen modernen Browsern unterstützt, allerdings nur in sicheren Kontexten (HTTPS, localhost). In Node.js steht die Eigenschaft über crypto.webcrypto bzw. ab Version 19 über das globale crypto zur Verfügung.

Siehe auch

Screen.mozBrightness CryptoKey.type CryptoKey.algorithm CryptoKey.extractable Crypto.subtle