Web Crypto API

[Verlauf]

Version	Änderungen
v23.5.0	Die Algorithmen Ed25519 und X25519 sind nun stabil.
v19.0.0	Nicht mehr experimentell, mit Ausnahme der Algorithmen Ed25519, Ed448, X25519 und X448.
v20.0.0, v18.17.0	Argumente werden nun wie in anderen Web Crypto API-Implementierungen gemäß ihren WebIDL-Definitionen gezwungen und validiert.
v18.4.0, v16.17.0	Proprietäres 'node.keyObject' Import-/Exportformat 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 'ECDH'-Algorithmus 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('Ich liebe 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 }
}

Ver- 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 ein- 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
}

Algorithmus-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 geworfen, 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 generiert.

Klasse: CryptoKey

Hinzugefügt in: v15.0.0

cryptoKey.algorithm

Hinzugefügt in: v15.0.0

• Typ: <AesKeyGenParams> | <RsaHashedKeyGenParams> | <EcKeyGenParams> | <HmacKeyGenParams>

Ein Objekt, das den Algorithmus detailliert 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 Zeichenfolge, die angibt, ob der Schlüssel ein symmetrischer ('secret') oder asymmetrischer ('private' oder 'public') Schlüssel ist.

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 Verwendungszwecke sind:

• 'encrypt' - Der Schlüssel kann zum Verschlüsseln von Daten verwendet werden.
• 'decrypt' - Der Schlüssel kann zum Entschlüsseln von Daten verwendet werden.
• 'sign' - Der Schlüssel kann zum Erzeugen digitaler Signaturen verwendet werden.
• 'verify' - Der Schlüssel kann zum Verifizieren digitaler Signaturen verwendet werden.
• 'deriveKey' - Der Schlüssel kann zum Ableiten eines neuen Schlüssels verwendet werden.
• 'deriveBits' - Der Schlüssel kann zum Ableiten von Bits verwendet werden.
• 'wrapKey' - Der Schlüssel kann zum Wrappen eines anderen Schlüssels verwendet werden.
• 'unwrapKey' - Der Schlüssel kann zum Entwrappen 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

Das CryptoKeyPair ist ein einfaches Dictionary-Objekt mit publicKey- und privateKey-Eigenschaften, das ein asymmetrisches Schlüsselpaar darstellt.

cryptoKeyPair.privateKey

Hinzugefügt in: v15.0.0

• Typ: <CryptoKey> Ein <CryptoKey>, dessen type 'private' sein wird.

cryptoKeyPair.publicKey

Hinzugefügt in: v15.0.0

• Typ: <CryptoKey> Ein <CryptoKey>, dessen type 'public' sein wird.

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

Mit der in algorithm angegebenen Methode und Parametern sowie dem von key bereitgestellten Schlüsselmaterial 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 sind:

• 'RSA-OAEP'
• 'AES-CTR'
• 'AES-CBC'
• 'AES-GCM'

subtle.deriveBits(algorithm, baseKey[, length])

[Historie]

Version	Änderungen
v22.5.0, v20.17.0	Der Parameter length ist nun für 'ECDH', 'X25519' und 'X448' optional.
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
• Gibt zurück: <Promise> Wird mit einem <ArrayBuffer> erfüllt.

Unter Verwendung der in algorithm angegebenen Methode und Parameter und des von baseKey bereitgestellten Schlüsselmaterials versucht subtle.deriveBits() length Bits zu erzeugen.

Wenn length nicht angegeben wird oder null ist, wird die maximale Anzahl von Bits für einen bestimmten Algorithmus erzeugt. Dies ist für die Algorithmen 'ECDH', 'X25519' und 'X448' zulässig. Für andere Algorithmen muss length eine Zahl sein.

Bei Erfolg wird das zurückgegebene Promise mit einem <ArrayBuffer> aufgelöst, das die erzeugten Daten enthält.

Die derzeit unterstützten Algorithmen sind:

• 'ECDH'
• 'X25519'
• 'X448'
• 'HKDF'
• 'PBKDF2'

subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)

