Signatur
SubtleCrypto.prototype.importKey(format, keyData, algorithm, extractable, keyUsages)
Beschreibung
importKey() wandelt Schlüsselmaterial aus einem portablen Format in ein CryptoKey-Objekt um, das die anderen Methoden der Web Crypto API verwenden können, z. B. encrypt(), sign(), verify() oder deriveKey(). Das Gegenstück ist exportKey().
Unterstützte Formate:
raw: rohe Bytes. Wird für symmetrische Schlüssel (AES, HMAC), öffentliche EC-Schlüssel und als Ausgangsmaterial für PBKDF2/HKDF genutzt.pkcs8: private RSA-, EC- oder Ed25519-Schlüssel in DER-Kodierung (PEM ohne Kopf- und Fußzeile, Base64-dekodiert).spki: öffentliche Schlüssel in DER-Kodierung (SubjectPublicKeyInfo).jwk: JSON Web Key als JavaScript-Objekt, für alle Schlüsseltypen.
Typische Einsatzfälle sind ein öffentlicher Server-Schlüssel, mit dem eine Signatur geprüft werden soll, ein AES-Schlüssel aus einem Schlüsselaustausch oder ein Passwort als Ausgangsmaterial für eine Schlüsselableitung. Mit extractable und keyUsages legst du genau fest, wofür der importierte Schlüssel verwendet werden darf.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $format Pflicht | "raw" | "pkcs8" | "spki" | "jwk" | Format, in dem das Schlüsselmaterial vorliegt. | |
| $keyData Pflicht | ArrayBuffer | TypedArray | DataView | JsonWebKey | Das Schlüsselmaterial. Bei jwk ein Objekt, sonst binäre Daten. |
|
| $algorithm Pflicht | string | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm | Algorithm | Algorithmus des Schlüssels, z. B. { name: "RSA-PSS", hash: "SHA-256" }, { name: "ECDSA", namedCurve: "P-256" }, { name: "HMAC", hash: "SHA-256" }, "AES-GCM" oder "PBKDF2". |
|
| $extractable Pflicht | boolean | Legt fest, ob der Schlüssel später mit exportKey() oder wrapKey() wieder exportiert werden darf. Muss für PBKDF2/HKDF false sein. |
|
| $keyUsages Pflicht | Array<"encrypt" | "decrypt" | "sign" | "verify" | "deriveKey" | "deriveBits" | "wrapKey" | "unwrapKey"> | Erlaubte Verwendungen. Sie müssen zum Algorithmus und zum Schlüsseltyp passen, z. B. verify für einen öffentlichen Signaturschlüssel. |
Rückgabewert
Typ
Promise<CryptoKey>
Beschreibung
Ein Promise, das mit dem importierten
CryptoKey erfüllt wird. Es wird mit einer SyntaxError-DOMException abgelehnt, wenn keyUsages leer oder für den Schlüsseltyp ungültig ist, und mit einem DataError, wenn keyData nicht zum Format passt. Bei nicht unterstützten Formaten oder Algorithmen gibt es einen NotSupportedError, bei keyData vom falschen Typ einen TypeError.Beispiele
AES-GCM-Schlüssel aus rohen Bytes importieren und verschlüsseln
// 256-Bit-Schlüssel, z. B. aus einem Schlüsselaustausch (hier nur Demo-Zufallsbytes)
const rawKey = crypto.getRandomValues(new Uint8Array(32));
const key = await crypto.subtle.importKey(
'raw',
rawKey,
{ name: 'AES-GCM' },
false, // nicht exportierbar
['encrypt', 'decrypt']
);
const iv = crypto.getRandomValues(new Uint8Array(12));
const ciphertext = await crypto.subtle.encrypt(
{ name: 'AES-GCM', iv },
key,
new TextEncoder().encode('Geheime Nachricht')
);
console.log(key.algorithm.name, key.extractable, ciphertext.byteLength);AES-GCM false 33
Öffentlichen RSA-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 = (pem) =>
crypto.subtle.importKey(
'spki',
pemToArrayBuffer(pem),
{ name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
true,
['verify']
);
// Nutzung: Signatur des Servers prüfen
// const publicKey = await importPublicKey(serverPem);
// const ok = await crypto.subtle.verify('RSASSA-PKCS1-v1_5', publicKey, signature, data);HMAC-Schlüssel aus JWK importieren und signieren
const jwk = {
kty: 'oct',
k: 'Y0zt37HgOx-BY7SQjYVmrqhPkO44Ii2Jcb9yydUDPfE',
alg: 'HS256',
ext: true
};
const hmacKey = await crypto.subtle.importKey(
'jwk',
jwk,
{ name: 'HMAC', hash: 'SHA-256' },
false,
['sign', 'verify']
);
const sig = await crypto.subtle.sign('HMAC', hmacKey, new TextEncoder().encode('payload'));
console.log(sig.byteLength);32
Passwort als Ausgangsmaterial für PBKDF2 importieren
const deriveAesKey = async (password, salt) => {
const baseKey = await crypto.subtle.importKey(
'raw',
new TextEncoder().encode(password),
'PBKDF2',
false, // bei PBKDF2 Pflicht
['deriveKey']
);
return crypto.subtle.deriveKey(
{ name: 'PBKDF2', salt, iterations: 600_000, hash: 'SHA-256' },
baseKey,
{ name: 'AES-GCM', length: 256 },
false,
['encrypt', 'decrypt']
);
};
const key = await deriveAesKey('korrekt-pferd-batterie', crypto.getRandomValues(new Uint8Array(16)));
console.log(key.usages);["encrypt", "decrypt"]