CryptoKey.algorithm — Eigenschaft · JavaScript-Referenz

Signatur

CryptoKey.algorithm

Beschreibung

Die Eigenschaft algorithm eines CryptoKey liefert ein Objekt, das beschreibt, für welchen Algorithmus der Schlüssel erzeugt oder importiert wurde. Es enthält immer die Eigenschaft name (z. B. "AES-GCM", "RSA-PSS", "ECDSA", "HMAC", "Ed25519") und je nach Algorithmus weitere Angaben.

Welche Form das Objekt hat, hängt vom Algorithmus ab:

AesKeyAlgorithm (AES-CBC, AES-CTR, AES-GCM, AES-KW): name, length (128, 192 oder 256 Bit).
RsaHashedKeyAlgorithm (RSASSA-PKCS1-v1_5, RSA-PSS, RSA-OAEP): name, modulusLength, publicExponent (Uint8Array), hash ({ name }).
EcKeyAlgorithm (ECDSA, ECDH): name, namedCurve (z. B. "P-256").
HmacKeyAlgorithm: name, hash ({ name }), length in Bit.
KeyAlgorithm (z. B. Ed25519, X25519, PBKDF2, HKDF): nur name.

Nützlich ist die Eigenschaft vor allem, um unbekannte Schlüssel zu prüfen (etwa nach importKey() oder beim Laden aus IndexedDB), bevor man sie an sign(), encrypt() oder deriveKey() übergibt, sowie für Logging und Debugging. Zusammen mit type, usages und extractable ergibt sich ein vollständiges Bild der Schlüsseleigenschaften.

Rückgabewert

Typ

KeyAlgorithm | AesKeyAlgorithm | RsaHashedKeyAlgorithm | EcKeyAlgorithm | HmacKeyAlgorithm

Beschreibung

Ein Objekt mit mindestens name sowie algorithmusspezifischen Feldern wie length, modulusLength, publicExponent, hash oder namedCurve.

Beispiele

AES-GCM-Schlüssel erzeugen und Algorithmus auslesen

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

console.log(key.algorithm);
console.log(`${key.algorithm.name} mit ${key.algorithm.length} Bit`);

{ name: 'AES-GCM', length: 256 } AES-GCM mit 256 Bit

RSA-PSS-Schlüsselpaar: Hash und Modulus prüfen

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

const { name, modulusLength, hash, publicExponent } = publicKey.algorithm;
console.log(name, modulusLength, hash.name, publicExponent);

RSA-PSS 2048 SHA-256 Uint8Array(3) [1, 0, 1]

Importierten Schlüssel vor der Verwendung validieren

// Prüft, ob ein Schlüssel für ECDSA auf P-256 geeignet ist
const assertEcdsaP256 = (key) => {
  const alg = key.algorithm;
  if (alg.name !== 'ECDSA' || alg.namedCurve !== 'P-256') {
    throw new TypeError(`Unerwarteter Schlüssel: ${JSON.stringify(alg)}`);
  }
  if (!key.usages.includes('verify')) {
    throw new TypeError('Schlüssel darf nicht verifizieren');
  }
};

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

assertEcdsaP256(imported);
console.log('OK:', imported.algorithm);

OK: { name: 'ECDSA', namedCurve: 'P-256' }

HMAC-Schlüssel: Standardlänge ermitteln

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

// Ohne length-Angabe entspricht die Länge der Blockgröße des Hashs
console.log(hmacKey.algorithm.hash.name, hmacKey.algorithm.length);

SHA-512 1024

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen an key.algorithm werden ignoriert (im Strict Mode TypeError). Das zurückgegebene Objekt ist eine Kopie; Änderungen daran wirken sich nicht auf den Schlüssel aus.
Hash immer als Objekt: Auch wenn beim Erzeugen hash: 'SHA-256' als String angegeben wurde, liefert algorithm.hash ein Objekt { name: 'SHA-256' }. Vergleiche daher mit alg.hash.name.
Name-Normalisierung: Algorithmusnamen werden auf die kanonische Schreibweise normalisiert ('aes-gcm' wird zu 'AES-GCM').
Nicht für Parameter pro Operation: Werte wie IV, saltLength oder label sind nicht enthalten – sie werden bei jedem encrypt()/sign()-Aufruf übergeben.
Sichere Kontexte: crypto.subtle steht nur unter HTTPS bzw. localhost zur Verfügung. Ed25519/X25519 werden erst in neueren Browserversionen unterstützt; in Node.js ist die API über globalThis.crypto (ab v19 global, ab v15 über require('node:crypto').webcrypto) verfügbar.
JSON.stringify(key.algorithm) stellt publicExponent (Uint8Array) als Objekt mit Indexschlüsseln dar – für Logging ggf. vorher umwandeln.

Siehe auch

CryptoKey CryptoKey.type CryptoKey.usages CryptoKey.extractable SubtleCrypto.generateKey() SubtleCrypto.importKey() TaskSignal.priority