[Historie]

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.
• Gibt zurück: <Promise> Wird mit einem <CryptoKey> erfüllt.

Unter Verwendung der in algorithm angegebenen Methode und Parameter und des von baseKey bereitgestellten Schlüsselmaterials versucht subtle.deriveKey() einen neuen <CryptoKey> basierend auf der Methode und den Parametern in derivedKeyAlgorithm zu erzeugen.

Der Aufruf von subtle.deriveKey() entspricht dem Aufruf von subtle.deriveBits(), um rohes Schlüsselmaterial zu erzeugen, und dem anschließenden Übergeben des Ergebnisses an die Methode subtle.importKey() unter Verwendung der Parameter deriveKeyAlgorithm, extractable und keyUsages als Eingabe.

Die derzeit unterstützten Algorithmen sind:

• '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 Digest von data zu generieren. Bei Erfolg wird das zurückgegebene Promise mit einem <ArrayBuffer> aufgelöst, das den berechneten Digest 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 obigen 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 Methode und den Parametern, die von algorithm angegeben werden, und dem von 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 sind:

• 'RSA-OAEP'
• 'AES-CTR'
• 'AES-CBC'
• 'AES-GCM'

subtle.exportKey(format, key)

[Verlauf]

Version	Änderungen
v18.4.0, v16.17.0	Die Algorithmen 'Ed25519', 'Ed448', 'X25519' und 'X448' wurden hinzugefügt.
v15.9.0	Der JWK-Export 'NODE-DSA' wurde 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.

Unter Verwendung der in algorithm bereitgestellten Methode und Parameter 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) umfassen:

• '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) umfassen:

• '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	Algorithmen 'Ed25519', 'Ed448', 'X25519' und 'X448' hinzugefügt.
v15.9.0	'NODE-DSA' JWK-Import 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 angegebene format zu interpretieren, um eine <CryptoKey>-Instanz unter Verwendung der bereitgestellten Argumente algorithm, extractable und keyUsages zu erstellen. Wenn der Import erfolgreich ist, wird das zurückgegebene Promise mit dem erstellten <CryptoKey> aufgelöst.

Beim Import eines 'PBKDF2'-Schlüssels muss extractable false sein.

Die derzeit unterstützten Algorithmen sind:

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	Algorithmen 'Ed25519' und 'Ed448' 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.

Mit der Methode und den Parametern, die durch algorithm angegeben sind, und dem Schlüsselmaterial, das durch key bereitgestellt wird, versucht subtle.sign() eine kryptografische Signatur von data zu generieren. Bei Erfolg 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 Schlüsselverwendungen.

• Gibt zurück: <Promise> Wird mit einem <CryptoKey> erfüllt.

In der Kryptographie bezieht sich "das Umhüllen eines Schlüssels" auf das Exportieren und anschließende Verschlüsseln des Schlüsselmaterials. Die Methode subtle.unwrapKey() versucht, einen umhüllten Schlüssel zu entschlüsseln und eine <CryptoKey>-Instanz zu erstellen. Es entspricht dem Aufruf von subtle.decrypt() zuerst auf den verschlüsselten Schlüsseldaten (unter Verwendung der Argumente wrappedKey, unwrapAlgo und unwrappingKey als Eingabe) und dann dem Übergeben der Ergebnisse an die Methode subtle.importKey() unter Verwendung der Argumente unwrappedKeyAlgo, extractable und keyUsages als Eingabe. Bei Erfolg wird das zurückgegebene Promise mit einem <CryptoKey>-Objekt aufgelöst.

Die derzeit unterstützten Umhüllungsalgorithmen umfassen:

• 'RSA-OAEP'
• 'AES-CTR'
• 'AES-CBC'
• 'AES-GCM'
• 'AES-KW'

Die unterstützten Algorithmen für nicht umhüllte 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)

[History]

Version	Änderungen
v18.4.0, v16.17.0	Algorithmen 'Ed25519' und 'Ed448' 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.

