RsaOaepParams — Schnittstelle · JavaScript-Referenz

Signatur

interface RsaOaepParams extends Algorithm

Beschreibung

RsaOaepParams ist kein Konstruktor, sondern ein einfaches Parameter-Objekt (ein sogenanntes Dictionary) der Web Crypto API. Man übergibt es als ersten Parameter an crypto.subtle.encrypt(), decrypt(), wrapKey() oder unwrapKey(), wenn ein RSA-Schlüssel mit dem Verfahren RSA-OAEP (Optimal Asymmetric Encryption Padding) verwendet wird.

Das Objekt hat die Pflicht-Eigenschaft name mit dem Wert "RSA-OAEP" und optional eine label-Eigenschaft. Die Hash-Funktion (z. B. SHA-256) wird nicht hier festgelegt, sondern bereits beim Erzeugen bzw. Importieren des Schlüssels über RsaHashedKeyGenParams bzw. RsaHashedImportParams.

RSA-OAEP eignet sich nur für kleine Datenmengen: Bei einem 2048-Bit-Schlüssel und SHA-256 sind maximal 190 Byte Klartext möglich (Schlüssellänge in Byte − 2 × Hash-Länge − 2). In der Praxis verschlüsselt man mit RSA-OAEP daher meist einen symmetrischen Schlüssel (z. B. AES-GCM), der wiederum die eigentlichen Daten schützt (hybride Verschlüsselung), etwa über wrapKey().

Das optionale label sind zusätzliche Daten, die nicht verschlüsselt, aber kryptografisch an den Geheimtext gebunden werden. Beim Entschlüsseln muss exakt dasselbe Label angegeben werden, sonst schlägt der Vorgang fehl.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des Algorithmus. Muss `"RSA-OAEP"` sein.
$label	ArrayBuffer \| TypedArray \| DataView	leeres Label	Optionale Zusatzdaten, die an den Geheimtext gebunden, aber nicht verschlüsselt werden. Beim Entschlüsseln muss dasselbe Label übergeben werden. Die meisten Anwendungen lassen es weg.

Rückgabewert

Typ

RsaOaepParams

Beschreibung

Kein Rückgabewert im eigentlichen Sinn – es handelt sich um ein reines Objekt-Literal, das an Methoden von SubtleCrypto übergeben wird.

Beispiele

Schlüsselpaar erzeugen und Text ver- und entschlüsseln

const keyPair = await crypto.subtle.generateKey(
  {
    name: 'RSA-OAEP',
    modulusLength: 2048,
    publicExponent: new Uint8Array([1, 0, 1]),
    hash: 'SHA-256', // Hash wird hier festgelegt, nicht in RsaOaepParams
  },
  true,
  ['encrypt', 'decrypt']
);

// RsaOaepParams
const params = { name: 'RSA-OAEP' };

const klartext = new TextEncoder().encode('Geheime PIN: 4711');
const geheimtext = await crypto.subtle.encrypt(params, keyPair.publicKey, klartext);
console.log('Länge Geheimtext:', geheimtext.byteLength);

const entschluesselt = await crypto.subtle.decrypt(params, keyPair.privateKey, geheimtext);
console.log(new TextDecoder().decode(entschluesselt));

Länge Geheimtext: 256 Geheime PIN: 4711

Label an den Geheimtext binden

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

const enc = new TextEncoder();
const label = enc.encode('benutzer-42');

const geheimtext = await crypto.subtle.encrypt(
  { name: 'RSA-OAEP', label },
  publicKey,
  enc.encode('Token XYZ')
);

try {
  // Falsches Label -> Entschlüsselung schlägt fehl
  await crypto.subtle.decrypt({ name: 'RSA-OAEP', label: enc.encode('benutzer-43') }, privateKey, geheimtext);
} catch (err) {
  console.log('Fehler:', err.name);
}

const ok = await crypto.subtle.decrypt({ name: 'RSA-OAEP', label }, privateKey, geheimtext);
console.log(new TextDecoder().decode(ok));

Fehler: OperationError Token XYZ

Hybride Verschlüsselung: AES-Schlüssel mit wrapKey() einpacken

const rsa = await crypto.subtle.generateKey(
  { name: 'RSA-OAEP', modulusLength: 3072, publicExponent: new Uint8Array([1, 0, 1]), hash: 'SHA-256' },
  true,
  ['wrapKey', 'unwrapKey']
);

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

// AES-Schlüssel mit dem öffentlichen RSA-Schlüssel verpacken
const wrapped = await crypto.subtle.wrapKey('raw', aesKey, rsa.publicKey, { name: 'RSA-OAEP' });

// Empfänger entpackt mit dem privaten Schlüssel
const restored = await crypto.subtle.unwrapKey(
  'raw',
  wrapped,
  rsa.privateKey,
  { name: 'RSA-OAEP' },
  { name: 'AES-GCM' },
  false,
  ['encrypt', 'decrypt']
);
console.log(restored.algorithm.name, restored.algorithm.length);

AES-GCM 256

// Wichtig · Fallstricke

Größenlimit: Maximale Klartextlänge = k − 2·hLen − 2 Byte (k = Modulus in Byte, hLen = Hash-Länge). Bei 2048 Bit/SHA-256 sind das 190 Byte. Größere Daten führen zu einem OperationError – für große Daten hybrid mit AES-GCM arbeiten.
Hash gehört zum Schlüssel: Der Hash-Algorithmus wird beim generateKey()/importKey() festgelegt. Ein Schlüssel mit SHA-1 kann nicht mit SHA-256-Geheimtexten anderer Systeme zusammenarbeiten – auf identische Hash-Einstellung achten (z. B. bei Interop mit OpenSSL oder Java, wo oft SHA-1 Standard ist).
Label: Wird bei Ver- und Entschlüsselung ein unterschiedliches (oder einmal gar kein) Label verwendet, schlägt decrypt() ohne nähere Angabe mit OperationError fehl.
Schlüsselnutzung: Der Schlüssel braucht passende keyUsages (encrypt/decrypt bzw. wrapKey/unwrapKey), sonst wird ein InvalidAccessError geworfen.
Sicherer Kontext: crypto.subtle ist nur in HTTPS-Kontexten (bzw. localhost) verfügbar. In allen modernen Browsern unterstützt; in Node.js über globalThis.crypto.subtle bzw. require('node:crypto').webcrypto.
Für neue Anwendungen mindestens 2048 Bit (besser 3072) und SHA-256 verwenden; das ältere RSAES-PKCS1-v1_5 wird von Web Crypto bewusst nicht angeboten.

Siehe auch

RsaPssParams EcdsaParams LaunchParams AesCbcParams AesCtrParams