Web Crypto API
[Historie]
| Version | Änderungen |
|---|---|
| v23.5.0 | Die Algorithmen Ed25519 und X25519 sind jetzt stabil. |
| v19.0.0 | Mit Ausnahme der Algorithmen Ed25519, Ed448, X25519 und X448 nicht mehr experimentell. |
| v20.0.0, v18.17.0 | Argumente werden jetzt gemäß ihren WebIDL-Definitionen wie in anderen Web Crypto API-Implementierungen erzwungen und validiert. |
| v18.4.0, v16.17.0 | Proprietäres Import-/Exportformat 'node.keyObject' entfernt. |
| v18.4.0, v16.17.0 | Proprietäre Algorithmen 'NODE-DSA', 'NODE-DH' und 'NODE-SCRYPT' entfernt. |
| v18.4.0, v16.17.0 | Algorithmen 'Ed25519', 'Ed448', 'X25519' und 'X448' hinzugefügt. |
| v18.4.0, v16.17.0 | Proprietäre Algorithmen 'NODE-ED25519' und 'NODE-ED448' entfernt. |
| v18.4.0, v16.17.0 | Proprietäre benannte Kurven 'NODE-X25519' und 'NODE-X448' aus dem Algorithmus 'ECDH' entfernt. |
[Stabil: 2 - Stabil]
Stabil: 2 Stabilität: 2 - Stabil
Node.js bietet eine Implementierung der Standard Web Crypto API.
Verwenden Sie globalThis.crypto oder require('node:crypto').webcrypto, um auf dieses Modul zuzugreifen.
const { subtle } = globalThis.crypto;
(async function() {
const key = await subtle.generateKey({
name: 'HMAC',
hash: 'SHA-256',
length: 256,
}, true, ['sign', 'verify']);
const enc = new TextEncoder();
const message = enc.encode('I love cupcakes');
const digest = await subtle.sign({
name: 'HMAC',
}, key, message);
})();Beispiele
Schlüssel generieren
Die Klasse <SubtleCrypto> kann verwendet werden, um symmetrische (geheime) Schlüssel oder asymmetrische Schlüsselpaare (öffentlicher Schlüssel und privater Schlüssel) zu generieren.
AES-Schlüssel
const { subtle } = globalThis.crypto;
async function generateAesKey(length = 256) {
const key = await subtle.generateKey({
name: 'AES-CBC',
length,
}, true, ['encrypt', 'decrypt']);
return key;
}ECDSA-Schlüsselpaare
const { subtle } = globalThis.crypto;
async function generateEcKey(namedCurve = 'P-521') {
const {
publicKey,
privateKey,
} = await subtle.generateKey({
name: 'ECDSA',
namedCurve,
}, true, ['sign', 'verify']);
return { publicKey, privateKey };
}Ed25519/X25519-Schlüsselpaare
const { subtle } = globalThis.crypto;
async function generateEd25519Key() {
return subtle.generateKey({
name: 'Ed25519',
}, true, ['sign', 'verify']);
}
async function generateX25519Key() {
return subtle.generateKey({
name: 'X25519',
}, true, ['deriveKey']);
}HMAC-Schlüssel
const { subtle } = globalThis.crypto;
async function generateHmacKey(hash = 'SHA-256') {
const key = await subtle.generateKey({
name: 'HMAC',
hash,
}, true, ['sign', 'verify']);
return key;
}RSA-Schlüsselpaare
const { subtle } = globalThis.crypto;
const publicExponent = new Uint8Array([1, 0, 1]);
async function generateRsaKey(modulusLength = 2048, hash = 'SHA-256') {
const {
publicKey,
privateKey,
} = await subtle.generateKey({
name: 'RSASSA-PKCS1-v1_5',
modulusLength,
publicExponent,
hash,
}, true, ['sign', 'verify']);
return { publicKey, privateKey };
}Verschlüsselung und Entschlüsselung
const crypto = globalThis.crypto;
async function aesEncrypt(plaintext) {
const ec = new TextEncoder();
const key = await generateAesKey();
const iv = crypto.getRandomValues(new Uint8Array(16));
const ciphertext = await crypto.subtle.encrypt({
name: 'AES-CBC',
iv,
}, key, ec.encode(plaintext));
return {
key,
iv,
ciphertext,
};
}
async function aesDecrypt(ciphertext, key, iv) {
const dec = new TextDecoder();
const plaintext = await crypto.subtle.decrypt({
name: 'AES-CBC',
iv,
}, key, ciphertext);
return dec.decode(plaintext);
}Exportieren und Importieren von Schlüsseln
const { subtle } = globalThis.crypto;
async function generateAndExportHmacKey(format = 'jwk', hash = 'SHA-512') {
const key = await subtle.generateKey({
name: 'HMAC',
hash,
}, true, ['sign', 'verify']);
return subtle.exportKey(format, key);
}
async function importHmacKey(keyData, format = 'jwk', hash = 'SHA-512') {
const key = await subtle.importKey(format, keyData, {
name: 'HMAC',
hash,
}, true, ['sign', 'verify']);
return key;
}Schlüssel einwickeln und auspacken
const { subtle } = globalThis.crypto;
async function generateAndWrapHmacKey(format = 'jwk', hash = 'SHA-512') {
const [
key,
wrappingKey,
] = await Promise.all([
subtle.generateKey({
name: 'HMAC', hash,
}, true, ['sign', 'verify']),
subtle.generateKey({
name: 'AES-KW',
length: 256,
}, true, ['wrapKey', 'unwrapKey']),
]);
const wrappedKey = await subtle.wrapKey(format, key, wrappingKey, 'AES-KW');
return { wrappedKey, wrappingKey };
}
async function unwrapHmacKey(
wrappedKey,
wrappingKey,
format = 'jwk',
hash = 'SHA-512') {
const key = await subtle.unwrapKey(
format,
wrappedKey,
wrappingKey,
'AES-KW',
{ name: 'HMAC', hash },
true,
['sign', 'verify']);
return key;
}Signieren und verifizieren
const { subtle } = globalThis.crypto;
async function sign(key, data) {
const ec = new TextEncoder();
const signature =
await subtle.sign('RSASSA-PKCS1-v1_5', key, ec.encode(data));
return signature;
}
async function verify(key, signature, data) {
const ec = new TextEncoder();
const verified =
await subtle.verify(
'RSASSA-PKCS1-v1_5',
key,
signature,
ec.encode(data));
return verified;
}Ableiten von Bits und Schlüsseln
const { subtle } = globalThis.crypto;
async function pbkdf2(pass, salt, iterations = 1000, length = 256) {
const ec = new TextEncoder();
const key = await subtle.importKey(
'raw',
ec.encode(pass),
'PBKDF2',
false,
['deriveBits']);
const bits = await subtle.deriveBits({
name: 'PBKDF2',
hash: 'SHA-512',
salt: ec.encode(salt),
iterations,
}, key, length);
return bits;
}
async function pbkdf2Key(pass, salt, iterations = 1000, length = 256) {
const ec = new TextEncoder();
const keyMaterial = await subtle.importKey(
'raw',
ec.encode(pass),
'PBKDF2',
false,
['deriveKey']);
const key = await subtle.deriveKey({
name: 'PBKDF2',
hash: 'SHA-512',
salt: ec.encode(salt),
iterations,
}, keyMaterial, {
name: 'AES-GCM',
length,
}, true, ['encrypt', 'decrypt']);
return key;
}Digest
const { subtle } = globalThis.crypto;
async function digest(data, algorithm = 'SHA-512') {
const ec = new TextEncoder();
const digest = await subtle.digest(algorithm, ec.encode(data));
return digest;
}Algorithm Matrix
Die Tabelle listet die von der Node.js Web Crypto API-Implementierung unterstützten Algorithmen und die für jeden unterstützten APIs auf:
| Algorithmus | generateKey | exportKey | importKey | encrypt | decrypt | wrapKey | unwrapKey | deriveBits | deriveKey | sign | verify | digest |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
'RSASSA-PKCS1-v1_5' | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
'RSA-PSS' | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
'RSA-OAEP' | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
'ECDSA' | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
'Ed25519' | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
'Ed448' | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
'ECDH' | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
'X25519' | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
'X448' | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
'AES-CTR' | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
'AES-CBC' | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
'AES-GCM' | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |||||
'AES-KW' | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
'HMAC' | ✔ | ✔ | ✔ | ✔ | ✔ | |||||||
'HKDF' | ✔ | ✔ | ✔ | ✔ | ||||||||
'PBKDF2' | ✔ | ✔ | ✔ | ✔ | ||||||||
'SHA-1' | ✔ | |||||||||||
'SHA-256' | ✔ | |||||||||||
'SHA-384' | ✔ | |||||||||||
'SHA-512' | ✔ |
Klasse: Crypto
Hinzugefügt in: v15.0.0
globalThis.crypto ist eine Instanz der Klasse Crypto. Crypto ist ein Singleton, das Zugriff auf den Rest der Crypto-API bietet.
crypto.subtle
Hinzugefügt in: v15.0.0
- Typ: <SubtleCrypto>
Bietet Zugriff auf die SubtleCrypto-API.
crypto.getRandomValues(typedArray)
Hinzugefügt in: v15.0.0
typedArray<Buffer> | <TypedArray>- Gibt zurück: <Buffer> | <TypedArray>
Generiert kryptografisch starke Zufallswerte. Das gegebene typedArray wird mit Zufallswerten gefüllt, und eine Referenz auf typedArray wird zurückgegeben.
Das gegebene typedArray muss eine Integer-basierte Instanz von <TypedArray> sein, d. h. Float32Array und Float64Array werden nicht akzeptiert.
Ein Fehler wird ausgelöst, wenn das gegebene typedArray größer als 65.536 Bytes ist.
crypto.randomUUID()
Hinzugefügt in: v16.7.0
- Gibt zurück: <string>
Generiert eine zufällige RFC 4122 Version 4 UUID. Die UUID wird mit einem kryptografischen Pseudozufallszahlengenerator erzeugt.
Klasse: CryptoKey
Hinzugefügt in: v15.0.0
cryptoKey.algorithm
Hinzugefügt in: v15.0.0
Ein Objekt, das den Algorithmus beschreibt, für den der Schlüssel verwendet werden kann, zusammen mit zusätzlichen algorithmusspezifischen Parametern.
Schreibgeschützt.
cryptoKey.extractable
Hinzugefügt in: v15.0.0
- Typ: <boolean>
Wenn true, kann der <CryptoKey> entweder mit subtleCrypto.exportKey() oder subtleCrypto.wrapKey() extrahiert werden.
Schreibgeschützt.
cryptoKey.type
Hinzugefügt in: v15.0.0
- Typ: <string> Einer von
'secret','private'oder'public'.
Eine Zeichenkette, die angibt, ob es sich bei dem Schlüssel um einen symmetrischen ('secret') oder asymmetrischen ('private' oder 'public') Schlüssel handelt.
cryptoKey.usages
Hinzugefügt in: v15.0.0
- Typ: <string[]>
Ein Array von Zeichenketten, die die Operationen identifizieren, für die der Schlüssel verwendet werden darf.
Die möglichen Verwendungen sind:
'encrypt'- Der Schlüssel darf zum Verschlüsseln von Daten verwendet werden.'decrypt'- Der Schlüssel darf zum Entschlüsseln von Daten verwendet werden.'sign'- Der Schlüssel darf zum Erzeugen digitaler Signaturen verwendet werden.'verify'- Der Schlüssel darf zum Verifizieren digitaler Signaturen verwendet werden.'deriveKey'- Der Schlüssel darf zum Ableiten eines neuen Schlüssels verwendet werden.'deriveBits'- Der Schlüssel darf zum Ableiten von Bits verwendet werden.'wrapKey'- Der Schlüssel darf zum Umhüllen eines anderen Schlüssels verwendet werden.'unwrapKey'- Der Schlüssel darf zum Entpacken eines anderen Schlüssels verwendet werden.
Gültige Schlüsselverwendungen hängen vom Schlüsselalgorithmus ab (identifiziert durch cryptokey.algorithm.name).
| Schlüsseltyp | 'encrypt' | 'decrypt' | 'sign' | 'verify' | 'deriveKey' | 'deriveBits' | 'wrapKey' | 'unwrapKey' |
|---|---|---|---|---|---|---|---|---|
'AES-CBC' | ✔ | ✔ | ✔ | ✔ | ||||
'AES-CTR' | ✔ | ✔ | ✔ | ✔ | ||||
'AES-GCM' | ✔ | ✔ | ✔ | ✔ | ||||
'AES-KW' | ✔ | ✔ | ||||||
'ECDH' | ✔ | ✔ | ||||||
'X25519' | ✔ | ✔ | ||||||
'X448' | ✔ | ✔ | ||||||
'ECDSA' | ✔ | ✔ | ||||||
'Ed25519' | ✔ | ✔ | ||||||
'Ed448' | ✔ | ✔ | ||||||
'HDKF' | ✔ | ✔ | ||||||
'HMAC' | ✔ | ✔ | ||||||
'PBKDF2' | ✔ | ✔ | ||||||
'RSA-OAEP' | ✔ | ✔ | ✔ | ✔ | ||||
'RSA-PSS' | ✔ | ✔ | ||||||
'RSASSA-PKCS1-v1_5' | ✔ | ✔ |
Klasse: CryptoKeyPair
Hinzugefügt in: v15.0.0
CryptoKeyPair ist ein einfaches Dictionary-Objekt mit den Eigenschaften publicKey und privateKey, das ein asymmetrisches Schlüsselpaar darstellt.
cryptoKeyPair.privateKey
Hinzugefügt in: v15.0.0
- Typ: <CryptoKey> Ein <CryptoKey>, dessen
type'private'ist.
cryptoKeyPair.publicKey
Hinzugefügt in: v15.0.0
- Typ: <CryptoKey> Ein <CryptoKey>, dessen
type'public'ist.
Klasse: SubtleCrypto
Hinzugefügt in: v15.0.0
subtle.decrypt(algorithm, key, data)
Hinzugefügt in: v15.0.0
algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>key: <CryptoKey>data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>- Gibt zurück: <Promise> Wird mit einem <ArrayBuffer> erfüllt.
Unter Verwendung der in algorithm angegebenen Methode und Parameter sowie des von key bereitgestellten Schlüsselmaterials versucht subtle.decrypt() die bereitgestellten data zu entschlüsseln. Wenn dies erfolgreich ist, wird das zurückgegebene Promise mit einem <ArrayBuffer> aufgelöst, das das Klartext-Ergebnis enthält.
Die aktuell unterstützten Algorithmen umfassen:
'RSA-OAEP''AES-CTR''AES-CBC''AES-GCM'
subtle.deriveBits(algorithm, baseKey[, length])
[Verlauf]
| Version | Änderungen |
|---|---|
| v22.5.0, v20.17.0 | Der Parameter length ist jetzt optional für 'ECDH', 'X25519' und 'X448'. |
| v18.4.0, v16.17.0 | Die Algorithmen 'X25519' und 'X448' wurden hinzugefügt. |
| v15.0.0 | Hinzugefügt in: v15.0.0 |
algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>baseKey: <CryptoKey>length: <number> | <null> Standard:null- Rückgabe: <Promise> Wird mit einem <ArrayBuffer> erfüllt
Mithilfe der in algorithm angegebenen Methode und Parameter sowie des von baseKey bereitgestellten Schlüsselmaterials versucht subtle.deriveBits() length Bits zu generieren.
Wenn length nicht angegeben oder null ist, wird die maximale Anzahl von Bits für einen bestimmten Algorithmus generiert. Dies ist für die Algorithmen 'ECDH', 'X25519' und 'X448' zulässig. Für andere Algorithmen muss length eine Zahl sein.
Wenn der Vorgang erfolgreich ist, wird die zurückgegebene Promise mit einem <ArrayBuffer> aufgelöst, das die generierten Daten enthält.
Die aktuell unterstützten Algorithmen umfassen:
'ECDH''X25519''X448''HKDF''PBKDF2'
subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)
[Verlauf]
| Version | Änderungen |
|---|---|
| v18.4.0, v16.17.0 | Die Algorithmen 'X25519' und 'X448' wurden hinzugefügt. |
| v15.0.0 | Hinzugefügt in: v15.0.0 |
algorithm: <AlgorithmIdentifier> | <EcdhKeyDeriveParams> | <HkdfParams> | <Pbkdf2Params>baseKey: <CryptoKey>derivedKeyAlgorithm: <HmacKeyGenParams> | <AesKeyGenParams>extractable: <boolean>keyUsages: <string[]> Siehe Key usages.- Rückgabe: <Promise> Wird mit einem <CryptoKey> erfüllt
Mithilfe der in algorithm angegebenen Methode und Parameter sowie des von baseKey bereitgestellten Schlüsselmaterials versucht subtle.deriveKey() einen neuen <CryptoKey> basierend auf der Methode und den Parametern in derivedKeyAlgorithm zu generieren.
Der Aufruf von subtle.deriveKey() entspricht dem Aufruf von subtle.deriveBits(), um rohes Schlüsselmaterial zu generieren, und der anschließenden Übergabe des Ergebnisses an die Methode subtle.importKey() unter Verwendung der Parameter deriveKeyAlgorithm, extractable und keyUsages als Eingabe.
Die aktuell unterstützten Algorithmen umfassen:
'ECDH''X25519''X448''HKDF''PBKDF2'
subtle.digest(algorithm, data)
Hinzugefügt in: v15.0.0
algorithm: <string> | <Object>data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>- Gibt zurück: <Promise> Wird mit einem <ArrayBuffer> erfüllt
Mit der durch algorithm identifizierten Methode versucht subtle.digest() einen Hash von data zu generieren. Bei Erfolg wird das zurückgegebene Promise mit einem <ArrayBuffer> aufgelöst, das den berechneten Hash enthält.
Wenn algorithm als <string> bereitgestellt wird, muss es eines der Folgenden sein:
'SHA-1''SHA-256''SHA-384''SHA-512'
Wenn algorithm als <Object> bereitgestellt wird, muss es eine name-Eigenschaft haben, deren Wert einer der oben genannten ist.
subtle.encrypt(algorithm, key, data)
Hinzugefügt in: v15.0.0
algorithm: <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>key: <CryptoKey>data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>- Gibt zurück: <Promise> Wird mit einem <ArrayBuffer> erfüllt
Mit der durch algorithm angegebenen Methode und Parametern und dem durch key bereitgestellten Schlüsselmaterial versucht subtle.encrypt() data zu verschlüsseln. Bei Erfolg wird das zurückgegebene Promise mit einem <ArrayBuffer> aufgelöst, das das verschlüsselte Ergebnis enthält.
Die derzeit unterstützten Algorithmen umfassen:
'RSA-OAEP''AES-CTR''AES-CBC''AES-GCM'
subtle.exportKey(format, key)
[Verlauf]
| Version | Änderungen |
|---|---|
| v18.4.0, v16.17.0 | Algorithmen 'Ed25519', 'Ed448', 'X25519' und 'X448' hinzugefügt. |
| v15.9.0 | 'NODE-DSA' JWK-Export entfernt. |
| v15.0.0 | Hinzugefügt in: v15.0.0 |
format: <string> Muss einer von'raw','pkcs8','spki'oder'jwk'sein.key: <CryptoKey>- Gibt zurück: <Promise> Wird mit einem <ArrayBuffer> | <Object> erfüllt.
Exportiert den gegebenen Schlüssel in das angegebene Format, falls unterstützt.
Wenn der <CryptoKey> nicht extrahierbar ist, wird das zurückgegebene Promise abgelehnt.
Wenn format entweder 'pkcs8' oder 'spki' ist und der Export erfolgreich ist, wird das zurückgegebene Promise mit einem <ArrayBuffer> aufgelöst, das die exportierten Schlüsseldaten enthält.
Wenn format 'jwk' ist und der Export erfolgreich ist, wird das zurückgegebene Promise mit einem JavaScript-Objekt aufgelöst, das der JSON Web Key-Spezifikation entspricht.
| Schlüsseltyp | 'spki' | 'pkcs8' | 'jwk' | 'raw' |
|---|---|---|---|---|
'AES-CBC' | ✔ | ✔ | ||
'AES-CTR' | ✔ | ✔ | ||
'AES-GCM' | ✔ | ✔ | ||
'AES-KW' | ✔ | ✔ | ||
'ECDH' | ✔ | ✔ | ✔ | ✔ |
'ECDSA' | ✔ | ✔ | ✔ | ✔ |
'Ed25519' | ✔ | ✔ | ✔ | ✔ |
'Ed448' | ✔ | ✔ | ✔ | ✔ |
'HDKF' | ||||
'HMAC' | ✔ | ✔ | ||
'PBKDF2' | ||||
'RSA-OAEP' | ✔ | ✔ | ✔ | |
'RSA-PSS' | ✔ | ✔ | ✔ | |
'RSASSA-PKCS1-v1_5' | ✔ | ✔ | ✔ |
subtle.generateKey(algorithm, extractable, keyUsages)
Hinzugefügt in: v15.0.0
algorithm: <AlgorithmIdentifier> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams> | <AesKeyGenParams>extractable: <boolean>keyUsages: <string[]> Siehe Key usages.Gibt zurück: <Promise> Wird mit einem <CryptoKey> | <CryptoKeyPair> erfüllt.
Mit der in algorithm bereitgestellten Methode und den Parametern versucht subtle.generateKey(), neues Schlüsselmaterial zu generieren. Abhängig von der verwendeten Methode kann die Methode entweder einen einzelnen <CryptoKey> oder ein <CryptoKeyPair> generieren.
Die unterstützten Algorithmen zur Generierung von <CryptoKeyPair> (öffentlicher und privater Schlüssel) sind:
'RSASSA-PKCS1-v1_5''RSA-PSS''RSA-OAEP''ECDSA''Ed25519''Ed448''ECDH''X25519''X448'
Die unterstützten Algorithmen zur Generierung von <CryptoKey> (geheimer Schlüssel) sind:
'HMAC''AES-CTR''AES-CBC''AES-GCM''AES-KW'
subtle.importKey(format, keyData, algorithm, extractable, keyUsages)
[Historie]
| Version | Änderungen |
|---|---|
| v18.4.0, v16.17.0 | Die Algorithmen 'Ed25519', 'Ed448', 'X25519' und 'X448' wurden hinzugefügt. |
| v15.9.0 | Der JWK-Import von 'NODE-DSA' wurde entfernt. |
| v15.0.0 | Hinzugefügt in: v15.0.0 |
format: <string> Muss einer von'raw','pkcs8','spki'oder'jwk'sein.keyData: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <Object>algorithm: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>extractable: <boolean>keyUsages: <string[]> Siehe Key usages.Gibt zurück: <Promise> Wird mit einem <CryptoKey> erfüllt.
Die Methode subtle.importKey() versucht, die bereitgestellten keyData als das gegebene format zu interpretieren, um eine <CryptoKey>-Instanz unter Verwendung der bereitgestellten Argumente algorithm, extractable und keyUsages zu erstellen. Wenn der Import erfolgreich ist, wird die zurückgegebene Promise mit dem erstellten <CryptoKey> aufgelöst.
Beim Importieren eines 'PBKDF2'-Schlüssels muss extractable false sein.
Die derzeit unterstützten Algorithmen umfassen:
| Schlüsseltyp | 'spki' | 'pkcs8' | 'jwk' | 'raw' |
|---|---|---|---|---|
'AES-CBC' | ✔ | ✔ | ||
'AES-CTR' | ✔ | ✔ | ||
'AES-GCM' | ✔ | ✔ | ||
'AES-KW' | ✔ | ✔ | ||
'ECDH' | ✔ | ✔ | ✔ | ✔ |
'X25519' | ✔ | ✔ | ✔ | ✔ |
'X448' | ✔ | ✔ | ✔ | ✔ |
'ECDSA' | ✔ | ✔ | ✔ | ✔ |
'Ed25519' | ✔ | ✔ | ✔ | ✔ |
'Ed448' | ✔ | ✔ | ✔ | ✔ |
'HDKF' | ✔ | |||
'HMAC' | ✔ | ✔ | ||
'PBKDF2' | ✔ | |||
'RSA-OAEP' | ✔ | ✔ | ✔ | |
'RSA-PSS' | ✔ | ✔ | ✔ | |
'RSASSA-PKCS1-v1_5' | ✔ | ✔ | ✔ |
subtle.sign(algorithm, key, data)
[Verlauf]
| Version | Änderungen |
|---|---|
| v18.4.0, v16.17.0 | Die Algorithmen 'Ed25519' und 'Ed448' wurden hinzugefügt. |
| v15.0.0 | Hinzugefügt in: v15.0.0 |
algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>key: <CryptoKey>data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>- Gibt zurück: <Promise> Wird mit einem <ArrayBuffer> erfüllt, das die generierte Signatur enthält.
Mithilfe der Methode und der Parameter, die von algorithm angegeben werden, und des Schlüsselmaterials, das von key bereitgestellt wird, versucht subtle.sign() eine kryptografische Signatur von data zu generieren. Wenn dies erfolgreich ist, wird das zurückgegebene Promise mit einem <ArrayBuffer> aufgelöst, das die generierte Signatur enthält.
Die derzeit unterstützten Algorithmen umfassen:
'RSASSA-PKCS1-v1_5''RSA-PSS''ECDSA''Ed25519''Ed448''HMAC'
subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages)
Hinzugefügt in: v15.0.0
format: <string> Muss einer von'raw','pkcs8','spki'oder'jwk'sein.wrappedKey: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>unwrappingKey: <CryptoKey>unwrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>unwrappedKeyAlgo: <AlgorithmIdentifier> | <RsaHashedImportParams> | <EcKeyImportParams> | <HmacImportParams>extractable: <boolean>keyUsages: <string[]> Siehe Key usages.Gibt zurück: <Promise> Wird mit einem <CryptoKey> erfüllt.
In der Kryptografie bezieht sich das "Verpacken eines Schlüssels" auf das Exportieren und anschließende Verschlüsseln des Schlüsselmaterials. Die Methode subtle.unwrapKey() versucht, einen verpackten Schlüssel zu entschlüsseln und eine <CryptoKey>-Instanz zu erstellen. Dies entspricht dem Aufruf von subtle.decrypt() zuerst auf den verschlüsselten Schlüsseldaten (unter Verwendung der Argumente wrappedKey, unwrapAlgo und unwrappingKey als Eingabe) und dem anschließenden Übergeben der Ergebnisse an die Methode subtle.importKey() unter Verwendung der Argumente unwrappedKeyAlgo, extractable und keyUsages als Eingaben. Wenn dies erfolgreich ist, wird das zurückgegebene Promise mit einem <CryptoKey>-Objekt aufgelöst.
Die derzeit unterstützten Verpackungsalgorithmen umfassen:
'RSA-OAEP''AES-CTR''AES-CBC''AES-GCM''AES-KW'
Die unterstützten Algorithmen für entpackte Schlüssel umfassen:
'RSASSA-PKCS1-v1_5''RSA-PSS''RSA-OAEP''ECDSA''Ed25519''Ed448''ECDH''X25519''X448''HMAC''AES-CTR''AES-CBC''AES-GCM''AES-KW'
subtle.verify(algorithm, key, signature, data)
[Historie]
| Version | Änderungen |
|---|---|
| v18.4.0, v16.17.0 | 'Ed25519' und 'Ed448' Algorithmen hinzugefügt. |
| v15.0.0 | Hinzugefügt in: v15.0.0 |
algorithm: <AlgorithmIdentifier> | <RsaPssParams> | <EcdsaParams> | <Ed448Params>key: <CryptoKey>signature: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>data: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>- Gibt zurück: <Promise> Wird mit einem <boolean> erfüllt
Mit der in algorithm angegebenen Methode und Parametern sowie dem von key bereitgestellten Schlüsselmaterial versucht subtle.verify() zu überprüfen, ob signature eine gültige kryptografische Signatur von data ist. Das zurückgegebene Promise wird entweder mit true oder false aufgelöst.
Die derzeit unterstützten Algorithmen umfassen:
'RSASSA-PKCS1-v1_5''RSA-PSS''ECDSA''Ed25519''Ed448''HMAC'
subtle.wrapKey(format, key, wrappingKey, wrapAlgo)
Hinzugefügt in: v15.0.0
format: <string> Muss einer von'raw','pkcs8','spki'oder'jwk'sein.key: <CryptoKey>wrappingKey: <CryptoKey>wrapAlgo: <AlgorithmIdentifier> | <RsaOaepParams> | <AesCtrParams> | <AesCbcParams> | <AesGcmParams>- Gibt zurück: <Promise> Wird mit einem <ArrayBuffer> erfüllt
In der Kryptographie bezieht sich "Einhüllen eines Schlüssels" auf das Exportieren und anschließende Verschlüsseln des Schlüsselmaterials. Die Methode subtle.wrapKey() exportiert das Schlüsselmaterial in das durch format identifizierte Format und verschlüsselt es anschließend mit der durch wrapAlgo angegebenen Methode und den Parametern sowie dem von wrappingKey bereitgestellten Schlüsselmaterial. Sie entspricht dem Aufruf von subtle.exportKey() mit format und key als Argumente und dem anschließenden Übergeben des Ergebnisses an die Methode subtle.encrypt() mit wrappingKey und wrapAlgo als Eingaben. Wenn erfolgreich, wird das zurückgegebene Promise mit einem <ArrayBuffer> aufgelöst, das die verschlüsselten Schlüsseldaten enthält.
Die derzeit unterstützten Wrapping-Algorithmen umfassen:
'RSA-OAEP''AES-CTR''AES-CBC''AES-GCM''AES-KW'
Algorithmparameter
Die Algorithmusparameter-Objekte definieren die Methoden und Parameter, die von den verschiedenen <SubtleCrypto>-Methoden verwendet werden. Obwohl sie hier als "Klassen" beschrieben werden, sind sie einfache JavaScript-Dictionary-Objekte.
Klasse: AlgorithmIdentifier
Hinzugefügt in: v18.4.0, v16.17.0
algorithmIdentifier.name
Hinzugefügt in: v18.4.0, v16.17.0
- Typ: <string>
Klasse: AesCbcParams
Hinzugefügt in: v15.0.0
aesCbcParams.iv
Hinzugefügt in: v15.0.0
- Typ: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Stellt den Initialisierungsvektor bereit. Er muss genau 16 Byte lang sein und sollte unvorhersehbar und kryptografisch zufällig sein.
aesCbcParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss
'AES-CBC'sein.
Klasse: AesCtrParams
Hinzugefügt in: v15.0.0
aesCtrParams.counter
Hinzugefügt in: v15.0.0
- Typ: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Der Anfangswert des Zählerblocks. Dieser muss genau 16 Byte lang sein.
Die AES-CTR-Methode verwendet die rechtesten length-Bits des Blocks als Zähler und die verbleibenden Bits als Nonce.
aesCtrParams.length
Hinzugefügt in: v15.0.0
- Typ: <number> Die Anzahl der Bits in
aesCtrParams.counter, die als Zähler verwendet werden sollen.
aesCtrParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss
'AES-CTR'sein.
Klasse: AesGcmParams
Hinzugefügt in: v15.0.0
aesGcmParams.additionalData
Hinzugefügt in: v15.0.0
- Typ: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>
Bei der AES-GCM-Methode sind die additionalData zusätzliche Eingaben, die nicht verschlüsselt werden, aber in die Authentifizierung der Daten einbezogen werden. Die Verwendung von additionalData ist optional.
aesGcmParams.iv
Hinzugefügt in: v15.0.0
- Typ: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Der Initialisierungsvektor muss für jede Verschlüsselungsoperation mit einem bestimmten Schlüssel eindeutig sein.
Idealerweise ist dies ein deterministischer 12-Byte-Wert, der so berechnet wird, dass seine Eindeutigkeit über alle Aufrufe hinweg gewährleistet ist, die denselben Schlüssel verwenden. Alternativ kann der Initialisierungsvektor aus mindestens 12 kryptografisch zufälligen Bytes bestehen. Weitere Informationen zum Erstellen von Initialisierungsvektoren für AES-GCM finden Sie in Abschnitt 8 von NIST SP 800-38D.
aesGcmParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss
'AES-GCM'sein.
aesGcmParams.tagLength
Hinzugefügt in: v15.0.0
- Typ: <number> Die Größe des generierten Authentifizierungs-Tags in Bits. Dieser Wert muss einer von
32,64,96,104,112,120oder128sein. Standard:128.
Klasse: AesKeyGenParams
Hinzugefügt in: v15.0.0
aesKeyGenParams.length
Hinzugefügt in: v15.0.0
- Typ: <number>
Die Länge des zu generierenden AES-Schlüssels. Dies muss entweder 128, 192 oder 256 sein.
aesKeyGenParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss einer von
'AES-CBC','AES-CTR','AES-GCM'oder'AES-KW'sein.
Klasse: EcdhKeyDeriveParams
Hinzugefügt in: v15.0.0
ecdhKeyDeriveParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss
'ECDH','X25519'oder'X448'sein.
ecdhKeyDeriveParams.public
Hinzugefügt in: v15.0.0
- Typ: <CryptoKey>
Die ECDH-Schlüsselableitung funktioniert, indem der private Schlüssel einer Partei und der öffentliche Schlüssel einer anderen Partei als Eingabe verwendet werden – wobei beide verwendet werden, um ein gemeinsames Shared Secret zu generieren. Die Eigenschaft ecdhKeyDeriveParams.public wird auf den öffentlichen Schlüssel der anderen Partei gesetzt.
Klasse: EcdsaParams
Hinzugefügt in: v15.0.0
ecdsaParams.hash
Hinzugefügt in: v15.0.0
Wenn als <string> dargestellt, muss der Wert einer der folgenden sein:
'SHA-1''SHA-256''SHA-384''SHA-512'
Wenn als <Object> dargestellt, muss das Objekt eine name-Eigenschaft haben, deren Wert einer der oben aufgeführten Werte ist.
ecdsaParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss
'ECDSA'sein.
Klasse: EcKeyGenParams
Hinzugefügt in: v15.0.0
ecKeyGenParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss entweder
'ECDSA'oder'ECDH'sein.
ecKeyGenParams.namedCurve
Hinzugefügt in: v15.0.0
- Typ: <string> Muss entweder
'P-256','P-384'oder'P-521'sein.
Klasse: EcKeyImportParams
Hinzugefügt in: v15.0.0
ecKeyImportParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss entweder
'ECDSA'oder'ECDH'sein.
ecKeyImportParams.namedCurve
Hinzugefügt in: v15.0.0
- Typ: <string> Muss entweder
'P-256','P-384'oder'P-521'sein.
Klasse: Ed448Params
Hinzugefügt in: v15.0.0
ed448Params.name
Hinzugefügt in: v18.4.0, v16.17.0
- Typ: <string> Muss
'Ed448'sein.
ed448Params.context
Hinzugefügt in: v18.4.0, v16.17.0
- Typ: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer> | <undefined>
Das context-Element repräsentiert die optionalen Kontextdaten, die der Nachricht zugeordnet werden sollen. Die Node.js Web Crypto API-Implementierung unterstützt nur Kontext mit der Länge Null, was dem Fehlen von Kontext gleichkommt.
Klasse: HkdfParams
Hinzugefügt in: v15.0.0
hkdfParams.hash
Hinzugefügt in: v15.0.0
Wenn als <string> dargestellt, muss der Wert einer der folgenden sein:
'SHA-1''SHA-256''SHA-384''SHA-512'
Wenn als <Object> dargestellt, muss das Objekt eine name-Eigenschaft haben, deren Wert einer der oben aufgeführten Werte ist.
hkdfParams.info
Hinzugefügt in: v15.0.0
- Typ: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Bietet anwendungsspezifische kontextbezogene Eingaben für den HKDF-Algorithmus. Dies kann eine Länge von Null haben, muss aber angegeben werden.
hkdfParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss
'HKDF'sein.
hkdfParams.salt
Hinzugefügt in: v15.0.0
- Typ: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Der Salt-Wert verbessert die Stärke des HKDF-Algorithmus erheblich. Er sollte zufällig oder pseudozufällig sein und die gleiche Länge wie die Ausgabe der Digest-Funktion haben (wenn beispielsweise 'SHA-256' als Digest verwendet wird, sollte der Salt 256 Bit an Zufallsdaten sein).
Klasse: HmacImportParams
Hinzugefügt in: v15.0.0
hmacImportParams.hash
Hinzugefügt in: v15.0.0
Wenn als <string> dargestellt, muss der Wert einer der folgenden sein:
'SHA-1''SHA-256''SHA-384''SHA-512'
Wenn als <Object> dargestellt, muss das Objekt eine name-Eigenschaft haben, deren Wert einer der oben aufgeführten Werte ist.
hmacImportParams.length
Hinzugefügt in: v15.0.0
- Typ: <number>
Die optionale Anzahl von Bits im HMAC-Schlüssel. Dies ist optional und sollte in den meisten Fällen weggelassen werden.
hmacImportParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss
'HMAC'sein.
Klasse: HmacKeyGenParams
Hinzugefügt in: v15.0.0
hmacKeyGenParams.hash
Hinzugefügt in: v15.0.0
Wenn als <string> dargestellt, muss der Wert einer der folgenden sein:
'SHA-1''SHA-256''SHA-384''SHA-512'
Wenn als <Object> dargestellt, muss das Objekt eine name-Eigenschaft haben, deren Wert einer der oben aufgeführten Werte ist.
hmacKeyGenParams.length
Hinzugefügt in: v15.0.0
- Typ: <number>
Die Anzahl der Bits, die für den HMAC-Schlüssel generiert werden sollen. Wenn ausgelassen, wird die Länge durch den verwendeten Hash-Algorithmus bestimmt. Dies ist optional und sollte in den meisten Fällen weggelassen werden.
hmacKeyGenParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss
'HMAC'sein.
Klasse: Pbkdf2Params
Hinzugefügt in: v15.0.0
pbkdb2Params.hash
Hinzugefügt in: v15.0.0
Wenn als <string> dargestellt, muss der Wert einer der folgenden sein:
'SHA-1''SHA-256''SHA-384''SHA-512'
Wenn als <Object> dargestellt, muss das Objekt eine name-Eigenschaft haben, deren Wert einer der oben aufgeführten Werte ist.
pbkdf2Params.iterations
Hinzugefügt in: v15.0.0
- Typ: <number>
Die Anzahl der Iterationen, die der PBKDF2-Algorithmus beim Ableiten von Bits durchführen soll.
pbkdf2Params.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss
'PBKDF2'sein.
pbkdf2Params.salt
Hinzugefügt in: v15.0.0
- Typ: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Sollte mindestens 16 zufällige oder pseudozufällige Bytes sein.
Klasse: RsaHashedImportParams
Hinzugefügt in: v15.0.0
rsaHashedImportParams.hash
Hinzugefügt in: v15.0.0
Wenn als <string> dargestellt, muss der Wert einer der folgenden sein:
'SHA-1''SHA-256''SHA-384''SHA-512'
Wenn als <Object> dargestellt, muss das Objekt eine name-Eigenschaft haben, deren Wert einer der oben aufgeführten Werte ist.
rsaHashedImportParams.name
Hinzugefügt in: v15.0.0
- Type: <string> Muss einer von
'RSASSA-PKCS1-v1_5','RSA-PSS'oder'RSA-OAEP'sein.
Klasse: RsaHashedKeyGenParams
Hinzugefügt in: v15.0.0
rsaHashedKeyGenParams.hash
Hinzugefügt in: v15.0.0
Wenn als <string> dargestellt, muss der Wert einer der folgenden sein:
'SHA-1''SHA-256''SHA-384''SHA-512'
Wenn als <Object> dargestellt, muss das Objekt eine name-Eigenschaft haben, deren Wert einer der oben aufgeführten Werte ist.
rsaHashedKeyGenParams.modulusLength
Hinzugefügt in: v15.0.0
- Type: <number>
Die Länge des RSA-Modulus in Bits. Als Best Practice sollte dies mindestens 2048 sein.
rsaHashedKeyGenParams.name
Hinzugefügt in: v15.0.0
- Type: <string> Muss einer von
'RSASSA-PKCS1-v1_5','RSA-PSS'oder'RSA-OAEP'sein.
rsaHashedKeyGenParams.publicExponent
Hinzugefügt in: v15.0.0
- Type: <Uint8Array>
Der öffentliche RSA-Exponent. Dies muss ein <Uint8Array> sein, das eine Big-Endian, vorzeichenlose Ganzzahl enthält, die in 32-Bit passen muss. Das <Uint8Array> kann eine beliebige Anzahl von führenden Null-Bits enthalten. Der Wert muss eine Primzahl sein. Sofern kein Grund besteht, einen anderen Wert zu verwenden, verwenden Sie new Uint8Array([1, 0, 1]) (65537) als öffentlichen Exponenten.
Klasse: RsaOaepParams
Hinzugefügt in: v15.0.0
rsaOaepParams.label
Hinzugefügt in: v15.0.0
- Typ: <ArrayBuffer> | <TypedArray> | <DataView> | <Buffer>
Eine zusätzliche Sammlung von Bytes, die nicht verschlüsselt werden, aber an den generierten Chiffretext gebunden werden.
Der Parameter rsaOaepParams.label ist optional.
rsaOaepParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> muss
'RSA-OAEP'sein.
Klasse: RsaPssParams
Hinzugefügt in: v15.0.0
rsaPssParams.name
Hinzugefügt in: v15.0.0
- Typ: <string> Muss
'RSA-PSS'sein.
rsaPssParams.saltLength
Hinzugefügt in: v15.0.0
- Typ: <number>
Die Länge (in Bytes) des zu verwendenden zufälligen Salzes.