Unter Verwendung der in algorithm angegebenen Methode und Parameter sowie des von key bereitgestellten Schlüsselmaterials versucht subtle.verify(), zu überprüfen, ob signature eine gültige kryptografische Signatur von data ist. Die zurückgegebene Promise wird entweder mit true oder false aufgelöst.

Die aktuell unterstützten Algorithmen sind:

• '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 eines 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 "einen Schlüssel wrappen" 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 dann unter Verwendung der durch wrapAlgo spezifizierten Methode und Parameter sowie des von wrappingKey bereitgestellten Schlüsselmaterials. Es ist das Äquivalent zum Aufrufen von subtle.exportKey() mit format und key als Argumente und anschließenden Übergeben des Ergebnisses an die Methode subtle.encrypt() mit wrappingKey und wrapAlgo als Eingaben. Im Erfolgsfall wird die zurückgegebene Promise mit einem <ArrayBuffer> aufgelöst, das die verschlüsselten Schlüsseldaten enthält.

Die aktuell unterstützten Wrapping-Algorithmen sind:

• 'RSA-OAEP'
• 'AES-CTR'
• 'AES-CBC'
• 'AES-GCM'
• 'AES-KW'

Algorithmusparameter

Die Algorithmusparameterobjekte 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>

Gibt den Initialisierungsvektor an. 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, sondern 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 jeden Verschlüsselungsvorgang mit einem bestimmten Schlüssel eindeutig sein.

Idealerweise handelt es sich um einen deterministischen 12-Byte-Wert, der so berechnet wird, dass er garantiert eindeutig ist für alle Aufrufe, die denselben Schlüssel verwenden. Alternativ kann der Initialisierungsvektor aus mindestens 12 kryptographisch 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. Diese Werte müssen entweder 32, 64, 96, 104, 112, 120 oder 128 sein. 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 sie den privaten Schlüssel einer Partei und den öffentlichen Schlüssel einer anderen Partei als Eingabe verwendet, um ein gemeinsames, geteiltes Geheimnis zu generieren. Die Eigenschaft ecdhKeyDeriveParams.public ist 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

• Typ: <string> | <Object>

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 mit der Nachricht verknüpft werden sollen. Die Node.js Web Crypto API-Implementierung unterstützt nur Kontext mit der Länge Null, was dem Nichtbereitstellen von Kontext entspricht.

Klasse: HkdfParams

Hinzugefügt in: v15.0.0

hkdfParams.hash

Hinzugefügt in: v15.0.0

• Typ: <string> | <Object>

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>

Stellt anwendungsspezifische kontextbezogene Eingaben für den HKDF-Algorithmus bereit. Dies kann eine Länge von Null haben, muss aber bereitgestellt 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 zufälligen Daten sein).

Klasse: HmacImportParams

Hinzugefügt in: v15.0.0

hmacImportParams.hash

Hinzugefügt in: v15.0.0

• Typ: <string> | <Object>

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

• Typ: <string> | <Object>

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 weggelassen, 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

• Typ: <string> | <Object>

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 enthalten.

Klasse: RsaHashedImportParams

Hinzugefügt in: v15.0.0

rsaHashedImportParams.hash

Hinzugefügt in: v15.0.0

• Typ: <string> | <Object>

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

• Typ: <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

• Typ: <string> | <Object>

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

• Typ: <number>

Die Länge des RSA-Moduls in Bit. Als bewährte Methode sollte dies mindestens 2048 sein.

rsaHashedKeyGenParams.name

Hinzugefügt in: v15.0.0

• Typ: <string> Muss einer von 'RSASSA-PKCS1-v1_5', 'RSA-PSS' oder 'RSA-OAEP' sein.

rsaHashedKeyGenParams.publicExponent

Hinzugefügt in: v15.0.0

• Typ: <Uint8Array>

Der öffentliche RSA-Exponent. Dies muss ein <Uint8Array> sein, das eine Big-Endian-Ganzzahl ohne Vorzeichen enthält, die in 32 Bit passen muss. Das <Uint8Array> kann eine beliebige Anzahl führender Nullbits 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, sondern an den erzeugten 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.

Fußnoten