RsaHashedImportParams — Schnittstelle · JavaScript-Referenz

Signatur

interface RsaHashedImportParams extends Algorithm { name: string; hash: string | Algorithm }

Beschreibung

RsaHashedImportParams ist kein Konstruktor, sondern ein einfaches Objekt (ein WebIDL-Wörterbuch), das beim Import eines RSA-Schlüssels über die Web Crypto API angibt, welcher RSA-Algorithmus genutzt wird und welche Hash-Funktion an den Schlüssel gebunden ist. Man übergibt es als zweites Argument an crypto.subtle.importKey() oder als unwrappedKeyAlgorithm an crypto.subtle.unwrapKey().

Gebraucht wird es immer dann, wenn ein RSA-Schlüssel von außen in die Anwendung kommt – etwa ein öffentlicher Schlüssel im PEM-/SPKI-Format vom Server, ein privater Schlüssel im PKCS#8-Format oder ein JSON Web Key (JWK). Anders als bei RsaHashedKeyGenParams (Schlüsselerzeugung) werden Modulus-Länge und öffentlicher Exponent nicht angegeben, weil sie bereits im Schlüsselmaterial stecken.

Gültige Werte für name sind "RSA-OAEP" (Verschlüsselung), "RSASSA-PKCS1-v1_5" und "RSA-PSS" (Signaturen). Für hash sind "SHA-256", "SHA-384", "SHA-512" und (nicht empfohlen) "SHA-1" zulässig. Der Hash wird fest mit dem importierten CryptoKey verknüpft und gilt für alle späteren Operationen mit diesem Schlüssel.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des RSA-Algorithmus: `"RSA-OAEP"`, `"RSASSA-PKCS1-v1_5"` oder `"RSA-PSS"`.
$hash Pflicht	string \| { name: string }		Zu verwendende Hash-Funktion, z. B. `"SHA-256"` oder `{ name: "SHA-256" }`. Erlaubt: `SHA-1`, `SHA-256`, `SHA-384`, `SHA-512`.

Rückgabewert

Typ

object

Beschreibung

Kein Rückgabewert – es handelt sich um ein Parameterobjekt. Die Funktion importKey(), an die es übergeben wird, liefert ein Promise<CryptoKey>.

Beispiele

Öffentlichen RSA-OAEP-Schlüssel aus PEM (SPKI) importieren

const pemToArrayBuffer = (pem) => {
  const b64 = pem
    .replace(/-----(BEGIN|END) PUBLIC KEY-----/g, '')
    .replace(/\s+/g, '');
  const bin = atob(b64);
  return Uint8Array.from(bin, (c) => c.charCodeAt(0)).buffer;
};

const importPublicKey = async (pem) => {
  // RsaHashedImportParams
  const algorithm = { name: 'RSA-OAEP', hash: 'SHA-256' };
  return crypto.subtle.importKey(
    'spki',
    pemToArrayBuffer(pem),
    algorithm,
    false,          // nicht exportierbar
    ['encrypt']
  );
};

const key = await importPublicKey(serverPem);
console.log(key.algorithm);

{ name: 'RSA-OAEP', modulusLength: 2048, publicExponent: Uint8Array(3), hash: { name: 'SHA-256' } }

JWK für Signaturprüfung mit RSASSA-PKCS1-v1_5 importieren

const verifyToken = async (jwk, signature, data) => {
  const key = await crypto.subtle.importKey(
    'jwk',
    jwk,
    { name: 'RSASSA-PKCS1-v1_5', hash: { name: 'SHA-256' } },
    false,
    ['verify']
  );
  return crypto.subtle.verify('RSASSA-PKCS1-v1_5', key, signature, data);
};

// jwk z. B. aus einem JWKS-Endpunkt (alg: "RS256")
const ok = await verifyToken(jwk, signatureBytes, new TextEncoder().encode(payload));
console.log(ok ? 'Signatur gültig' : 'Signatur ungültig');

Signatur gültig

Privaten RSA-PSS-Schlüssel (PKCS#8) importieren und signieren

const signMessage = async (pkcs8Buffer, message) => {
  const privateKey = await crypto.subtle.importKey(
    'pkcs8',
    pkcs8Buffer,
    { name: 'RSA-PSS', hash: 'SHA-384' },
    false,
    ['sign']
  );
  // saltLength gehört zu RsaPssParams, nicht zum Import
  return crypto.subtle.sign(
    { name: 'RSA-PSS', saltLength: 48 },
    privateKey,
    new TextEncoder().encode(message)
  );
};

const sig = await signMessage(pkcs8, 'Bestellung #4711');
console.log(sig.byteLength);

256

// Wichtig · Fallstricke

Hash muss passen: Beim JWK-Import muss hash zum Feld alg passen (z. B. RS256 ↔ RSASSA-PKCS1-v1_5 + SHA-256, PS384 ↔ RSA-PSS + SHA-384, RSA-OAEP-256 ↔ RSA-OAEP + SHA-256). Sonst wirft importKey() einen DataError.
Nutzungen prüfen: Öffentliche Schlüssel erlauben nur encrypt/wrapKey bzw. verify, private nur decrypt/unwrapKey bzw. sign. Falsche Angaben führen zu einem SyntaxError.
Das Format "raw" wird für RSA nicht unterstützt – nur spki, pkcs8 und jwk.
SHA-1 gilt als kryptografisch schwach und sollte nur für Altsysteme verwendet werden.
Die Web Crypto API ist nur in sicheren Kontexten (HTTPS, localhost) verfügbar; crypto.subtle ist sonst undefined. In Node.js steht sie ab Version 15 über globalThis.crypto.subtle bzw. require('node:crypto').webcrypto bereit.
Private Schlüssel möglichst mit extractable: false importieren, damit sie nicht wieder ausgelesen werden können.

Siehe auch

SubtleCrypto.importKey() SubtleCrypto.unwrapKey() RsaHashedKeyGenParams RsaOaepParams RsaPssParams CryptoKey SubtleCrypto