EcKeyImportParams — Schnittstelle · JavaScript-Referenz

Signatur

interface EcKeyImportParams extends Algorithm { name: "ECDSA" | "ECDH"; namedCurve: "P-256" | "P-384" | "P-521" }

Beschreibung

EcKeyImportParams ist keine Klasse, sondern ein einfaches Wörterbuch (Dictionary) der Web Crypto API. Man übergibt es als gewöhnliches Objektliteral an crypto.subtle.importKey() oder crypto.subtle.unwrapKey(), wenn ein Schlüssel für elliptische Kurven importiert werden soll, also für die Algorithmen ECDSA (Signaturen) oder ECDH (Schlüsselaustausch).

Das Objekt enthält zwei Angaben: name legt den Algorithmus fest, und namedCurve bestimmt die elliptische Kurve, zu der der Schlüssel gehört. Die Kurve muss zum importierten Schlüsselmaterial passen, sonst bricht der Import mit einem Fehler ab.

Typische Einsatzfälle sind das Prüfen von JWT-Signaturen (ES256/ES384/ES512) mit einem öffentlichen Schlüssel im JWK-Format, das Laden eines öffentlichen Gegenschlüssels für einen ECDH-Austausch oder das Importieren von Schlüsseln im Format spki, pkcs8, raw (nur öffentliche Schlüssel) oder jwk.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des Algorithmus: `"ECDSA"` für Signaturen oder `"ECDH"` für die Ableitung gemeinsamer Schlüssel.
$namedCurve Pflicht	"P-256" \| "P-384" \| "P-521"		Name der elliptischen Kurve (NIST-Kurven). Muss zum Schlüsselmaterial passen, z. B. `crv` in einem JWK.

Rückgabewert

Typ

void

Beschreibung

Ein Wörterbuch liefert selbst keinen Wert. importKey() gibt mit diesem Objekt ein Promise<CryptoKey> zurück.

Beispiele

Öffentlichen ECDSA-Schlüssel (JWK) importieren und Signatur prüfen

const jwk = {
  kty: 'EC',
  crv: 'P-256',
  x: 'f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU',
  y: 'x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0'
};

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

console.log(publicKey.type, publicKey.algorithm);

// Signatur prüfen (signature und data als ArrayBuffer/Uint8Array)
// const ok = await crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, publicKey, signature, data);

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

ECDH: Rohen öffentlichen Schlüssel des Gegenübers importieren

// Eigenes Schlüsselpaar erzeugen
const own = await crypto.subtle.generateKey(
  { name: 'ECDH', namedCurve: 'P-384' },
  true,
  ['deriveKey', 'deriveBits']
);

// Öffentlichen Schlüssel als 'raw' exportieren (simuliert Übertragung)
const rawPeer = await crypto.subtle.exportKey('raw', own.publicKey);

// Beim Empfänger wieder importieren – öffentliche ECDH-Schlüssel haben keine Verwendungen
const peerKey = await crypto.subtle.importKey(
  'raw',
  rawPeer,
  { name: 'ECDH', namedCurve: 'P-384' },
  true,
  []
);

const bits = await crypto.subtle.deriveBits(
  { name: 'ECDH', public: peerKey },
  own.privateKey,
  384
);
console.log(bits.byteLength);

48

Privaten Schlüssel im PKCS#8-Format aus PEM importieren

const pemToArrayBuffer = (pem) => {
  const b64 = pem.replace(/-----[^-]+-----/g, '').replace(/\s+/g, '');
  return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)).buffer;
};

const importPrivateKey = async (pem) =>
  crypto.subtle.importKey(
    'pkcs8',
    pemToArrayBuffer(pem),
    { name: 'ECDSA', namedCurve: 'P-256' },
    false, // nicht exportierbar
    ['sign']
  );

// const key = await importPrivateKey(pemString);

// Wichtig · Fallstricke

Kurve muss passen: Weicht namedCurve von der Kurve im Schlüsselmaterial ab (z. B. crv im JWK), wirft importKey() einen DataError.
Verwendungen (keyUsages): Öffentliche ECDSA-Schlüssel erlauben nur verify, private nur sign. Öffentliche ECDH-Schlüssel müssen mit leerem Array [] importiert werden; private nutzen deriveKey/deriveBits. Falsche Angaben führen zu einem SyntaxError.
Das Format raw ist nur für öffentliche Schlüssel erlaubt (unkomprimierter Punkt, in einigen Browsern auch komprimiert).
Der Hash-Algorithmus gehört nicht in EcKeyImportParams, sondern wird bei ECDSA erst in sign()/verify() über EcdsaParams angegeben.
Für Ed25519/X25519 wird stattdessen nur { name: 'Ed25519' } bzw. { name: 'X25519' } verwendet – ohne namedCurve.
crypto.subtle steht nur in sicheren Kontexten (HTTPS, localhost) zur Verfügung; in Node.js ab Version 15 über globalThis.crypto.subtle bzw. require('node:crypto').webcrypto.
Private Schlüssel möglichst mit extractable: false importieren, damit sie nicht wieder ausgelesen werden können.

Siehe auch

SubtleCrypto.importKey() SubtleCrypto.unwrapKey() EcKeyGenParams EcdsaParams EcKeyImportParams CryptoKey SubtleCrypto