CryptoKey.type — Eigenschaft · JavaScript-Referenz

Signatur

CryptoKey.type

Beschreibung

Die Eigenschaft type eines CryptoKey-Objekts gibt an, um welche Art von Schlüssel es sich handelt. Möglich sind genau drei Zeichenketten:

"secret": ein geheimer Schlüssel für symmetrische Verfahren wie AES-GCM, AES-CBC, AES-CTR, AES-KW oder HMAC, außerdem Ausgangsmaterial für PBKDF2 und HKDF.
"private": die private Hälfte eines asymmetrischen Schlüsselpaars (RSA, ECDSA, ECDH, Ed25519, X25519).
"public": die öffentliche Hälfte eines asymmetrischen Schlüsselpaars.

Gebraucht wird die Eigenschaft vor allem in allgemeinem Code, der Schlüssel unterschiedlicher Herkunft verarbeitet. Beispiele sind Funktionen, die Schlüssel exportieren, speichern oder protokollieren. Anhand von type lässt sich festlegen, welches Exportformat passt ("raw", "spki", "pkcs8" oder "jwk") und ob ein Schlüssel weitergegeben werden darf.

Der Wert wird beim Erzeugen (generateKey()), Importieren (importKey(), unwrapKey()) oder Ableiten (deriveKey()) festgelegt und lässt sich danach nicht mehr ändern. Er sagt nur etwas über die Art des Schlüssels aus, nicht über den Algorithmus. Den Algorithmus liefert CryptoKey.algorithm.

Rückgabewert

Typ

"secret" | "private" | "public"

Beschreibung

Eine Zeichenkette mit der Art des Schlüssels: "secret" für symmetrische Schlüssel, "private" bzw. "public" für die Hälften eines asymmetrischen Schlüsselpaars.

Beispiele

Typ eines symmetrischen AES-Schlüssels abfragen

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

console.log(aesKey.type);

secret

Beide Hälften eines ECDSA-Schlüsselpaars

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

console.log(publicKey.type);
console.log(privateKey.type);

public private

Passendes Exportformat je nach Schlüsseltyp wählen

const exportFormatFor = (key) => {
  switch (key.type) {
    case 'secret':  return 'raw';
    case 'public':  return 'spki';
    case 'private': return 'pkcs8';
    default: throw new TypeError(`Unbekannter Schlüsseltyp: ${key.type}`);
  }
};

const exportKeyAsBase64 = async (key) => {
  const format = exportFormatFor(key);
  const buffer = await crypto.subtle.exportKey(format, key);
  const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));
  return { format, base64 };
};

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

const result = await exportKeyAsBase64(publicKey);
console.log(result.format);

spki

Weitergabe privater Schlüssel verhindern

const sendKeyToServer = async (key) => {
  if (key.type !== 'public') {
    throw new Error('Nur öffentliche Schlüssel dürfen übertragen werden!');
  }
  const jwk = await crypto.subtle.exportKey('jwk', key);
  await fetch('/api/keys', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(jwk)
  });
};

const pair = await crypto.subtle.generateKey(
  { name: 'ECDH', namedCurve: 'P-256' },
  true,
  ['deriveKey']
);

try {
  await sendKeyToServer(pair.privateKey);
} catch (err) {
  console.log(err.message);
}

Nur öffentliche Schlüssel dürfen übertragen werden!

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie key.type = 'public' wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus. Der Typ lässt sich nicht nachträglich ändern.
Typ und Exportierbarkeit sind zwei verschiedene Dinge: Ob ein Schlüssel exportiert werden kann, bestimmt CryptoKey.extractable, nicht type. Ein privater Schlüssel mit extractable: false lässt sich trotzdem abfragen, aber nicht exportieren.
Öffentliche Schlüssel sind immer exportierbar: Bei generateKey() wird der öffentliche Schlüssel eines Paars unabhängig vom Parameter extractable immer mit extractable: true erzeugt.
Formate passen nur zu bestimmten Typen: "spki" ist nur für "public" gültig, "pkcs8" nur für "private". Ein falsches Format führt zu einem InvalidAccessError bzw. NotSupportedError. "raw" geht bei symmetrischen Schlüsseln und bei öffentlichen EC-/Ed25519-/X25519-Schlüsseln.
Kompatibilität: CryptoKey und crypto.subtle gibt es nur in sicheren Kontexten (HTTPS oder localhost). In Node.js ist die API über globalThis.crypto (ab Version 19 global) bzw. require('node:crypto').webcrypto erreichbar.

Siehe auch

CryptoKey CryptoKey.algorithm CryptoKey.extractable CryptoKey.usages SubtleCrypto.generateKey() SubtleCrypto.exportKey() SubtleCrypto.importKey() CryptoKeyPair