iDoc.dev

Deutsch

English
简体中文
Español
Français
Português
Italiano
日本語
한국어
Русский
العربية

Deutsch

English
简体中文
Español
Français
Português
Italiano
日本語
한국어
Русский
العربية

Thema

Kryptografie ​

[Stabil: 2 - Stabil]

Stabil: 2 Stabilität: 2 - Stabil

Quellcode: lib/crypto.js

Das Modul node:crypto bietet kryptografische Funktionen, darunter eine Reihe von Wrappern für die Hash-, HMAC-, Cipher-, Decipher-, Signatur- und Verifizierungsfunktionen von OpenSSL.

js
const { createHmac } = await import('node:crypto')

const secret = 'abcdefg'
const hash = createHmac('sha256', secret).update('I love cupcakes').digest('hex')
console.log(hash)
// Gibt aus:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e
js
const { createHmac } = require('node:crypto')

const secret = 'abcdefg'
const hash = createHmac('sha256', secret).update('I love cupcakes').digest('hex')
console.log(hash)
// Gibt aus:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e

Feststellen, ob Kryptografie-Unterstützung nicht verfügbar ist ​

Es ist möglich, dass Node.js ohne Unterstützung für das Modul node:crypto kompiliert wird. In solchen Fällen führt der Versuch, aus crypto zu importieren oder require('node:crypto') aufzurufen, zu einem Fehler.

Bei Verwendung von CommonJS kann der ausgegebene Fehler mit try/catch abgefangen werden:

js
let crypto
try {
  crypto = require('node:crypto')
} catch (err) {
  console.error('Kryptografie-Unterstützung ist deaktiviert!')
}

Bei Verwendung des lexikalischen ESM import-Schlüsselworts kann der Fehler nur abgefangen werden, wenn ein Handler für process.on('uncaughtException') vor jedem Versuch, das Modul zu laden, registriert wird (z. B. mit einem Preload-Modul).

Bei Verwendung von ESM sollte, wenn die Möglichkeit besteht, dass der Code auf einem Build von Node.js ausgeführt wird, auf dem die Kryptografie-Unterstützung nicht aktiviert ist, die Funktion import() anstelle des lexikalischen import-Schlüsselworts verwendet werden:

js
let crypto
try {
  crypto = await import('node:crypto')
} catch (err) {
  console.error('Kryptografie-Unterstützung ist deaktiviert!')
}

Klasse: Certificate ​

Hinzugefügt in: v0.11.8

SPKAC ist ein Mechanismus für Certificate Signing Requests, der ursprünglich von Netscape implementiert und formal als Teil des keygen-Elements von HTML5 spezifiziert wurde.

\<keygen\> ist seit HTML 5.2 veraltet, und neue Projekte sollten dieses Element nicht mehr verwenden.

Das Modul node:crypto bietet die Klasse Certificate zur Arbeit mit SPKAC-Daten. Die häufigste Verwendung ist die Verarbeitung von Ausgaben, die vom HTML5-Element \<keygen\> generiert werden. Node.js verwendet intern OpenSSLs SPKAC-Implementierung.

Statische Methode: Certificate.exportChallenge(spkac[, encoding]) ​

[Historie]

VersionÄnderungen
v15.0.0Das Argument spkac kann ein ArrayBuffer sein. Die Größe des Arguments spkac wurde auf maximal 2**31 - 1 Bytes begrenzt.
v9.0.0Hinzugefügt in: v9.0.0
js
const { Certificate } = await import('node:crypto')
const spkac = getSpkacSomehow()
const challenge = Certificate.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// Gibt aus: die Challenge als UTF8-Zeichenkette
js
const { Certificate } = require('node:crypto')
const spkac = getSpkacSomehow()
const challenge = Certificate.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// Gibt aus: die Challenge als UTF8-Zeichenkette

Statische Methode: Certificate.exportPublicKey(spkac[, encoding]) ​

[Verlauf]

VersionÄnderungen
v15.0.0Das Argument spkac kann ein ArrayBuffer sein. Die Größe des Arguments spkac wurde auf maximal 2**31 - 1 Byte begrenzt.
v9.0.0Hinzugefügt in: v9.0.0
js
const { Certificate } = await import('node:crypto')
const spkac = getSpkacSomehow()
const publicKey = Certificate.exportPublicKey(spkac)
console.log(publicKey)
// Gibt aus: den öffentlichen Schlüssel als <Buffer ...>
js
const { Certificate } = require('node:crypto')
const spkac = getSpkacSomehow()
const publicKey = Certificate.exportPublicKey(spkac)
console.log(publicKey)
// Gibt aus: den öffentlichen Schlüssel als <Buffer ...>

Statische Methode: Certificate.verifySpkac(spkac[, encoding]) ​

[Verlauf]

VersionÄnderungen
v15.0.0Das Argument spkac kann ein ArrayBuffer sein. encoding hinzugefügt. Die Größe des Arguments spkac wurde auf maximal 2**31 - 1 Byte begrenzt.
v9.0.0Hinzugefügt in: v9.0.0
js
import { Buffer } from 'node:buffer'
const { Certificate } = await import('node:crypto')

const spkac = getSpkacSomehow()
console.log(Certificate.verifySpkac(Buffer.from(spkac)))
// Gibt aus: true oder false
js
const { Buffer } = require('node:buffer')
const { Certificate } = require('node:crypto')

const spkac = getSpkacSomehow()
console.log(Certificate.verifySpkac(Buffer.from(spkac)))
// Gibt aus: true oder false

Legacy-API ​

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet

Als Legacy-Schnittstelle ist es möglich, neue Instanzen der Klasse crypto.Certificate zu erstellen, wie in den folgenden Beispielen gezeigt.

new crypto.Certificate() ​

Instanzen der Klasse Certificate können mit dem Schlüsselwort new oder durch Aufruf von crypto.Certificate() als Funktion erstellt werden:

js
const { Certificate } = await import('node:crypto')

const cert1 = new Certificate()
const cert2 = Certificate()
js
const { Certificate } = require('node:crypto')

const cert1 = new Certificate()
const cert2 = Certificate()

certificate.exportChallenge(spkac[, encoding]) ​

Hinzugefügt in: v0.11.8

js
const { Certificate } = await import('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const challenge = cert.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// Gibt aus: die Challenge als UTF8-Zeichenkette
js
const { Certificate } = require('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const challenge = cert.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// Gibt aus: die Challenge als UTF8-Zeichenkette

certificate.exportPublicKey(spkac[, encoding]) ​

Hinzugefügt in: v0.11.8

js
const { Certificate } = await import('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const publicKey = cert.exportPublicKey(spkac)
console.log(publicKey)
// Gibt aus: den öffentlichen Schlüssel als <Buffer ...>
js
const { Certificate } = require('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const publicKey = cert.exportPublicKey(spkac)
console.log(publicKey)
// Gibt aus: den öffentlichen Schlüssel als <Buffer ...>

certificate.verifySpkac(spkac[, encoding]) ​

Hinzugefügt in: v0.11.8

js
import { Buffer } from 'node:buffer'
const { Certificate } = await import('node:crypto')

const cert = Certificate()
const spkac = getSpkacSomehow()
console.log(cert.verifySpkac(Buffer.from(spkac)))
// Gibt aus: true oder false
js
const { Buffer } = require('node:buffer')
const { Certificate } = require('node:crypto')

const cert = Certificate()
const spkac = getSpkacSomehow()
console.log(cert.verifySpkac(Buffer.from(spkac)))
// Gibt aus: true oder false

Klasse: Cipher ​

Hinzugefügt in: v0.1.94

Instanzen der Klasse Cipher werden verwendet, um Daten zu verschlüsseln. Die Klasse kann auf zwei Arten verwendet werden:

  • Als Stream, der sowohl lesbar als auch beschreibbar ist, wobei unverschlüsselte Daten geschrieben werden, um verschlüsselte Daten auf der lesbaren Seite zu erzeugen, oder
  • Mit den Methoden cipher.update() und cipher.final(), um die verschlüsselten Daten zu erzeugen.

Die Methode crypto.createCipheriv() wird verwendet, um Cipher-Instanzen zu erstellen. Cipher-Objekte dürfen nicht direkt mit dem Schlüsselwort new erstellt werden.

Beispiel: Verwendung von Cipher-Objekten als Streams:

js
const { scrypt, randomFill, createCipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'

// Zuerst generieren wir den Schlüssel. Die Schlüssellänge hängt vom Algorithmus ab.
// In diesem Fall für aes192 sind es 24 Bytes (192 Bit).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Dann generieren wir einen zufälligen Initialisierungsvektor
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    // Sobald wir den Schlüssel und den IV haben, können wir die Chiffre erstellen und verwenden...
    const cipher = createCipheriv(algorithm, key, iv)

    let encrypted = ''
    cipher.setEncoding('hex')

    cipher.on('data', chunk => (encrypted += chunk))
    cipher.on('end', () => console.log(encrypted))

    cipher.write('some clear text data')
    cipher.end()
  })
})
js
const { scrypt, randomFill, createCipheriv } = require('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'

// Zuerst generieren wir den Schlüssel. Die Schlüssellänge hängt vom Algorithmus ab.
// In diesem Fall für aes192 sind es 24 Bytes (192 Bit).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Dann generieren wir einen zufälligen Initialisierungsvektor
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    // Sobald wir den Schlüssel und den IV haben, können wir die Chiffre erstellen und verwenden...
    const cipher = createCipheriv(algorithm, key, iv)

    let encrypted = ''
    cipher.setEncoding('hex')

    cipher.on('data', chunk => (encrypted += chunk))
    cipher.on('end', () => console.log(encrypted))

    cipher.write('some clear text data')
    cipher.end()
  })
})

Beispiel: Verwendung von Cipher und gepipeteten Streams:

js
import { createReadStream, createWriteStream } from 'node:fs'

import { pipeline } from 'node:stream'

const { scrypt, randomFill, createCipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'

// Zuerst generieren wir den Schlüssel. Die Schlüssellänge hängt vom Algorithmus ab.
// In diesem Fall für aes192 sind es 24 Bytes (192 Bit).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Dann generieren wir einen zufälligen Initialisierungsvektor
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

    const input = createReadStream('test.js')
    const output = createWriteStream('test.enc')

    pipeline(input, cipher, output, err => {
      if (err) throw err
    })
  })
})
js
const { createReadStream, createWriteStream } = require('node:fs')

const { pipeline } = require('node:stream')

const { scrypt, randomFill, createCipheriv } = require('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'

// Zuerst generieren wir den Schlüssel. Die Schlüssellänge hängt vom Algorithmus ab.
// In diesem Fall für aes192 sind es 24 Bytes (192 Bit).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Dann generieren wir einen zufälligen Initialisierungsvektor
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

    const input = createReadStream('test.js')
    const output = createWriteStream('test.enc')

    pipeline(input, cipher, output, err => {
      if (err) throw err
    })
  })
})

Beispiel: Verwendung der Methoden cipher.update() und cipher.final():

js
const { scrypt, randomFill, createCipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'

// Zuerst generieren wir den Schlüssel. Die Schlüssellänge hängt vom Algorithmus ab.
// In diesem Fall für aes192 sind es 24 Bytes (192 Bit).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Dann generieren wir einen zufälligen Initialisierungsvektor
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

    let encrypted = cipher.update('some clear text data', 'utf8', 'hex')
    encrypted += cipher.final('hex')
    console.log(encrypted)
  })
})
js
const { scrypt, randomFill, createCipheriv } = require('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'

// Zuerst generieren wir den Schlüssel. Die Schlüssellänge hängt vom Algorithmus ab.
// In diesem Fall für aes192 sind es 24 Bytes (192 Bit).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Dann generieren wir einen zufälligen Initialisierungsvektor
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    const cipher = createCipheriv(algorithm, key, iv)

    let encrypted = cipher.update('some clear text data', 'utf8', 'hex')
    encrypted += cipher.final('hex')
    console.log(encrypted)
  })
})

cipher.final([outputEncoding]) ​

Hinzugefügt in: v0.1.94

  • outputEncoding <string> Die Kodierung des Rückgabewerts.
  • Rückgabewert: <Buffer> | <string> Alle restlichen verschlüsselten Inhalte. Wenn outputEncoding angegeben ist, wird eine Zeichenkette zurückgegeben. Wenn kein outputEncoding angegeben ist, wird ein Buffer zurückgegeben.

Nachdem die Methode cipher.final() aufgerufen wurde, kann das Cipher-Objekt nicht mehr zum Verschlüsseln von Daten verwendet werden. Versuche, cipher.final() mehr als einmal aufzurufen, führen zu einem Fehler.

cipher.getAuthTag() ​

Hinzugefügt in: v1.0.0

  • Rückgabewert: <Buffer> Bei Verwendung eines authentifizierten Verschlüsselungsmodus (GCM, CCM, OCB und chacha20-poly1305 werden derzeit unterstützt) gibt die Methode cipher.getAuthTag() einen Buffer zurück, der das aus den gegebenen Daten berechnete Authentifizierungstag enthält.

Die Methode cipher.getAuthTag() sollte erst nach Abschluss der Verschlüsselung mit der Methode cipher.final() aufgerufen werden.

Wenn die Option authTagLength während der Erstellung der cipher-Instanz gesetzt wurde, gibt diese Funktion genau authTagLength Bytes zurück.

cipher.setAAD(buffer[, options]) ​

Hinzugefügt in: v1.0.0

Bei Verwendung eines authentifizierten Verschlüsselungsmodus (GCM, CCM, OCB und chacha20-poly1305 werden derzeit unterstützt) legt die Methode cipher.setAAD() den Wert fest, der für den zusätzliche authentifizierte Daten (AAD)-Eingabeparameter verwendet wird.

Die Option plaintextLength ist für GCM und OCB optional. Bei Verwendung von CCM muss die Option plaintextLength angegeben werden und ihr Wert muss der Länge des Klartextes in Bytes entsprechen. Siehe CCM-Modus.

Die Methode cipher.setAAD() muss vor cipher.update() aufgerufen werden.

cipher.setAutoPadding([autoPadding]) ​

Hinzugefügt in: v0.7.1

  • autoPadding <boolean> Standardwert: true
  • Rückgabewert: <Cipher> Dieselbe Cipher-Instanz für Methodenkette.

Bei Verwendung von Blockverschlüsselungsverfahren fügt die Klasse Cipher den Eingabedaten automatisch eine Auffüllung (Padding) auf die entsprechende Blockgröße hinzu. Um die Standardauffüllung zu deaktivieren, rufen Sie cipher.setAutoPadding(false) auf.

Wenn autoPadding auf false gesetzt ist, muss die Länge der gesamten Eingabedaten ein Vielfaches der Blockgröße der Chiffre sein, andernfalls löst cipher.final() einen Fehler aus. Das Deaktivieren der automatischen Auffüllung ist nützlich für nicht standardmäßige Auffüllungen, z. B. die Verwendung von 0x0 anstelle von PKCS-Auffüllung.

Die Methode cipher.setAutoPadding() muss vor cipher.final() aufgerufen werden.

cipher.update(data[, inputEncoding][, outputEncoding]) ​

[Historie]

VersionÄnderungen
v6.0.0Die Standardcodierung von inputEncoding wurde von binary zu utf8 geändert.
v0.1.94Hinzugefügt in: v0.1.94

Aktualisiert die Chiffre mit data. Wenn das Argument inputEncoding angegeben ist, handelt es sich bei dem Argument data um eine Zeichenkette mit der angegebenen Codierung. Wenn das Argument inputEncoding nicht angegeben ist, muss data ein Buffer, TypedArray oder DataView sein. Wenn data ein Buffer, TypedArray oder DataView ist, wird inputEncoding ignoriert.

outputEncoding gibt das Ausgabeformat der verschlüsselten Daten an. Wenn outputEncoding angegeben ist, wird eine Zeichenkette mit der angegebenen Codierung zurückgegeben. Wenn kein outputEncoding angegeben ist, wird ein Buffer zurückgegeben.

Die Methode cipher.update() kann mehrmals mit neuen Daten aufgerufen werden, bis cipher.final() aufgerufen wird. Ein Aufruf von cipher.update() nach cipher.final() führt zu einem Fehler.

Klasse: Decipher ​

Hinzugefügt in: v0.1.94

Instanzen der Klasse Decipher werden verwendet, um Daten zu entschlüsseln. Die Klasse kann auf zwei Arten verwendet werden:

  • Als Stream, der sowohl lesbar als auch beschreibbar ist, wobei verschlüsselte Daten geschrieben werden, um unverschlüsselte Daten auf der lesbaren Seite zu erzeugen, oder
  • Mit den Methoden decipher.update() und decipher.final(), um die unverschlüsselten Daten zu erzeugen.

Die Methode crypto.createDecipheriv() wird verwendet, um Decipher-Instanzen zu erstellen. Decipher-Objekte dürfen nicht direkt mit dem Schlüsselwort new erstellt werden.

Beispiel: Verwendung von Decipher-Objekten als Streams:

js
import { Buffer } from 'node:buffer'
const { scryptSync, createDecipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'
// Die Schlüssellänge hängt vom Algorithmus ab. In diesem Fall für aes192 sind es
// 24 Bytes (192 Bit).
// Verwenden Sie stattdessen das asynchrone `crypto.scrypt()`.
const key = scryptSync(password, 'salt', 24)
// Der IV wird normalerweise zusammen mit dem Chiffretext übergeben.
const iv = Buffer.alloc(16, 0) // Initialisierungsvektor.

const decipher = createDecipheriv(algorithm, key, iv)

let decrypted = ''
decipher.on('readable', () => {
  let chunk
  while (null !== (chunk = decipher.read())) {
    decrypted += chunk.toString('utf8')
  }
})
decipher.on('end', () => {
  console.log(decrypted)
  // Gibt aus: some clear text data
})

// Verschlüsselt mit demselben Algorithmus, Schlüssel und IV.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
decipher.write(encrypted, 'hex')
decipher.end()
js
const { scryptSync, createDecipheriv } = require('node:crypto')
const { Buffer } = require('node:buffer')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'
// Die Schlüssellänge hängt vom Algorithmus ab. In diesem Fall für aes192 sind es
// 24 Bytes (192 Bit).
// Verwenden Sie stattdessen das asynchrone `crypto.scrypt()`.
const key = scryptSync(password, 'salt', 24)
// Der IV wird normalerweise zusammen mit dem Chiffretext übergeben.
const iv = Buffer.alloc(16, 0) // Initialisierungsvektor.

const decipher = createDecipheriv(algorithm, key, iv)

let decrypted = ''
decipher.on('readable', () => {
  let chunk
  while (null !== (chunk = decipher.read())) {
    decrypted += chunk.toString('utf8')
  }
})
decipher.on('end', () => {
  console.log(decrypted)
  // Gibt aus: some clear text data
})

// Verschlüsselt mit demselben Algorithmus, Schlüssel und IV.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
decipher.write(encrypted, 'hex')
decipher.end()

Beispiel: Verwendung von Decipher und gepipten Streams:

js
import { createReadStream, createWriteStream } from 'node:fs'
import { Buffer } from 'node:buffer'
const { scryptSync, createDecipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'
// Verwenden Sie stattdessen das asynchrone `crypto.scrypt()`.
const key = scryptSync(password, 'salt', 24)
// Der IV wird normalerweise zusammen mit dem Chiffretext übergeben.
const iv = Buffer.alloc(16, 0) // Initialisierungsvektor.

const decipher = createDecipheriv(algorithm, key, iv)

const input = createReadStream('test.enc')
const output = createWriteStream('test.js')

input.pipe(decipher).pipe(output)
js
const { createReadStream, createWriteStream } = require('node:fs')
const { scryptSync, createDecipheriv } = require('node:crypto')
const { Buffer } = require('node:buffer')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'
// Verwenden Sie stattdessen das asynchrone `crypto.scrypt()`.
const key = scryptSync(password, 'salt', 24)
// Der IV wird normalerweise zusammen mit dem Chiffretext übergeben.
const iv = Buffer.alloc(16, 0) // Initialisierungsvektor.

const decipher = createDecipheriv(algorithm, key, iv)

const input = createReadStream('test.enc')
const output = createWriteStream('test.js')

input.pipe(decipher).pipe(output)

Beispiel: Verwendung der Methoden decipher.update() und decipher.final():

js
import { Buffer } from 'node:buffer'
const { scryptSync, createDecipheriv } = await import('node:crypto')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'
// Verwenden Sie stattdessen das asynchrone `crypto.scrypt()`.
const key = scryptSync(password, 'salt', 24)
// Der IV wird normalerweise zusammen mit dem Chiffretext übergeben.
const iv = Buffer.alloc(16, 0) // Initialisierungsvektor.

const decipher = createDecipheriv(algorithm, key, iv)

// Verschlüsselt mit demselben Algorithmus, Schlüssel und IV.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
let decrypted = decipher.update(encrypted, 'hex', 'utf8')
decrypted += decipher.final('utf8')
console.log(decrypted)
// Gibt aus: some clear text data
js
const { scryptSync, createDecipheriv } = require('node:crypto')
const { Buffer } = require('node:buffer')

const algorithm = 'aes-192-cbc'
const password = 'Password used to generate key'
// Verwenden Sie stattdessen das asynchrone `crypto.scrypt()`.
const key = scryptSync(password, 'salt', 24)
// Der IV wird normalerweise zusammen mit dem Chiffretext übergeben.
const iv = Buffer.alloc(16, 0) // Initialisierungsvektor.

const decipher = createDecipheriv(algorithm, key, iv)

// Verschlüsselt mit demselben Algorithmus, Schlüssel und IV.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
let decrypted = decipher.update(encrypted, 'hex', 'utf8')
decrypted += decipher.final('utf8')
console.log(decrypted)
// Gibt aus: some clear text data

decipher.final([outputEncoding]) ​

Hinzugefügt in: v0.1.94

  • outputEncoding <string> Die Kodierung des Rückgabewerts.
  • Rückgabewert: <Buffer> | <string> Alle verbleibenden entschlüsselten Inhalte. Wenn outputEncoding angegeben ist, wird eine Zeichenkette zurückgegeben. Wenn kein outputEncoding angegeben ist, wird ein Buffer zurückgegeben.

Nachdem die Methode decipher.final() aufgerufen wurde, kann das Decipher-Objekt nicht mehr zum Entschlüsseln von Daten verwendet werden. Versuche, decipher.final() mehr als einmal aufzurufen, führen zu einem Fehler.

decipher.setAAD(buffer[, options]) ​

[Verlauf]

VersionÄnderungen
v15.0.0Das buffer-Argument kann eine Zeichenkette oder ein ArrayBuffer sein und ist auf maximal 2 ** 31 - 1 Bytes begrenzt.
v7.2.0Diese Methode gibt jetzt eine Referenz auf decipher zurück.
v1.0.0Hinzugefügt in: v1.0.0

Bei Verwendung eines authentifizierten Verschlüsselungsmodus (GCM, CCM, OCB und chacha20-poly1305 werden derzeit unterstützt) legt die Methode decipher.setAAD() den Wert fest, der für den Eingabeparameter zusätzliche authentifizierte Daten (AAD) verwendet wird.

Das Argument options ist für GCM optional. Bei Verwendung von CCM muss die Option plaintextLength angegeben werden und ihr Wert muss der Länge des Ciphertexts in Bytes entsprechen. Siehe CCM-Modus.

Die Methode decipher.setAAD() muss vor decipher.update() aufgerufen werden.

Wenn Sie eine Zeichenkette als buffer übergeben, beachten Sie bitte die Warnungen bei der Verwendung von Zeichenketten als Eingaben für kryptografische APIs.

decipher.setAuthTag(buffer[, encoding]) ​

[Verlauf]

VersionÄnderungen
v22.0.0, v20.13.0Die Verwendung von GCM-Tag-Längen ungleich 128 Bit ohne Angabe der Option authTagLength bei der Erstellung von decipher ist veraltet.
v15.0.0Das buffer-Argument kann ein String oder ArrayBuffer sein und ist auf maximal 2 ** 31 - 1 Bytes begrenzt.
v11.0.0Diese Methode löst nun einen Fehler aus, wenn die GCM-Tag-Länge ungültig ist.
v7.2.0Diese Methode gibt nun eine Referenz auf decipher zurück.
v1.0.0Hinzugefügt in: v1.0.0

Bei Verwendung eines authentifizierten Verschlüsselungsmodus (GCM, CCM, OCB und chacha20-poly1305 werden derzeit unterstützt) wird die Methode decipher.setAuthTag() verwendet, um den empfangenen Authentifizierungs-Tag zu übergeben. Wenn kein Tag angegeben wird oder der Chiffretext manipuliert wurde, löst decipher.final() einen Fehler aus, der darauf hinweist, dass der Chiffretext aufgrund fehlgeschlagener Authentifizierung verworfen werden sollte. Wenn die Tag-Länge gemäß NIST SP 800-38D ungültig ist oder nicht mit dem Wert der Option authTagLength übereinstimmt, löst decipher.setAuthTag() einen Fehler aus.

Die Methode decipher.setAuthTag() muss vor decipher.update() für den CCM-Modus oder vor decipher.final() für die Modi GCM und OCB sowie chacha20-poly1305 aufgerufen werden. decipher.setAuthTag() kann nur einmal aufgerufen werden.

Wenn ein String als Authentifizierungs-Tag übergeben wird, beachten Sie bitte die Warnungen bei der Verwendung von Strings als Eingaben für kryptografische APIs.

decipher.setAutoPadding([autoPadding]) ​

Hinzugefügt in: v0.7.1

  • autoPadding <boolean> Standardwert: true
  • Rückgabewert: <Decipher> Das gleiche Decipher-Objekt für Method Chaining.

Wenn Daten ohne Standard-Block-Padding verschlüsselt wurden, deaktiviert der Aufruf von decipher.setAutoPadding(false) das automatische Padding, um zu verhindern, dass decipher.final() nach Padding sucht und es entfernt.

Das Deaktivieren des automatischen Paddings funktioniert nur, wenn die Länge der Eingabedaten ein Vielfaches der Blockgröße des Chiphers ist.

Die Methode decipher.setAutoPadding() muss vor decipher.final() aufgerufen werden.

decipher.update(data[, inputEncoding][, outputEncoding]) ​

[Versionsgeschichte]

VersionÄnderungen
v6.0.0Der Standardwert von inputEncoding wurde von binary zu utf8 geändert.
v0.1.94Hinzugefügt in: v0.1.94

Aktualisiert die Entschlüsselung mit data. Wenn das Argument inputEncoding angegeben ist, ist das Argument data eine Zeichenkette mit der angegebenen Kodierung. Wenn das Argument inputEncoding nicht angegeben ist, muss data ein Buffer sein. Wenn data ein Buffer ist, wird inputEncoding ignoriert.

outputEncoding gibt das Ausgabeformat der verschlüsselten Daten an. Wenn outputEncoding angegeben ist, wird eine Zeichenkette mit der angegebenen Kodierung zurückgegeben. Wenn kein outputEncoding angegeben ist, wird ein Buffer zurückgegeben.

Die Methode decipher.update() kann mehrmals mit neuen Daten aufgerufen werden, bis decipher.final() aufgerufen wird. Ein Aufruf von decipher.update() nach decipher.final() führt zu einem Fehler.

Auch wenn der zugrunde liegende Chipher Authentifizierung implementiert, können die Authentizität und Integrität des von dieser Funktion zurückgegebenen Klartexts zu diesem Zeitpunkt ungewiss sein. Bei authentifizierten Verschlüsselungsalgorithmen wird die Authentizität im Allgemeinen erst hergestellt, wenn die Anwendung decipher.final() aufruft.

Klasse: DiffieHellman ​

Hinzugefügt in: v0.5.0

Die Klasse DiffieHellman ist ein Dienstprogramm zum Erstellen von Diffie-Hellman-Schlüsselaustauschen.

Instanzen der Klasse DiffieHellman können mit der Funktion crypto.createDiffieHellman() erstellt werden.

js
import assert from 'node:assert'

const { createDiffieHellman } = await import('node:crypto')

// Generiere Alices Schlüssel...
const alice = createDiffieHellman(2048)
const aliceKey = alice.generateKeys()

// Generiere Bobs Schlüssel...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator())
const bobKey = bob.generateKeys()

// Austausch und Generierung des Geheimnisses...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

// OK
assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'))
js
const assert = require('node:assert')

const { createDiffieHellman } = require('node:crypto')

// Generiere Alices Schlüssel...
const alice = createDiffieHellman(2048)
const aliceKey = alice.generateKeys()

// Generiere Bobs Schlüssel...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator())
const bobKey = bob.generateKeys()

// Austausch und Generierung des Geheimnisses...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

// OK
assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'))

diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding]) ​

Hinzugefügt in: v0.5.0

Berechnet das gemeinsame Geheimnis unter Verwendung von otherPublicKey als öffentlichem Schlüssel der anderen Partei und gibt das berechnete gemeinsame Geheimnis zurück. Der angegebene Schlüssel wird unter Verwendung der angegebenen inputEncoding interpretiert, und das Geheimnis wird unter Verwendung der angegebenen outputEncoding kodiert. Wenn inputEncoding nicht angegeben ist, wird erwartet, dass otherPublicKey ein Buffer, TypedArray oder DataView ist.

Wenn outputEncoding angegeben ist, wird eine Zeichenkette zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

diffieHellman.generateKeys([encoding]) ​

Hinzugefügt in: v0.5.0

Generiert private und öffentliche Diffie-Hellman-Schlüsselwerte, sofern diese nicht bereits generiert oder berechnet wurden, und gibt den öffentlichen Schlüssel in der angegebenen encoding zurück. Dieser Schlüssel sollte an die andere Partei übertragen werden. Wenn encoding angegeben wird, wird eine Zeichenkette zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

Diese Funktion ist ein dünner Wrapper um DH_generate_key(). Insbesondere wird nach der Generierung oder Festlegung eines privaten Schlüssels durch Aufrufen dieser Funktion nur der öffentliche Schlüssel aktualisiert, aber kein neuer privater Schlüssel generiert.

diffieHellman.getGenerator([encoding]) ​

Hinzugefügt in: v0.5.0

Gibt den Diffie-Hellman-Generator in der angegebenen encoding zurück. Wenn encoding angegeben wird, wird eine Zeichenkette zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

diffieHellman.getPrime([encoding]) ​

Hinzugefügt in: v0.5.0

Gibt die Diffie-Hellman-Primzahl in der angegebenen encoding zurück. Wenn encoding angegeben wird, wird eine Zeichenkette zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

diffieHellman.getPrivateKey([encoding]) ​

Hinzugefügt in: v0.5.0

Gibt den Diffie-Hellman-Privatschlüssel in der angegebenen encoding zurück. Wenn encoding angegeben ist, wird eine Zeichenkette zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

diffieHellman.getPublicKey([encoding]) ​

Hinzugefügt in: v0.5.0

Gibt den Diffie-Hellman-öffentlichen Schlüssel in der angegebenen encoding zurück. Wenn encoding angegeben ist, wird eine Zeichenkette zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

diffieHellman.setPrivateKey(privateKey[, encoding]) ​

Hinzugefügt in: v0.5.0

Setzt den Diffie-Hellman-Privatschlüssel. Wenn das Argument encoding angegeben ist, wird erwartet, dass privateKey eine Zeichenkette ist. Wenn kein encoding angegeben ist, wird erwartet, dass privateKey ein Buffer, TypedArray oder DataView ist.

Diese Funktion berechnet den zugehörigen öffentlichen Schlüssel nicht automatisch. Entweder diffieHellman.setPublicKey() oder diffieHellman.generateKeys() können verwendet werden, um den öffentlichen Schlüssel manuell anzugeben oder ihn automatisch abzuleiten.

diffieHellman.setPublicKey(publicKey[, encoding]) ​

Hinzugefügt in: v0.5.0

Setzt den öffentlichen Diffie-Hellman-Schlüssel. Wenn das Argument encoding angegeben wird, wird erwartet, dass publicKey ein String ist. Wenn keine encoding angegeben wird, wird erwartet, dass publicKey ein Buffer, TypedArray oder DataView ist.

diffieHellman.verifyError ​

Hinzugefügt in: v0.11.12

Ein Bitfeld, das alle Warnungen und/oder Fehler enthält, die sich aus einer Prüfung ergeben, die während der Initialisierung des DiffieHellman-Objekts durchgeführt wurde.

Die folgenden Werte sind für diese Eigenschaft gültig (wie im Modul node:constants definiert):

  • DH_CHECK_P_NOT_SAFE_PRIME
  • DH_CHECK_P_NOT_PRIME
  • DH_UNABLE_TO_CHECK_GENERATOR
  • DH_NOT_SUITABLE_GENERATOR

Klasse: DiffieHellmanGroup ​

Hinzugefügt in: v0.7.5

Die Klasse DiffieHellmanGroup verwendet eine bekannte modp-Gruppe als Argument. Sie funktioniert genauso wie DiffieHellman, außer dass sie keine Änderung ihrer Schlüssel nach der Erstellung zulässt. Mit anderen Worten, sie implementiert keine Methoden setPublicKey() oder setPrivateKey().

js
const { createDiffieHellmanGroup } = await import('node:crypto')
const dh = createDiffieHellmanGroup('modp16')
js
const { createDiffieHellmanGroup } = require('node:crypto')
const dh = createDiffieHellmanGroup('modp16')

Die folgenden Gruppen werden unterstützt:

  • 'modp14' (2048 Bit, RFC 3526 Abschnitt 3)
  • 'modp15' (3072 Bit, RFC 3526 Abschnitt 4)
  • 'modp16' (4096 Bit, RFC 3526 Abschnitt 5)
  • 'modp17' (6144 Bit, RFC 3526 Abschnitt 6)
  • 'modp18' (8192 Bit, RFC 3526 Abschnitt 7)

Die folgenden Gruppen werden noch unterstützt, sind aber veraltet (siehe Warnungen):

  • 'modp1' (768 Bit, RFC 2409 Abschnitt 6.1)
  • 'modp2' (1024 Bit, RFC 2409 Abschnitt 6.2)
  • 'modp5' (1536 Bit, RFC 3526 Abschnitt 2)

Diese veralteten Gruppen werden möglicherweise in zukünftigen Versionen von Node.js entfernt.

Klasse: ECDH ​

Hinzugefügt in: v0.11.14

Die Klasse ECDH ist ein Dienstprogramm zum Erstellen von Elliptic Curve Diffie-Hellman (ECDH)-Schlüsselaustauschen.

Instanzen der Klasse ECDH können mit der Funktion crypto.createECDH() erstellt werden.

js
import assert from 'node:assert'

const { createECDH } = await import('node:crypto')

// Generiere Alices Schlüssel...
const alice = createECDH('secp521r1')
const aliceKey = alice.generateKeys()

// Generiere Bobs Schlüssel...
const bob = createECDH('secp521r1')
const bobKey = bob.generateKeys()

// Austausch und Generierung des Geheimnisses...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'))
// OK
js
const assert = require('node:assert')

const { createECDH } = require('node:crypto')

// Generiere Alices Schlüssel...
const alice = createECDH('secp521r1')
const aliceKey = alice.generateKeys()

// Generiere Bobs Schlüssel...
const bob = createECDH('secp521r1')
const bobKey = bob.generateKeys()

// Austausch und Generierung des Geheimnisses...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'))
// OK

Statische Methode: ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]]) ​

Hinzugefügt in: v10.0.0

Konvertiert den durch key und curve angegebenen EC Diffie-Hellman öffentlichen Schlüssel in das durch format angegebene Format. Das Argument format gibt die Punktkodierung an und kann 'compressed', 'uncompressed' oder 'hybrid' sein. Der angegebene Schlüssel wird mit der angegebenen inputEncoding interpretiert, und der zurückgegebene Schlüssel wird mit der angegebenen outputEncoding kodiert.

Verwenden Sie crypto.getCurves(), um eine Liste der verfügbaren Kurvennamen zu erhalten. Bei neueren OpenSSL-Versionen zeigt openssl ecparam -list_curves auch den Namen und die Beschreibung jeder verfügbaren elliptischen Kurve an.

Wenn format nicht angegeben ist, wird der Punkt im Format 'uncompressed' zurückgegeben.

Wenn inputEncoding nicht angegeben ist, wird erwartet, dass key ein Buffer, TypedArray oder DataView ist.

Beispiel (Entkomprimieren eines Schlüssels):

js
const { createECDH, ECDH } = await import('node:crypto')

const ecdh = createECDH('secp256k1')
ecdh.generateKeys()

const compressedKey = ecdh.getPublicKey('hex', 'compressed')

const uncompressedKey = ECDH.convertKey(compressedKey, 'secp256k1', 'hex', 'hex', 'uncompressed')

// Der konvertierte Schlüssel und der unkomprimierte öffentliche Schlüssel sollten gleich sein
console.log(uncompressedKey === ecdh.getPublicKey('hex'))
js
const { createECDH, ECDH } = require('node:crypto')

const ecdh = createECDH('secp256k1')
ecdh.generateKeys()

const compressedKey = ecdh.getPublicKey('hex', 'compressed')

const uncompressedKey = ECDH.convertKey(compressedKey, 'secp256k1', 'hex', 'hex', 'uncompressed')

// Der konvertierte Schlüssel und der unkomprimierte öffentliche Schlüssel sollten gleich sein
console.log(uncompressedKey === ecdh.getPublicKey('hex'))

ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding]) ​

[Verlauf]

VersionÄnderungen
v10.0.0Fehlerformat geändert, um ungültige Public-Key-Fehler besser zu unterstützen.
v6.0.0Die Standardeinstellung von inputEncoding wurde von binary zu utf8 geändert.
v0.11.14Hinzugefügt in: v0.11.14

Berechnet das geteilte Geheimnis unter Verwendung von otherPublicKey als Public Key der Gegenseite und gibt das berechnete geteilte Geheimnis zurück. Der angegebene Schlüssel wird unter Verwendung der angegebenen inputEncoding interpretiert, und das zurückgegebene Geheimnis wird unter Verwendung der angegebenen outputEncoding kodiert. Wenn inputEncoding nicht angegeben wird, wird erwartet, dass otherPublicKey ein Buffer, TypedArray oder DataView ist.

Wenn outputEncoding einen String erhält, wird ein String zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

ecdh.computeSecret löst einen ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY-Fehler aus, wenn otherPublicKey außerhalb der elliptischen Kurve liegt. Da otherPublicKey normalerweise von einem entfernten Benutzer über ein unsicheres Netzwerk bereitgestellt wird, sollte diese Ausnahme entsprechend behandelt werden.

ecdh.generateKeys([encoding[, format]]) ​

Hinzugefügt in: v0.11.14

Generiert private und öffentliche EC Diffie-Hellman Schlüsselwerte und gibt den öffentlichen Schlüssel im angegebenen format und encoding zurück. Dieser Schlüssel sollte an die andere Partei übertragen werden.

Das Argument format gibt die Punktkodierung an und kann 'compressed' oder 'uncompressed' sein. Wenn format nicht angegeben ist, wird der Punkt im Format 'uncompressed' zurückgegeben.

Wenn encoding angegeben ist, wird eine Zeichenkette zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

ecdh.getPrivateKey([encoding]) ​

Hinzugefügt in: v0.11.14

Wenn encoding angegeben ist, wird eine Zeichenkette zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

ecdh.getPublicKey([encoding][, format]) ​

Hinzugefügt in: v0.11.14

  • encoding <string> Die Kodierung des Rückgabewerts.
  • format <string> Standard: 'uncompressed'
  • Rückgabewert: <Buffer> | <string> Der öffentliche EC Diffie-Hellman Schlüssel in der angegebenen encoding und format.

Das Argument format gibt die Punktkodierung an und kann 'compressed' oder 'uncompressed' sein. Wenn format nicht angegeben ist, wird der Punkt im Format 'uncompressed' zurückgegeben.

Wenn encoding angegeben ist, wird eine Zeichenkette zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

ecdh.setPrivateKey(privateKey[, encoding]) ​

Hinzugefügt in: v0.11.14

Legt den privaten EC Diffie-Hellman-Schlüssel fest. Wenn encoding angegeben ist, wird erwartet, dass privateKey ein String ist; andernfalls wird erwartet, dass privateKey ein Buffer, TypedArray oder DataView ist.

Wenn privateKey für die beim Erstellen des ECDH-Objekts angegebene Kurve ungültig ist, wird ein Fehler ausgelöst. Nach dem Festlegen des privaten Schlüssels wird der zugehörige öffentliche Punkt (Schlüssel) ebenfalls generiert und im ECDH-Objekt gesetzt.

ecdh.setPublicKey(publicKey[, encoding]) ​

Hinzugefügt in: v0.11.14

Veraltet seit: v5.2.0

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet

Legt den öffentlichen EC Diffie-Hellman-Schlüssel fest. Wenn encoding angegeben ist, wird erwartet, dass publicKey ein String ist; andernfalls wird ein Buffer, TypedArray oder DataView erwartet.

Es gibt normalerweise keinen Grund, diese Methode aufzurufen, da ECDH nur einen privaten Schlüssel und den öffentlichen Schlüssel der anderen Partei benötigt, um das gemeinsame Geheimnis zu berechnen. Normalerweise wird entweder ecdh.generateKeys() oder ecdh.setPrivateKey() aufgerufen. Die Methode ecdh.setPrivateKey() versucht, den öffentlichen Punkt/Schlüssel zu generieren, der dem festgelegten privaten Schlüssel zugeordnet ist.

Beispiel (Erhalten eines gemeinsamen Geheimnisses):

js
const { createECDH, createHash } = await import('node:crypto')

const alice = createECDH('secp256k1')
const bob = createECDH('secp256k1')

// Dies ist eine Abkürzung zur Angabe eines der vorherigen privaten Schlüssel von Alice.
// Es wäre unklug, einen so vorhersehbaren privaten Schlüssel in einer realen Anwendung zu verwenden.
alice.setPrivateKey(createHash('sha256').update('alice', 'utf8').digest())

// Bob verwendet ein neu generiertes kryptografisch starkes
// pseudorandomes Schlüsselpaar
bob.generateKeys()

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex')
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex')

// aliceSecret und bobSecret sollten den gleichen Wert des gemeinsamen Geheimnisses haben
console.log(aliceSecret === bobSecret)
js
const { createECDH, createHash } = require('node:crypto')

const alice = createECDH('secp256k1')
const bob = createECDH('secp256k1')

// Dies ist eine Abkürzung zur Angabe eines der vorherigen privaten Schlüssel von Alice.
// Es wäre unklug, einen so vorhersehbaren privaten Schlüssel in einer realen Anwendung zu verwenden.
alice.setPrivateKey(createHash('sha256').update('alice', 'utf8').digest())

// Bob verwendet ein neu generiertes kryptografisch starkes
// pseudorandomes Schlüsselpaar
bob.generateKeys()

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex')
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex')

// aliceSecret und bobSecret sollten den gleichen Wert des gemeinsamen Geheimnisses haben
console.log(aliceSecret === bobSecret)

Klasse: Hash ​

Hinzugefügt in: v0.1.92

Die Klasse Hash ist ein Dienstprogramm zum Erstellen von Hash-Digests von Daten. Sie kann auf zwei Arten verwendet werden:

  • Als Stream, der sowohl lesbar als auch beschreibbar ist, wobei Daten geschrieben werden, um einen berechneten Hash-Digest auf der lesbaren Seite zu erzeugen, oder
  • Mit den Methoden hash.update() und hash.digest(), um den berechneten Hash zu erzeugen.

Die Methode crypto.createHash() wird verwendet, um Hash-Instanzen zu erstellen. Hash-Objekte dürfen nicht direkt mit dem Schlüsselwort new erstellt werden.

Beispiel: Verwenden von Hash-Objekten als Streams:

js
const { createHash } = await import('node:crypto')

const hash = createHash('sha256')

hash.on('readable', () => {
  // Nur ein Element wird vom
  // Hash-Stream erzeugt.
  const data = hash.read()
  if (data) {
    console.log(data.toString('hex'))
    // Gibt aus:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
})

hash.write('some data to hash')
hash.end()
js
const { createHash } = require('node:crypto')

const hash = createHash('sha256')

hash.on('readable', () => {
  // Nur ein Element wird vom
  // Hash-Stream erzeugt.
  const data = hash.read()
  if (data) {
    console.log(data.toString('hex'))
    // Gibt aus:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
})

hash.write('some data to hash')
hash.end()

Beispiel: Verwenden von Hash und gepipeteten Streams:

js
import { createReadStream } from 'node:fs'
import { stdout } from 'node:process'
const { createHash } = await import('node:crypto')

const hash = createHash('sha256')

const input = createReadStream('test.js')
input.pipe(hash).setEncoding('hex').pipe(stdout)
js
const { createReadStream } = require('node:fs')
const { createHash } = require('node:crypto')
const { stdout } = require('node:process')

const hash = createHash('sha256')

const input = createReadStream('test.js')
input.pipe(hash).setEncoding('hex').pipe(stdout)

Beispiel: Verwenden der Methoden hash.update() und hash.digest():

js
const { createHash } = await import('node:crypto')

const hash = createHash('sha256')

hash.update('some data to hash')
console.log(hash.digest('hex'))
// Gibt aus:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
js
const { createHash } = require('node:crypto')

const hash = createHash('sha256')

hash.update('some data to hash')
console.log(hash.digest('hex'))
// Gibt aus:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50

hash.copy([options]) ​

Hinzugefügt in: v13.1.0

Erstellt ein neues Hash-Objekt, das eine tiefe Kopie des internen Zustands des aktuellen Hash-Objekts enthält.

Das optionale Argument options steuert das Stream-Verhalten. Für XOF-Hash-Funktionen wie 'shake256' kann die Option outputLength verwendet werden, um die gewünschte Ausgabelänge in Bytes anzugeben.

Es wird ein Fehler ausgelöst, wenn versucht wird, das Hash-Objekt zu kopieren, nachdem seine Methode hash.digest() aufgerufen wurde.

js
// Berechnung eines gleitenden Hash-Werts.
const { createHash } = await import('node:crypto')

const hash = createHash('sha256')

hash.update('one')
console.log(hash.copy().digest('hex'))

hash.update('two')
console.log(hash.copy().digest('hex'))

hash.update('three')
console.log(hash.copy().digest('hex'))

// usw.
js
// Berechnung eines gleitenden Hash-Werts.
const { createHash } = require('node:crypto')

const hash = createHash('sha256')

hash.update('one')
console.log(hash.copy().digest('hex'))

hash.update('two')
console.log(hash.copy().digest('hex'))

hash.update('three')
console.log(hash.copy().digest('hex'))

// usw.

hash.digest([encoding]) ​

Hinzugefügt in: v0.1.92

Berechnet den Digest aller Daten, die zum Hashen übergeben wurden (mit der Methode hash.update()). Wenn encoding angegeben ist, wird eine Zeichenkette zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

Das Hash-Objekt kann nach dem Aufruf der Methode hash.digest() nicht mehr verwendet werden. Mehrere Aufrufe führen zu einem Fehler.

hash.update(data[, inputEncoding]) ​

[Verlauf]

VersionÄnderungen
v6.0.0Die Standardcodierung von inputEncoding wurde von binary auf utf8 geändert.
v0.1.92Hinzugefügt in: v0.1.92

Aktualisiert den Hash-Inhalt mit den gegebenen data, deren Codierung in inputEncoding angegeben ist. Wenn encoding nicht angegeben ist und data eine Zeichenkette ist, wird eine Codierung von 'utf8' erzwungen. Wenn data ein Buffer, TypedArray oder DataView ist, wird inputEncoding ignoriert.

Dies kann mehrmals mit neuen Daten aufgerufen werden, während diese gestreamt werden.

Klasse: Hmac ​

Hinzugefügt in: v0.1.94

Die Hmac-Klasse ist ein Dienstprogramm zum Erstellen kryptografischer HMAC-Digests. Sie kann auf zwei Arten verwendet werden:

  • Als Stream, der sowohl lesbar als auch beschreibbar ist, wobei Daten geschrieben werden, um einen berechneten HMAC-Digest auf der lesbaren Seite zu erzeugen, oder
  • Mit den Methoden hmac.update() und hmac.digest(), um den berechneten HMAC-Digest zu erzeugen.

Die Methode crypto.createHmac() wird verwendet, um Hmac-Instanzen zu erstellen. Hmac-Objekte dürfen nicht direkt mit dem Schlüsselwort new erstellt werden.

Beispiel: Verwenden von Hmac-Objekten als Streams:

js
const { createHmac } = await import('node:crypto')

const hmac = createHmac('sha256', 'a secret')

hmac.on('readable', () => {
  // Nur ein Element wird vom
  // Hash-Stream erzeugt.
  const data = hmac.read()
  if (data) {
    console.log(data.toString('hex'))
    // Gibt aus:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
})

hmac.write('some data to hash')
hmac.end()
js
const { createHmac } = require('node:crypto')

const hmac = createHmac('sha256', 'a secret')

hmac.on('readable', () => {
  // Nur ein Element wird vom
  // Hash-Stream erzeugt.
  const data = hmac.read()
  if (data) {
    console.log(data.toString('hex'))
    // Gibt aus:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
})

hmac.write('some data to hash')
hmac.end()

Beispiel: Verwenden von Hmac und gepipeteten Streams:

js
import { createReadStream } from 'node:fs'
import { stdout } from 'node:process'
const { createHmac } = await import('node:crypto')

const hmac = createHmac('sha256', 'a secret')

const input = createReadStream('test.js')
input.pipe(hmac).pipe(stdout)
js
const { createReadStream } = require('node:fs')
const { createHmac } = require('node:crypto')
const { stdout } = require('node:process')

const hmac = createHmac('sha256', 'a secret')

const input = createReadStream('test.js')
input.pipe(hmac).pipe(stdout)

Beispiel: Verwenden der Methoden hmac.update() und hmac.digest():

js
const { createHmac } = await import('node:crypto')

const hmac = createHmac('sha256', 'a secret')

hmac.update('some data to hash')
console.log(hmac.digest('hex'))
// Gibt aus:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
js
const { createHmac } = require('node:crypto')

const hmac = createHmac('sha256', 'a secret')

hmac.update('some data to hash')
console.log(hmac.digest('hex'))
// Gibt aus:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e

hmac.digest([encoding]) ​

Hinzugefügt in: v0.1.94

Berechnet den HMAC-Digest aller übergebenen Daten mittels hmac.update(). Wenn encoding angegeben ist, wird eine Zeichenkette zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

Das Hmac-Objekt kann nach dem Aufruf von hmac.digest() nicht mehr verwendet werden. Mehrfache Aufrufe von hmac.digest() führen zu einem Fehler.

hmac.update(data[, inputEncoding]) ​

[Versionsgeschichte]

VersionÄnderungen
v6.0.0Die Standard inputEncoding wurde von binary zu utf8 geändert.
v0.1.94Hinzugefügt in: v0.1.94

Aktualisiert den Hmac-Inhalt mit den gegebenen data, deren Kodierung in inputEncoding angegeben ist. Wenn encoding nicht angegeben ist und data eine Zeichenkette ist, wird die Kodierung 'utf8' erzwungen. Wenn data ein Buffer, TypedArray oder DataView ist, wird inputEncoding ignoriert.

Dies kann mehrmals mit neuen Daten aufgerufen werden, während diese gestreamt werden.

Klasse: KeyObject ​

[Versionsgeschichte]

VersionÄnderungen
v14.5.0, v12.19.0Instanzen dieser Klasse können nun mithilfe von postMessage an Worker-Threads übergeben werden.
v11.13.0Diese Klasse wird nun exportiert.
v11.6.0Hinzugefügt in: v11.6.0

Node.js verwendet eine KeyObject-Klasse, um einen symmetrischen oder asymmetrischen Schlüssel darzustellen, und jede Art von Schlüssel stellt unterschiedliche Funktionen bereit. Die Methoden crypto.createSecretKey(), crypto.createPublicKey() und crypto.createPrivateKey() werden verwendet, um KeyObject-Instanzen zu erstellen. KeyObject-Objekte dürfen nicht direkt mit dem Schlüsselwort new erstellt werden.

Die meisten Anwendungen sollten die neue KeyObject-API anstelle der Übergabe von Schlüsseln als Zeichenketten oder Buffers verwenden, da dies verbesserte Sicherheitsfunktionen bietet.

KeyObject-Instanzen können über postMessage() an andere Threads übergeben werden. Der Empfänger erhält ein geklontes KeyObject, und das KeyObject muss nicht in dem Argument transferList aufgeführt werden.

Statische Methode: KeyObject.from(key) ​

Hinzugefügt in: v15.0.0

Beispiel: Konvertieren einer CryptoKey-Instanz in ein KeyObject:

js
const { KeyObject } = await import('node:crypto')
const { subtle } = globalThis.crypto

const key = await subtle.generateKey(
  {
    name: 'HMAC',
    hash: 'SHA-256',
    length: 256,
  },
  true,
  ['sign', 'verify']
)

const keyObject = KeyObject.from(key)
console.log(keyObject.symmetricKeySize)
// Gibt aus: 32 (symmetrische Schlüssellänge in Bytes)
js
const { KeyObject } = require('node:crypto')
const { subtle } = globalThis.crypto

;(async function () {
  const key = await subtle.generateKey(
    {
      name: 'HMAC',
      hash: 'SHA-256',
      length: 256,
    },
    true,
    ['sign', 'verify']
  )

  const keyObject = KeyObject.from(key)
  console.log(keyObject.symmetricKeySize)
  // Gibt aus: 32 (symmetrische Schlüssellänge in Bytes)
})()

keyObject.asymmetricKeyDetails ​

[Verlauf]

VersionÄnderungen
v16.9.0RSASSA-PSS-params Sequenzparameter für RSA-PSS-Schlüssel freigeben.
v15.7.0Hinzugefügt in: v15.7.0
  • <Object>
    • modulusLength: <number> Schlüssellänge in Bits (RSA, DSA).
    • publicExponent: <bigint> Öffentlicher Exponent (RSA).
    • hashAlgorithm: <string> Name des Message Digest (RSA-PSS).
    • mgf1HashAlgorithm: <string> Name des von MGF1 verwendeten Message Digest (RSA-PSS).
    • saltLength: <number> Minimale Saltlänge in Bytes (RSA-PSS).
    • divisorLength: <number> Größe von q in Bits (DSA).
    • namedCurve: <string> Name der Kurve (EC).

Diese Eigenschaft existiert nur bei asymmetrischen Schlüsseln. Je nach Schlüsseltyp enthält dieses Objekt Informationen über den Schlüssel. Keine der über diese Eigenschaft erhaltenen Informationen kann verwendet werden, um einen Schlüssel eindeutig zu identifizieren oder die Sicherheit des Schlüssels zu gefährden.

Bei RSA-PSS-Schlüsseln werden die Eigenschaften hashAlgorithm, mgf1HashAlgorithm und saltLength gesetzt, wenn das Schlüsselmaterial eine RSASSA-PSS-params-Sequenz enthält.

Weitere Schlüsseldetails können über diese API mit zusätzlichen Attributen verfügbar gemacht werden.

keyObject.asymmetricKeyType ​

[Verlauf]

VersionÄnderungen
v13.9.0, v12.17.0Unterstützung für 'dh' hinzugefügt.
v12.0.0Unterstützung für 'rsa-pss' hinzugefügt.
v12.0.0Diese Eigenschaft gibt nun undefined für KeyObject-Instanzen unbekannten Typs zurück, anstatt abzubrechen.
v12.0.0Unterstützung für 'x25519' und 'x448' hinzugefügt.
v12.0.0Unterstützung für 'ed25519' und 'ed448' hinzugefügt.
v11.6.0Hinzugefügt in: v11.6.0

Für asymmetrische Schlüssel repräsentiert diese Eigenschaft den Typ des Schlüssels. Unterstützte Schlüsseltypen sind:

  • 'rsa' (OID 1.2.840.113549.1.1.1)
  • 'rsa-pss' (OID 1.2.840.113549.1.1.10)
  • 'dsa' (OID 1.2.840.10040.4.1)
  • 'ec' (OID 1.2.840.10045.2.1)
  • 'x25519' (OID 1.3.101.110)
  • 'x448' (OID 1.3.101.111)
  • 'ed25519' (OID 1.3.101.112)
  • 'ed448' (OID 1.3.101.113)
  • 'dh' (OID 1.2.840.113549.1.3.1)

Diese Eigenschaft ist undefined für nicht erkannte KeyObject-Typen und symmetrische Schlüssel.

keyObject.equals(otherKeyObject) ​

Hinzugefügt in: v17.7.0, v16.15.0

  • otherKeyObject: <KeyObject> Ein KeyObject, mit dem keyObject verglichen werden soll.
  • Gibt zurück: <boolean>

Gibt true oder false zurück, je nachdem, ob die Schlüssel exakt den gleichen Typ, Wert und die gleichen Parameter haben. Diese Methode ist nicht konstante Zeit.

keyObject.export([options]) ​

[Verlauf]

VersionÄnderungen
v15.9.0Unterstützung für das Format 'jwk' hinzugefügt.
v11.6.0Hinzugefügt in: v11.6.0

Für symmetrische Schlüssel können die folgenden Codierungsoptionen verwendet werden:

  • format: <string> Muss 'buffer' (Standard) oder 'jwk' sein.

Für öffentliche Schlüssel können die folgenden Codierungsoptionen verwendet werden:

  • type: <string> Muss einer von 'pkcs1' (nur RSA) oder 'spki' sein.
  • format: <string> Muss 'pem', 'der' oder 'jwk' sein.

Für private Schlüssel können die folgenden Codierungsoptionen verwendet werden:

  • type: <string> Muss einer von 'pkcs1' (nur RSA), 'pkcs8' oder 'sec1' (nur EC) sein.
  • format: <string> Muss 'pem', 'der' oder 'jwk' sein.
  • cipher: <string> Wenn angegeben, wird der private Schlüssel mit dem angegebenen cipher und passphrase unter Verwendung der passwortbasierten Verschlüsselung nach PKCS#5 v2.0 verschlüsselt.
  • passphrase: <string> | <Buffer> Die Passphrase, die für die Verschlüsselung verwendet werden soll, siehe cipher.

Der Ergebnistyp hängt vom ausgewählten Codierungsformat ab: Bei PEM ist das Ergebnis eine Zeichenkette, bei DER ein Puffer, der die als DER codierten Daten enthält, bei JWK ein Objekt.

Wenn das Codierungsformat JWK ausgewählt wurde, werden alle anderen Codierungsoptionen ignoriert.

PKCS#1-, SEC1- und PKCS#8-Schlüssel können durch eine Kombination der Optionen cipher und format verschlüsselt werden. Der Typ PKCS#8 kann mit jedem format verwendet werden, um jeden Schlüsselalgorithmus (RSA, EC oder DH) zu verschlüsseln, indem ein cipher angegeben wird. PKCS#1 und SEC1 können nur verschlüsselt werden, indem ein cipher angegeben wird, wenn das Format PEM verwendet wird. Für maximale Kompatibilität verwenden Sie PKCS#8 für verschlüsselte private Schlüssel. Da PKCS#8 seinen eigenen Verschlüsselungsmechanismus definiert, wird die PEM-Verschlüsselung bei der Verschlüsselung eines PKCS#8-Schlüssels nicht unterstützt. Siehe RFC 5208 für die PKCS#8-Verschlüsselung und RFC 1421 für die PKCS#1- und SEC1-Verschlüsselung.

keyObject.symmetricKeySize ​

Hinzugefügt in: v11.6.0

Für geheime Schlüssel repräsentiert diese Eigenschaft die Größe des Schlüssels in Bytes. Diese Eigenschaft ist für asymmetrische Schlüssel undefined.

keyObject.toCryptoKey(algorithm, extractable, keyUsages) ​

Hinzugefügt in: v23.0.0

Konvertiert eine KeyObject-Instanz in einen CryptoKey.

keyObject.type ​

Hinzugefügt in: v11.6.0

Abhängig vom Typ dieses KeyObject ist diese Eigenschaft entweder 'secret' für geheime (symmetrische) Schlüssel, 'public' für öffentliche (asymmetrische) Schlüssel oder 'private' für private (asymmetrische) Schlüssel.

Klasse: Sign ​

Hinzugefügt in: v0.1.92

Die Klasse Sign ist ein Dienstprogramm zum Generieren von Signaturen. Sie kann auf zwei Arten verwendet werden:

  • Als beschreibbarer Stream, in den die zu signierenden Daten geschrieben werden und die Methode sign.sign() verwendet wird, um die Signatur zu generieren und zurückzugeben, oder
  • Mit den Methoden sign.update() und sign.sign() zur Erstellung der Signatur.

Die Methode crypto.createSign() wird verwendet, um Sign-Instanzen zu erstellen. Das Argument ist der String-Name der zu verwendenden Hash-Funktion. Sign-Objekte dürfen nicht direkt mit dem Schlüsselwort new erstellt werden.

Beispiel: Verwenden von Sign- und Verify-Objekten als Streams:

js
const { generateKeyPairSync, createSign, createVerify } = await import('node:crypto')

const { privateKey, publicKey } = generateKeyPairSync('ec', {
  namedCurve: 'sect239k1',
})

const sign = createSign('SHA256')
sign.write('some data to sign')
sign.end()
const signature = sign.sign(privateKey, 'hex')

const verify = createVerify('SHA256')
verify.write('some data to sign')
verify.end()
console.log(verify.verify(publicKey, signature, 'hex'))
// Gibt aus: true
js
const { generateKeyPairSync, createSign, createVerify } = require('node:crypto')

const { privateKey, publicKey } = generateKeyPairSync('ec', {
  namedCurve: 'sect239k1',
})

const sign = createSign('SHA256')
sign.write('some data to sign')
sign.end()
const signature = sign.sign(privateKey, 'hex')

const verify = createVerify('SHA256')
verify.write('some data to sign')
verify.end()
console.log(verify.verify(publicKey, signature, 'hex'))
// Gibt aus: true

Beispiel: Verwenden der Methoden sign.update() und verify.update():

js
const { generateKeyPairSync, createSign, createVerify } = await import('node:crypto')

const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
})

const sign = createSign('SHA256')
sign.update('some data to sign')
sign.end()
const signature = sign.sign(privateKey)

const verify = createVerify('SHA256')
verify.update('some data to sign')
verify.end()
console.log(verify.verify(publicKey, signature))
// Gibt aus: true
js
const { generateKeyPairSync, createSign, createVerify } = require('node:crypto')

const { privateKey, publicKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
})

const sign = createSign('SHA256')
sign.update('some data to sign')
sign.end()
const signature = sign.sign(privateKey)

const verify = createVerify('SHA256')
verify.update('some data to sign')
verify.end()
console.log(verify.verify(publicKey, signature))
// Gibt aus: true

sign.sign(privateKey[, outputEncoding]) ​

[Verlauf]

VersionÄnderungen
v15.0.0privateKey kann nun auch ein ArrayBuffer und CryptoKey sein.
v13.2.0, v12.16.0Diese Funktion unterstützt jetzt IEEE-P1363 DSA und ECDSA Signaturen.
v12.0.0Diese Funktion unterstützt jetzt RSA-PSS Schlüssel.
v11.6.0Diese Funktion unterstützt jetzt Schlüssel Objekte.
v8.0.0Unterstützung für RSASSA-PSS und zusätzliche Optionen wurde hinzugefügt.
v0.1.92Hinzugefügt in: v0.1.92

Berechnet die Signatur aller übertragenen Daten mit entweder sign.update() oder sign.write().

Wenn privateKey kein KeyObject ist, verhält sich diese Funktion so, als wäre privateKey an crypto.createPrivateKey() übergeben worden. Handelt es sich um ein Objekt, können die folgenden zusätzlichen Eigenschaften übergeben werden:

  • dsaEncoding <Zeichenkette> Für DSA und ECDSA gibt diese Option das Format der generierten Signatur an. Es kann einer der folgenden Werte sein:

    • 'der' (Standard): DER-codierte ASN.1 Signaturstrukturkodierung (r, s).
    • 'ieee-p1363': Signaturformat r || s wie in IEEE-P1363 vorgeschlagen.

  • padding <Ganzzahl> Optionaler Padding-Wert für RSA, einer der folgenden:

    • crypto.constants.RSA_PKCS1_PADDING (Standard)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

RSA_PKCS1_PSS_PADDING verwendet MGF1 mit der gleichen Hash-Funktion, die zum Signieren der Nachricht verwendet wird, wie in Abschnitt 3.1 von RFC 4055 angegeben, es sei denn, eine MGF1-Hash-Funktion wurde als Teil des Schlüssels gemäß Abschnitt 3.3 von RFC 4055 angegeben.

  • saltLength <Ganzzahl> Salzlänge, wenn Padding RSA_PKCS1_PSS_PADDING ist. Der spezielle Wert crypto.constants.RSA_PSS_SALTLEN_DIGEST setzt die Salzlänge auf die Digest-Größe, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (Standard) setzt sie auf den maximal zulässigen Wert.

Wenn outputEncoding angegeben wird, wird eine Zeichenkette zurückgegeben; andernfalls wird ein Buffer zurückgegeben.

Das Sign-Objekt kann nach dem Aufruf der Methode sign.sign() nicht mehr verwendet werden. Mehrfache Aufrufe von sign.sign() führen zu einem Fehler.

sign.update(data[, inputEncoding]) ​

[History]

VersionÄnderungen
v6.0.0Die Standardcodierung von inputEncoding wurde von binary auf utf8 geändert.
v0.1.92Hinzugefügt in: v0.1.92

Aktualisiert den Sign-Inhalt mit den gegebenen data, deren Codierung in inputEncoding angegeben ist. Wenn encoding nicht angegeben ist und data eine Zeichenkette ist, wird die Codierung 'utf8' erzwungen. Wenn data ein Buffer, TypedArray oder DataView ist, wird inputEncoding ignoriert.

Dies kann mehrmals mit neuen Daten aufgerufen werden, während diese gestreamt werden.

Klasse: Verify ​

Hinzugefügt in: v0.1.92

Die Klasse Verify ist ein Dienstprogramm zum Überprüfen von Signaturen. Sie kann auf zwei Arten verwendet werden:

  • Als beschreibbarer Stream, wobei die geschriebenen Daten verwendet werden, um die bereitgestellte Signatur zu validieren, oder
  • Mit den Methoden verify.update() und verify.verify() zum Überprüfen der Signatur.

Die Methode crypto.createVerify() wird verwendet, um Verify-Instanzen zu erstellen. Verify-Objekte dürfen nicht direkt mit dem Schlüsselwort new erstellt werden.

Siehe Sign für Beispiele.

verify.update(data[, inputEncoding]) ​

[History]

VersionÄnderungen
v6.0.0Die Standardcodierung von inputEncoding wurde von binary auf utf8 geändert.
v0.1.92Hinzugefügt in: v0.1.92

Aktualisiert den Verify-Inhalt mit den gegebenen data, deren Codierung in inputEncoding angegeben ist. Wenn inputEncoding nicht angegeben ist und data eine Zeichenkette ist, wird die Codierung 'utf8' erzwungen. Wenn data ein Buffer, TypedArray oder DataView ist, wird inputEncoding ignoriert.

Dies kann mehrmals mit neuen Daten aufgerufen werden, während diese gestreamt werden.

verify.verify(object, signature[, signatureEncoding]) ​

[Versionsgeschichte]

VersionÄnderungen
v15.0.0Das Objekt kann auch ein ArrayBuffer und CryptoKey sein.
v13.2.0, v12.16.0Diese Funktion unterstützt jetzt IEEE-P1363 DSA- und ECDSA-Signaturen.
v12.0.0Diese Funktion unterstützt jetzt RSA-PSS-Schlüssel.
v11.7.0Der Schlüssel kann jetzt ein privater Schlüssel sein.
v8.0.0Unterstützung für RSASSA-PSS und zusätzliche Optionen wurde hinzugefügt.
v0.1.92Hinzugefügt in: v0.1.92

Überprüft die bereitgestellten Daten mit dem angegebenen object und signature.

Wenn object kein KeyObject ist, verhält sich diese Funktion so, als wäre object an crypto.createPublicKey() übergeben worden. Wenn es sich um ein Objekt handelt, können die folgenden zusätzlichen Eigenschaften übergeben werden:

  • dsaEncoding <string> Für DSA und ECDSA gibt diese Option das Format der Signatur an. Es kann einer der folgenden sein:

    • 'der' (Standard): DER-codierte ASN.1-Signaturstrukturcodierung (r, s).
    • 'ieee-p1363': Signaturformat r || s wie in IEEE-P1363 vorgeschlagen.

  • padding <integer> Optionaler Padding-Wert für RSA, einer der folgenden:

    • crypto.constants.RSA_PKCS1_PADDING (Standard)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

RSA_PKCS1_PSS_PADDING verwendet MGF1 mit der gleichen Hash-Funktion, die verwendet wird, um die Nachricht zu verifizieren, wie in Abschnitt 3.1 von RFC 4055 angegeben, es sei denn, eine MGF1-Hash-Funktion wurde als Teil des Schlüssels gemäß Abschnitt 3.3 von RFC 4055 angegeben.

  • saltLength <integer> Salzlänge, wenn Padding RSA_PKCS1_PSS_PADDING ist. Der spezielle Wert crypto.constants.RSA_PSS_SALTLEN_DIGEST setzt die Salzlänge auf die Digestgröße, crypto.constants.RSA_PSS_SALTLEN_AUTO (Standard) bewirkt, dass sie automatisch bestimmt wird.

Das Argument signature ist die zuvor berechnete Signatur für die Daten in der signatureEncoding. Wenn eine signatureEncoding angegeben ist, wird erwartet, dass signature ein String ist; andernfalls wird erwartet, dass signature ein Buffer, TypedArray oder DataView ist.

Das verify-Objekt kann nach dem Aufruf von verify.verify() nicht mehr verwendet werden. Mehrere Aufrufe von verify.verify() führen zu einem Fehler.

Da öffentliche Schlüssel aus privaten Schlüsseln abgeleitet werden können, kann stattdessen ein privater Schlüssel anstelle eines öffentlichen Schlüssels übergeben werden.

Klasse: X509Certificate ​

Hinzugefügt in: v15.6.0

Kapselt ein X509-Zertifikat und bietet schreibgeschützten Zugriff auf dessen Informationen.

js
const { X509Certificate } = await import('node:crypto')

const x509 = new X509Certificate('{... pem encoded cert ...}')

console.log(x509.subject)
js
const { X509Certificate } = require('node:crypto')

const x509 = new X509Certificate('{... pem encoded cert ...}')

console.log(x509.subject)

new X509Certificate(buffer) ​

Hinzugefügt in: v15.6.0

x509.ca ​

Hinzugefügt in: v15.6.0

  • Typ: <boolean> Ist true, wenn es sich um ein Certificate Authority (CA)-Zertifikat handelt.

x509.checkEmail(email[, options]) ​

[Verlauf]

VersionÄnderungen
v18.0.0Die Option subject hat nun den Standardwert 'default'.
v17.5.0, v16.15.0Die Option subject kann nun auf 'default' gesetzt werden.
v17.5.0, v16.14.1Die Optionen wildcards, partialWildcards, multiLabelWildcards und singleLabelSubdomains wurden entfernt, da sie keine Wirkung hatten.
v15.6.0Hinzugefügt in: v15.6.0

  • email <string>

  • options <Object>

    • subject <string> 'default', 'always' oder 'never'. Standard: 'default'.

  • Rückgabewert: <string> | <undefined> Gibt email zurück, wenn das Zertifikat übereinstimmt, undefined, wenn nicht.

Überprüft, ob das Zertifikat mit der angegebenen E-Mail-Adresse übereinstimmt.

Wenn die Option 'subject' undefiniert oder auf 'default' gesetzt ist, wird der Zertifikatsinhaber nur berücksichtigt, wenn die Erweiterung für alternative Subjectnamen entweder nicht existiert oder keine E-Mail-Adressen enthält.

Wenn die Option 'subject' auf 'always' gesetzt ist und die Erweiterung für alternative Subjectnamen entweder nicht existiert oder keine übereinstimmende E-Mail-Adresse enthält, wird der Zertifikatsinhaber berücksichtigt.

Wenn die Option 'subject' auf 'never' gesetzt ist, wird der Zertifikatsinhaber niemals berücksichtigt, selbst wenn das Zertifikat keine alternativen Subjectnamen enthält.

x509.checkHost(name[, options]) ​

[Verlauf]

VersionÄnderungen
v18.0.0Die Option subject hat nun standardmäßig den Wert 'default'.
v17.5.0, v16.15.0Die Option subject kann nun auf 'default' gesetzt werden.
v15.6.0Hinzugefügt in: v15.6.0

  • name <string>

  • options <Object>

    • subject <string> 'default', 'always', oder 'never'. Standard: 'default'.
    • wildcards <boolean> Standard: true.
    • partialWildcards <boolean> Standard: true.
    • multiLabelWildcards <boolean> Standard: false.
    • singleLabelSubdomains <boolean> Standard: false.

  • Rückgabewert: <string> | <undefined> Gibt einen Subject-Namen zurück, der mit name übereinstimmt, oder undefined, wenn kein Subject-Name mit name übereinstimmt.

Überprüft, ob das Zertifikat mit dem angegebenen Hostnamen übereinstimmt.

Wenn das Zertifikat mit dem angegebenen Hostnamen übereinstimmt, wird der übereinstimmende Subject-Name zurückgegeben. Der zurückgegebene Name kann eine exakte Übereinstimmung sein (z. B. foo.example.com) oder er kann Wildcards enthalten (z. B. *.example.com). Da Hostnamenvergleiche nicht zwischen Groß- und Kleinschreibung unterscheiden, kann der zurückgegebene Subject-Name sich auch in der Groß-/Kleinschreibung vom angegebenen name unterscheiden.

Wenn die Option 'subject' undefiniert ist oder auf 'default' gesetzt ist, wird der Zertifikat-Subject nur dann berücksichtigt, wenn die Subject Alternative Name-Erweiterung entweder nicht existiert oder keine DNS-Namen enthält. Dieses Verhalten entspricht RFC 2818 ("HTTP Over TLS").

Wenn die Option 'subject' auf 'always' gesetzt ist und die Subject Alternative Name-Erweiterung entweder nicht existiert oder keinen übereinstimmenden DNS-Namen enthält, wird der Zertifikat-Subject berücksichtigt.

Wenn die Option 'subject' auf 'never' gesetzt ist, wird der Zertifikat-Subject niemals berücksichtigt, selbst wenn das Zertifikat keine Subject Alternative Names enthält.

x509.checkIP(ip) ​

[Verlauf]

VersionÄnderungen
v17.5.0, v16.14.1Das Argument options wurde entfernt, da es keine Wirkung hatte.
v15.6.0Hinzugefügt in: v15.6.0

Überprüft, ob das Zertifikat mit der angegebenen IP-Adresse (IPv4 oder IPv6) übereinstimmt.

Es werden nur iPAddress-Subject Alternative Names gemäß RFC 5280 berücksichtigt, und diese müssen exakt mit der angegebenen ip-Adresse übereinstimmen. Andere Subject Alternative Names sowie das Subject-Feld des Zertifikats werden ignoriert.

x509.checkIssued(otherCert) ​

Hinzugefügt in: v15.6.0

Überprüft, ob dieses Zertifikat von dem angegebenen otherCert ausgestellt wurde.

x509.checkPrivateKey(privateKey) ​

Hinzugefügt in: v15.6.0

Überprüft, ob der öffentliche Schlüssel für dieses Zertifikat mit dem angegebenen privaten Schlüssel übereinstimmt.

x509.extKeyUsage ​

Hinzugefügt in: v15.6.0

Ein Array, das die erweiterten Schlüsselverwendungen für dieses Zertifikat detailliert beschreibt.

x509.fingerprint ​

Hinzugefügt in: v15.6.0

Der SHA-1-Fingerabdruck dieses Zertifikats.

Da SHA-1 kryptografisch gebrochen ist und die Sicherheit von SHA-1 deutlich schlechter ist als die von Algorithmen, die üblicherweise zum Signieren von Zertifikaten verwendet werden, sollten Sie stattdessen x509.fingerprint256 verwenden.

x509.fingerprint256 ​

Hinzugefügt in: v15.6.0

Der SHA-256-Fingerabdruck dieses Zertifikats.

x509.fingerprint512 ​

Hinzugefügt in: v17.2.0, v16.14.0

Der SHA-512-Fingerabdruck dieses Zertifikats.

Da die Berechnung des SHA-256-Fingerabdrucks in der Regel schneller ist und nur halb so groß ist wie der SHA-512-Fingerabdruck, ist x509.fingerprint256 möglicherweise die bessere Wahl. Obwohl SHA-512 vermutlich im Allgemeinen ein höheres Sicherheitsniveau bietet, entspricht die Sicherheit von SHA-256 der der meisten Algorithmen, die üblicherweise zum Signieren von Zertifikaten verwendet werden.

x509.infoAccess ​

[Verlauf]

VersionÄnderungen
v17.3.1, v16.13.2Teile dieser Zeichenkette können als JSON-Zeichenkettenliterale als Antwort auf CVE-2021-44532 codiert sein.
v15.6.0Hinzugefügt in: v15.6.0

Eine textuelle Darstellung der Authority Information Access-Erweiterung des Zertifikats.

Dies ist eine durch Zeilenvorschübe getrennte Liste von Zugriffsbeschreibungen. Jede Zeile beginnt mit der Zugriffsmethode und der Art des Zugriffsortes, gefolgt von einem Doppelpunkt und dem Wert, der dem Zugriffsort zugeordnet ist.

Nach dem Präfix, das die Zugriffsmethode und die Art des Zugriffsortes angibt, kann der Rest jeder Zeile in Anführungszeichen eingeschlossen sein, um anzugeben, dass der Wert ein JSON-Zeichenkettenliteral ist. Aus Gründen der Abwärtskompatibilität verwendet Node.js diese JSON-Zeichenkettenliterale innerhalb dieser Eigenschaft nur dann, wenn dies zur Vermeidung von Mehrdeutigkeiten erforderlich ist. Code von Drittanbietern sollte darauf vorbereitet sein, beide möglichen Eingabeformate zu verarbeiten.

x509.issuer ​

Hinzugefügt in: v15.6.0

Die in diesem Zertifikat enthaltene Ausstellerkennung.

x509.issuerCertificate ​

Hinzugefügt in: v15.9.0

Das Ausstellerzertifikat oder undefined, wenn das Ausstellerzertifikat nicht verfügbar ist.

x509.publicKey ​

Hinzugefügt in: v15.6.0

Der öffentliche Schlüssel <KeyObject> für dieses Zertifikat.

x509.raw ​

Hinzugefügt in: v15.6.0

Ein Buffer, der die DER-Kodierung dieses Zertifikats enthält.

x509.serialNumber ​

Hinzugefügt in: v15.6.0

Die Seriennummer dieses Zertifikats.

Seriennummern werden von Zertifizierungsstellen vergeben und identifizieren Zertifikate nicht eindeutig. Verwenden Sie stattdessen x509.fingerprint256 als eindeutige Kennung.

x509.subject ​

Hinzugefügt in: v15.6.0

Der vollständige Antragsteller dieses Zertifikats.

x509.subjectAltName ​

[Verlauf]

VersionÄnderungen
v17.3.1, v16.13.2Teile dieser Zeichenkette können als JSON-Zeichenkettenliterale kodiert sein, als Reaktion auf CVE-2021-44532.
v15.6.0Hinzugefügt in: v15.6.0

Der alternative Antragstellername, der für dieses Zertifikat angegeben ist.

Dies ist eine kommaseparierte Liste alternativer Antragstellernamen. Jeder Eintrag beginnt mit einer Zeichenkette, die die Art des alternativen Antragstellernamens identifiziert, gefolgt von einem Doppelpunkt und dem Wert, der dem Eintrag zugeordnet ist.

Frühere Versionen von Node.js gingen fälschlicherweise davon aus, dass es sicher ist, diese Eigenschaft an der zweizeichenlangen Sequenz ', ' zu teilen (siehe CVE-2021-44532). Sowohl bösartige als auch legitime Zertifikate können jedoch alternative Antragstellernamen enthalten, die diese Sequenz enthalten, wenn sie als Zeichenkette dargestellt werden.

Nach dem Präfix, das den Typ des Eintrags angibt, kann der Rest jedes Eintrags in Anführungszeichen eingeschlossen sein, um anzugeben, dass der Wert ein JSON-Zeichenkettenliteral ist. Aus Gründen der Abwärtskompatibilität verwendet Node.js diese JSON-Zeichenkettenliterale innerhalb dieser Eigenschaft nur dann, wenn dies zur Vermeidung von Mehrdeutigkeiten erforderlich ist. Code von Drittanbietern sollte darauf vorbereitet sein, beide möglichen Eintragformate zu verarbeiten.

x509.toJSON() ​

Hinzugefügt in: v15.6.0

Es gibt keine standardmäßige JSON-Kodierung für X509-Zertifikate. Die Methode toJSON() gibt eine Zeichenkette zurück, die das PEM-kodierte Zertifikat enthält.

x509.toLegacyObject() ​

Hinzugefügt in: v15.6.0

Gibt Informationen über dieses Zertifikat unter Verwendung der Legacy-Zertifikatobjekt-Kodierung zurück.

x509.toString() ​

Hinzugefügt in: v15.6.0

Gibt das PEM-kodierte Zertifikat zurück.

x509.validFrom ​

Hinzugefügt in: v15.6.0

Das Datum/die Uhrzeit, ab der dieses Zertifikat gültig ist.

x509.validFromDate ​

Hinzugefügt in: v23.0.0

Das Datum/die Uhrzeit, ab der dieses Zertifikat gültig ist, gekapselt in einem Date-Objekt.

x509.validTo ​

Hinzugefügt in: v15.6.0

Das Datum/die Uhrzeit, bis zu der dieses Zertifikat gültig ist.

x509.validToDate ​

Hinzugefügt in: v23.0.0

Das Datum/die Uhrzeit, bis zu der dieses Zertifikat gültig ist, gekapselt in einem Date-Objekt.

x509.verify(publicKey) ​

Hinzugefügt in: v15.6.0

Überprüft, ob dieses Zertifikat mit dem angegebenen öffentlichen Schlüssel signiert wurde. Führt keine weiteren Validierungsprüfungen für das Zertifikat durch.

node:crypto Modulmethoden und -eigenschaften ​

crypto.checkPrime(candidate[, options], callback) ​

[Verlauf]

VersionÄnderungen
v18.0.0Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v15.8.0Hinzugefügt in: v15.8.0

  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> Eine mögliche Primzahl, codiert als Sequenz von Big-Endian-Oktetten beliebiger Länge.

  • options <Object>

    • checks <number> Die Anzahl der probabilistischen Miller-Rabin-Primzahliterationen, die durchgeführt werden sollen. Wenn der Wert 0 (Null) ist, wird eine Anzahl von Prüfungen verwendet, die eine falsch positive Rate von höchstens 2 für zufällige Eingaben ergibt. Bei der Auswahl der Anzahl der Prüfungen ist Vorsicht geboten. Weitere Informationen finden Sie in der OpenSSL-Dokumentation zur Funktion BN_is_prime_ex nchecks-Optionen. Standard: 0

  • callback <Function>

    • err <Error> Wird auf ein <Error>-Objekt gesetzt, wenn während der Prüfung ein Fehler aufgetreten ist.
    • result <boolean> true, wenn der Kandidat eine Primzahl mit einer Fehlerwahrscheinlichkeit von weniger als 0.25 ** options.checks ist.

Überprüft die Primalität des candidate.

crypto.checkPrimeSync(candidate[, options]) ​

Hinzugefügt in: v15.8.0

  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> Eine mögliche Primzahl, codiert als Folge von Big-Endian-Oktetten beliebiger Länge.

  • options <Object>

    • checks <number> Die Anzahl der probabilistischen Primzahliterationen von Miller-Rabin, die durchgeführt werden sollen. Wenn der Wert 0 (null) ist, wird eine Anzahl von Prüfungen verwendet, die eine falsch positive Rate von höchstens 2 für zufällige Eingaben ergibt. Bei der Auswahl der Anzahl der Prüfungen ist Vorsicht geboten. Weitere Informationen finden Sie in der OpenSSL-Dokumentation zur Funktion BN_is_prime_ex nchecks Optionen. Standard: 0

  • Gibt zurück: <boolean> true, wenn der Kandidat eine Primzahl mit einer Fehlerwahrscheinlichkeit von weniger als 0.25 ** options.checks ist.

Prüft die Primalität des candidate.

crypto.constants ​

Hinzugefügt in: v6.3.0

Ein Objekt, das häufig verwendete Konstanten für kryptografische und sicherheitsbezogene Operationen enthält. Die aktuell definierten Konstanten werden in Krypto-Konstanten beschrieben.

crypto.createCipheriv(algorithm, key, iv[, options]) ​

[Verlauf]

VersionÄnderungen
v17.9.0, v16.17.0Die Option authTagLength ist jetzt optional bei Verwendung der Chiffre chacha20-poly1305 und hat standardmäßig eine Länge von 16 Bytes.
v15.0.0Die Argumente password und iv können ein ArrayBuffer sein und sind jeweils auf maximal 2 ** 31 - 1 Bytes begrenzt.
v11.6.0Das Argument key kann jetzt ein KeyObject sein.
v11.2.0, v10.17.0Die Chiffre chacha20-poly1305 (die IETF-Variante von ChaCha20-Poly1305) wird jetzt unterstützt.
v10.10.0Chiffren im OCB-Modus werden jetzt unterstützt.
v10.2.0Die Option authTagLength kann jetzt verwendet werden, um kürzere Authentifizierungs-Tags im GCM-Modus zu erzeugen und hat standardmäßig eine Länge von 16 Bytes.
v9.9.0Der Parameter iv kann jetzt null sein für Chiffren, die keinen Initialisierungsvektor benötigen.
v0.1.94Hinzugefügt in: v0.1.94

Erzeugt und gibt ein Cipher-Objekt mit dem angegebenen algorithm, key und Initialisierungsvektor (iv) zurück.

Das Argument options steuert das Stream-Verhalten und ist optional, außer wenn eine Chiffre im CCM- oder OCB-Modus (z. B. 'aes-128-ccm') verwendet wird. In diesem Fall ist die Option authTagLength erforderlich und gibt die Länge des Authentifizierungs-Tags in Bytes an, siehe CCM-Modus. Im GCM-Modus ist die Option authTagLength nicht erforderlich, kann aber verwendet werden, um die Länge des Authentifizierungs-Tags festzulegen, die von getAuthTag() zurückgegeben wird, und hat standardmäßig eine Länge von 16 Bytes. Für chacha20-poly1305 hat die Option authTagLength standardmäßig eine Länge von 16 Bytes.

Der algorithm hängt von OpenSSL ab, Beispiele sind 'aes192', usw. Bei neueren OpenSSL-Versionen zeigt openssl list -cipher-algorithms die verfügbaren Chiffrieralgorithmen an.

Der key ist der Rohschlüssel, der vom algorithm verwendet wird, und iv ist ein Initialisierungsvektor. Beide Argumente müssen 'utf8'-kodierte Strings, Buffers, TypedArray oder DataViews sein. Der key kann optional ein KeyObject vom Typ secret sein. Wenn die Chiffre keinen Initialisierungsvektor benötigt, kann iv null sein.

Bei der Übergabe von Strings für key oder iv beachten Sie bitte die Warnungen bei der Verwendung von Strings als Eingabe für kryptografische APIs.

Initialisierungsvektoren sollten unvorhersehbar und eindeutig sein; idealerweise sind sie kryptografisch zufällig. Sie müssen nicht geheim sein: IVs werden typischerweise nur unverschlüsselt zu Chiffretextnachrichten hinzugefügt. Es mag widersprüchlich klingen, dass etwas unvorhersehbar und eindeutig sein muss, aber nicht geheim sein muss; denken Sie daran, dass ein Angreifer nicht im Voraus vorhersagen können darf, wie ein bestimmter IV aussehen wird.

crypto.createDecipheriv(algorithm, key, iv[, options]) ​

[Historie]

VersionÄnderungen
v17.9.0, v16.17.0Die Option authTagLength ist jetzt optional bei Verwendung der Chiffre chacha20-poly1305 und standardmäßig auf 16 Bytes eingestellt.
v11.6.0Das Argument key kann jetzt ein KeyObject sein.
v11.2.0, v10.17.0Die Chiffre chacha20-poly1305 (die IETF-Variante von ChaCha20-Poly1305) wird jetzt unterstützt.
v10.10.0Chiffren im OCB-Modus werden jetzt unterstützt.
v10.2.0Die Option authTagLength kann jetzt verwendet werden, um akzeptierte GCM-Authentifizierungs-Tag-Längen einzuschränken.
v9.9.0Der Parameter iv kann jetzt null sein für Chiffren, die keinen Initialisierungsvektor benötigen.
v0.1.94Hinzugefügt in: v0.1.94

Erzeugt und gibt ein Decipher-Objekt zurück, das den angegebenen algorithm, key und Initialisierungsvektor (iv) verwendet.

Das Argument options steuert das Stream-Verhalten und ist optional, außer wenn eine Chiffre im CCM- oder OCB-Modus (z. B. 'aes-128-ccm') verwendet wird. In diesem Fall ist die Option authTagLength erforderlich und gibt die Länge des Authentifizierungstags in Bytes an, siehe CCM-Modus. Für AES-GCM und chacha20-poly1305 ist die Option authTagLength standardmäßig auf 16 Bytes eingestellt und muss auf einen anderen Wert gesetzt werden, wenn eine andere Länge verwendet wird.

Der algorithm ist abhängig von OpenSSL, Beispiele sind 'aes192', usw. Bei neueren OpenSSL-Versionen zeigt openssl list -cipher-algorithms die verfügbaren Chiffrieralgorithmen an.

Der key ist der vom algorithm verwendete Rohschlüssel und iv ist ein Initialisierungsvektor. Beide Argumente müssen 'utf8'-kodierte Strings, Buffers, TypedArray oder DataViews sein. Der key kann optional ein KeyObject vom Typ secret sein. Wenn die Chiffre keinen Initialisierungsvektor benötigt, kann iv null sein.

Bei der Übergabe von Strings für key oder iv beachten Sie bitte die Warnungen bei der Verwendung von Strings als Eingabe für kryptografische APIs.

Initialisierungsvektoren sollten unvorhersehbar und eindeutig sein; idealerweise sind sie kryptografisch zufällig. Sie müssen nicht geheim sein: IVs werden typischerweise nur unverschlüsselt zu Chiffretextnachrichten hinzugefügt. Es mag widersprüchlich klingen, dass etwas unvorhersehbar und eindeutig sein muss, aber nicht geheim sein muss; denken Sie daran, dass ein Angreifer nicht im Voraus vorhersagen können darf, was ein bestimmter IV sein wird.

crypto.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding]) ​

[Verlauf]

VersionÄnderungen
v8.0.0Das Argument prime kann jetzt jedes TypedArray oder DataView sein.
v8.0.0Das Argument prime kann jetzt ein Uint8Array sein.
v6.0.0Die Standardeinstellung für die Kodierungsparameter wurde von binary auf utf8 geändert.
v0.11.12Hinzugefügt in: v0.11.12

Erstellt ein DiffieHellman-Schlüsselaustauschobjekt mit dem angegebenen prime und einem optionalen spezifischen generator.

Das Argument generator kann eine Zahl, ein String oder ein Buffer sein. Wenn generator nicht angegeben ist, wird der Wert 2 verwendet.

Wenn primeEncoding angegeben ist, wird erwartet, dass prime ein String ist; andernfalls wird ein Buffer, TypedArray oder DataView erwartet.

Wenn generatorEncoding angegeben ist, wird erwartet, dass generator ein String ist; andernfalls wird eine Zahl, ein Buffer, TypedArray oder DataView erwartet.

crypto.createDiffieHellman(primeLength[, generator]) ​

Hinzugefügt in: v0.5.0

Erstellt ein DiffieHellman-Schlüsselaustauschobjekt und generiert eine Primzahl mit primeLength Bits unter Verwendung eines optionalen, spezifischen numerischen generator. Wenn generator nicht angegeben ist, wird der Wert 2 verwendet.

crypto.createDiffieHellmanGroup(name) ​

Hinzugefügt in: v0.9.3

Ein Alias für crypto.getDiffieHellman()

crypto.createECDH(curveName) ​

Hinzugefügt in: v0.11.14

Erstellt ein Elliptic Curve Diffie-Hellman (ECDH)-Schlüsselaustauschobjekt unter Verwendung einer vordefinierten Kurve, die durch die Zeichenkette curveName angegeben wird. Verwenden Sie crypto.getCurves(), um eine Liste der verfügbaren Kurvennamen zu erhalten. Bei neueren OpenSSL-Versionen zeigt openssl ecparam -list_curves auch den Namen und die Beschreibung jeder verfügbaren elliptischen Kurve an.

crypto.createHash(algorithm[, options]) ​

[Verlauf]

VersionÄnderungen
v12.8.0Die Option outputLength wurde für XOF-Hash-Funktionen hinzugefügt.
v0.1.92Hinzugefügt in: v0.1.92

Erstellt und gibt ein Hash-Objekt zurück, mit dem Hash-Digests mit dem angegebenen algorithm generiert werden können. Das optionale Argument options steuert das Stream-Verhalten. Für XOF-Hash-Funktionen wie 'shake256' kann die Option outputLength verwendet werden, um die gewünschte Ausgabelänge in Bytes anzugeben.

Der algorithm hängt von den verfügbaren Algorithmen ab, die von der OpenSSL-Version auf der Plattform unterstützt werden. Beispiele sind 'sha256', 'sha512' usw. Bei neueren OpenSSL-Versionen zeigt openssl list -digest-algorithms die verfügbaren Digest-Algorithmen an.

Beispiel: Generieren der sha256-Summe einer Datei

js
import { createReadStream } from 'node:fs'
import { argv } from 'node:process'
const { createHash } = await import('node:crypto')

const filename = argv[2]

const hash = createHash('sha256')

const input = createReadStream(filename)
input.on('readable', () => {
  // Nur ein Element wird vom
  // Hash-Stream erzeugt.
  const data = input.read()
  if (data) hash.update(data)
  else {
    console.log(`${hash.digest('hex')} ${filename}`)
  }
})
js
const { createReadStream } = require('node:fs')
const { createHash } = require('node:crypto')
const { argv } = require('node:process')

const filename = argv[2]

const hash = createHash('sha256')

const input = createReadStream(filename)
input.on('readable', () => {
  // Nur ein Element wird vom
  // Hash-Stream erzeugt.
  const data = input.read()
  if (data) hash.update(data)
  else {
    console.log(`${hash.digest('hex')} ${filename}`)
  }
})

crypto.createHmac(algorithm, key[, options]) ​

[Historie]

VersionÄnderungen
v15.0.0Der Schlüssel kann auch ein ArrayBuffer oder CryptoKey sein. Die Option encoding wurde hinzugefügt. Der Schlüssel darf nicht mehr als 2 ** 32 - 1 Bytes enthalten.
v11.6.0Das Argument key kann jetzt ein KeyObject sein.
v0.1.94Hinzugefügt in: v0.1.94

Erstellt und gibt ein Hmac-Objekt zurück, das den angegebenen algorithm und key verwendet. Das optionale options-Argument steuert das Stream-Verhalten.

Der algorithm hängt von den verfügbaren Algorithmen ab, die von der OpenSSL-Version auf der Plattform unterstützt werden. Beispiele sind 'sha256', 'sha512' usw. Bei neueren OpenSSL-Versionen zeigt openssl list -digest-algorithms die verfügbaren Digest-Algorithmen an.

Der key ist der HMAC-Schlüssel, der zur Generierung des kryptografischen HMAC-Hashes verwendet wird. Wenn es sich um ein KeyObject handelt, muss sein Typ secret sein. Wenn es sich um eine Zeichenkette handelt, beachten Sie bitte die Warnungen bei der Verwendung von Zeichenketten als Eingaben für kryptografische APIs. Wenn es aus einer kryptografisch sicheren Quelle für Entropie stammt, wie z. B. crypto.randomBytes() oder crypto.generateKey(), sollte seine Länge die Blockgröße von algorithm nicht überschreiten (z. B. 512 Bit für SHA-256).

Beispiel: Generieren des sha256 HMAC einer Datei

js
import { createReadStream } from 'node:fs'
import { argv } from 'node:process'
const { createHmac } = await import('node:crypto')

const filename = argv[2]

const hmac = createHmac('sha256', 'a secret')

const input = createReadStream(filename)
input.on('readable', () => {
  // Nur ein Element wird vom
  // Hash-Stream erzeugt.
  const data = input.read()
  if (data) hmac.update(data)
  else {
    console.log(`${hmac.digest('hex')} ${filename}`)
  }
})
js
const { createReadStream } = require('node:fs')
const { createHmac } = require('node:crypto')
const { argv } = require('node:process')

const filename = argv[2]

const hmac = createHmac('sha256', 'a secret')

const input = createReadStream(filename)
input.on('readable', () => {
  // Nur ein Element wird vom
  // Hash-Stream erzeugt.
  const data = input.read()
  if (data) hmac.update(data)
  else {
    console.log(`${hmac.digest('hex')} ${filename}`)
  }
})

crypto.createPrivateKey(key) ​

[Verlauf]

VersionÄnderungen
v15.12.0Der Schlüssel kann auch ein JWK-Objekt sein.
v15.0.0Der Schlüssel kann auch ein ArrayBuffer sein. Die Option encoding wurde hinzugefügt. Der Schlüssel darf nicht mehr als 2 ** 32 - 1 Byte enthalten.
v11.6.0Hinzugefügt in: v11.6.0

Erstellt und gibt ein neues Schlüssel-Objekt zurück, das einen privaten Schlüssel enthält. Wenn key eine Zeichenkette oder ein Buffer ist, wird angenommen, dass format 'pem' ist; andernfalls muss key ein Objekt mit den oben beschriebenen Eigenschaften sein.

Wenn der private Schlüssel verschlüsselt ist, muss eine passphrase angegeben werden. Die Länge der Passphrase ist auf 1024 Byte begrenzt.

crypto.createPublicKey(key) ​

[Historie]

VersionÄnderungen
v15.12.0Der Schlüssel kann auch ein JWK-Objekt sein.
v15.0.0Der Schlüssel kann auch ein ArrayBuffer sein. Die Option encoding wurde hinzugefügt. Der Schlüssel darf nicht mehr als 2 ** 32 - 1 Byte enthalten.
v11.13.0Das Argument key kann jetzt ein KeyObject vom Typ private sein.
v11.7.0Das Argument key kann jetzt ein privater Schlüssel sein.
v11.6.0Hinzugefügt in: v11.6.0

Erstellt und gibt ein neues Key-Objekt zurück, das einen öffentlichen Schlüssel enthält. Wenn key eine Zeichenkette oder ein Buffer ist, wird angenommen, dass format 'pem' ist; wenn key ein KeyObject vom Typ 'private' ist, wird der öffentliche Schlüssel aus dem gegebenen privaten Schlüssel abgeleitet; andernfalls muss key ein Objekt mit den oben beschriebenen Eigenschaften sein.

Wenn das Format 'pem' ist, kann der 'key' auch ein X.509-Zertifikat sein.

Da öffentliche Schlüssel aus privaten Schlüsseln abgeleitet werden können, kann stattdessen ein privater Schlüssel anstelle eines öffentlichen Schlüssels übergeben werden. In diesem Fall verhält sich diese Funktion so, als ob crypto.createPrivateKey() aufgerufen worden wäre, außer dass der Typ des zurückgegebenen KeyObject 'public' sein wird und der private Schlüssel nicht aus dem zurückgegebenen KeyObject extrahiert werden kann. Ähnlich verhält es sich, wenn ein KeyObject vom Typ 'private' angegeben wird, wird ein neues KeyObject vom Typ 'public' zurückgegeben und es wird unmöglich sein, den privaten Schlüssel aus dem zurückgegebenen Objekt zu extrahieren.

crypto.createSecretKey(key[, encoding]) ​

[Verlauf]

VersionÄnderungen
v18.8.0, v16.18.0Der Schlüssel kann jetzt die Länge Null haben.
v15.0.0Der Schlüssel kann auch ein ArrayBuffer oder eine Zeichenkette sein. Das Argument encoding wurde hinzugefügt. Der Schlüssel darf nicht mehr als 2 ** 32 - 1 Bytes enthalten.
v11.6.0Hinzugefügt in: v11.6.0

Erstellt und gibt ein neues Schlüssel-Objekt zurück, das einen geheimen Schlüssel für die symmetrische Verschlüsselung oder Hmac enthält.

crypto.createSign(algorithm[, options]) ​

Hinzugefügt in: v0.1.92

Erstellt und gibt ein Sign-Objekt zurück, das den angegebenen algorithm verwendet. Verwenden Sie crypto.getHashes(), um die Namen der verfügbaren Digest-Algorithmen zu erhalten. Das optionale options-Argument steuert das Verhalten von stream.Writable.

In einigen Fällen kann eine Sign-Instanz unter Verwendung des Namens eines Signaturalgorithmus, z. B. 'RSA-SHA256', anstelle eines Digest-Algorithmus erstellt werden. Dies verwendet den entsprechenden Digest-Algorithmus. Dies funktioniert nicht für alle Signaturalgorithmen, z. B. 'ecdsa-with-SHA256', daher ist es am besten, immer Digest-Algorithmusnamen zu verwenden.

crypto.createVerify(algorithm[, options]) ​

Hinzugefügt in: v0.1.92

Erstellt und gibt ein Verify-Objekt zurück, das den angegebenen Algorithmus verwendet. Verwenden Sie crypto.getHashes(), um ein Array mit den Namen der verfügbaren Signaturalgorithmen zu erhalten. Das optionale Argument options steuert das Verhalten von stream.Writable.

In einigen Fällen kann eine Verify-Instanz unter Verwendung des Namens eines Signaturalgorithmus wie 'RSA-SHA256' anstelle eines Digest-Algorithmus erstellt werden. Dies verwendet den entsprechenden Digest-Algorithmus. Dies funktioniert nicht für alle Signaturalgorithmen, wie z. B. 'ecdsa-with-SHA256', daher ist es am besten, immer Digest-Algorithmusnamen zu verwenden.

crypto.diffieHellman(options) ​

Hinzugefügt in: v13.9.0, v12.17.0

Berechnet das Diffie-Hellman-Geheimnis basierend auf einem privateKey und einem publicKey. Beide Schlüssel müssen den gleichen asymmetricKeyType haben, der einer von 'dh' (für Diffie-Hellman), 'ec', 'x448' oder 'x25519' (für ECDH) sein muss.

crypto.fips ​

Hinzugefügt in: v6.0.0

Veraltet seit: v10.0.0

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet

Eigenschaft zum Überprüfen und Steuern, ob derzeit ein FIPS-konformer Krypto-Provider verwendet wird. Das Setzen auf true erfordert einen FIPS-Build von Node.js.

Diese Eigenschaft ist veraltet. Verwenden Sie stattdessen crypto.setFips() und crypto.getFips().

crypto.generateKey(type, options, callback) ​

[Verlauf]

VersionÄnderungen
v18.0.0Das Übergeben eines ungültigen Callbacks an das Argument callback löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v15.0.0Hinzugefügt in: v15.0.0

  • type: <string> Der beabsichtigte Verwendungszweck des generierten geheimen Schlüssels. Derzeit akzeptierte Werte sind 'hmac' und 'aes'.

  • options: <Object>

    • length: <number> Die Bitlänge des zu generierenden Schlüssels. Dies muss ein Wert größer als 0 sein.
    • Wenn type 'hmac' ist, beträgt das Minimum 8 und die maximale Länge 2-1. Wenn der Wert kein Vielfaches von 8 ist, wird der generierte Schlüssel auf Math.floor(length / 8) gekürzt.
    • Wenn type 'aes' ist, muss die Länge einer von 128, 192 oder 256 sein.

  • callback: <Function>

Generiert asynchron einen neuen zufälligen geheimen Schlüssel der angegebenen length. Der type bestimmt, welche Validierungen für die length durchgeführt werden.

js
const { generateKey } = await import('node:crypto')

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err
  console.log(key.export().toString('hex')) // 46e..........620
})
js
const { generateKey } = require('node:crypto')

generateKey('hmac', { length: 512 }, (err, key) => {
  if (err) throw err
  console.log(key.export().toString('hex')) // 46e..........620
})

Die Größe eines generierten HMAC-Schlüssels sollte die Blockgröße der zugrundeliegenden Hash-Funktion nicht überschreiten. Weitere Informationen finden Sie unter crypto.createHmac().

crypto.generateKeyPair(type, options, callback) ​

[Verlauf]

VersionÄnderungen
v18.0.0Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE statt ERR_INVALID_CALLBACK aus.
v16.10.0Möglichkeit hinzugefügt, RSASSA-PSS-params-Sequenzparameter für RSA-PSS-Schlüsselpaare zu definieren.
v13.9.0, v12.17.0Unterstützung für Diffie-Hellman hinzugefügt.
v12.0.0Unterstützung für RSA-PSS-Schlüsselpaare hinzugefügt.
v12.0.0Möglichkeit hinzugefügt, X25519- und X448-Schlüsselpaare zu generieren.
v12.0.0Möglichkeit hinzugefügt, Ed25519- und Ed448-Schlüsselpaare zu generieren.
v11.6.0Die Funktionen generateKeyPair und generateKeyPairSync erzeugen nun Key-Objekte, wenn keine Codierung angegeben wurde.
v10.12.0Hinzugefügt in: v10.12.0

Generiert ein neues asymmetrisches Schlüsselpaar des angegebenen Typs. RSA, RSA-PSS, DSA, EC, Ed25519, Ed448, X25519, X448 und DH werden derzeit unterstützt.

Wenn ein publicKeyEncoding oder privateKeyEncoding angegeben wurde, verhält sich diese Funktion so, als ob keyObject.export() auf das Ergebnis aufgerufen worden wäre. Andernfalls wird der jeweilige Teil des Schlüssels als KeyObject zurückgegeben.

Es wird empfohlen, öffentliche Schlüssel als 'spki' und private Schlüssel als 'pkcs8' mit Verschlüsselung für die Langzeitaufbewahrung zu kodieren:

js
const { generateKeyPair } = await import('node:crypto')

generateKeyPair(
  'rsa',
  {
    modulusLength: 4096,
    publicKeyEncoding: {
      type: 'spki',
      format: 'pem',
    },
    privateKeyEncoding: {
      type: 'pkcs8',
      format: 'pem',
      cipher: 'aes-256-cbc',
      passphrase: 'top secret',
    },
  },
  (err, publicKey, privateKey) => {
    // Fehler behandeln und das generierte Schlüsselpaar verwenden.
  }
)
js
const { generateKeyPair } = require('node:crypto')

generateKeyPair(
  'rsa',
  {
    modulusLength: 4096,
    publicKeyEncoding: {
      type: 'spki',
      format: 'pem',
    },
    privateKeyEncoding: {
      type: 'pkcs8',
      format: 'pem',
      cipher: 'aes-256-cbc',
      passphrase: 'top secret',
    },
  },
  (err, publicKey, privateKey) => {
    // Fehler behandeln und das generierte Schlüsselpaar verwenden.
  }
)

Nach Abschluss wird callback mit err auf undefined und publicKey / privateKey aufgerufen, die das generierte Schlüsselpaar darstellen.

Wenn diese Methode als ihre util.promisify()-Version aufgerufen wird, gibt sie ein Promise für ein Object mit den Eigenschaften publicKey und privateKey zurück.

crypto.generateKeyPairSync(type, options) ​

[Historie]

VersionÄnderungen
v16.10.0Hinzufügen der Möglichkeit, RSASSA-PSS-params-Sequenzparameter für RSA-PSS-Schlüsselpaare zu definieren.
v13.9.0, v12.17.0Unterstützung für Diffie-Hellman hinzugefügt.
v12.0.0Unterstützung für RSA-PSS-Schlüsselpaare hinzugefügt.
v12.0.0Möglichkeit zum Generieren von X25519- und X448-Schlüsselpaaren hinzugefügt.
v12.0.0Möglichkeit zum Generieren von Ed25519- und Ed448-Schlüsselpaaren hinzugefügt.
v11.6.0Die Funktionen generateKeyPair und generateKeyPairSync erzeugen jetzt Schlüssel-Objekte, wenn keine Kodierung angegeben wurde.
v10.12.0Hinzugefügt in: v10.12.0

Generiert ein neues asymmetrisches Schlüsselpaar des angegebenen Typs. RSA, RSA-PSS, DSA, EC, Ed25519, Ed448, X25519, X448 und DH werden derzeit unterstützt.

Wenn eine publicKeyEncoding oder privateKeyEncoding angegeben wurde, verhält sich diese Funktion so, als wäre keyObject.export() auf ihr Ergebnis aufgerufen worden. Andernfalls wird der jeweilige Teil des Schlüssels als KeyObject zurückgegeben.

Bei der Kodierung öffentlicher Schlüssel wird die Verwendung von 'spki' empfohlen. Bei der Kodierung privater Schlüssel wird die Verwendung von 'pkcs8' mit einer starken Passphrase empfohlen, und die Passphrase sollte vertraulich behandelt werden.

js
const { generateKeyPairSync } = await import('node:crypto')

const { publicKey, privateKey } = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
})
js
const { generateKeyPairSync } = require('node:crypto')

const { publicKey, privateKey } = generateKeyPairSync('rsa', {
  modulusLength: 4096,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem',
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem',
    cipher: 'aes-256-cbc',
    passphrase: 'top secret',
  },
})

Der Rückgabewert { publicKey, privateKey } stellt das generierte Schlüsselpaar dar. Wenn die PEM-Kodierung ausgewählt wurde, ist der jeweilige Schlüssel eine Zeichenkette, andernfalls ist es ein Puffer, der die als DER kodierten Daten enthält.

crypto.generateKeySync(type, options) ​

Hinzugefügt in: v15.0.0

  • type: <string> Der beabsichtigte Verwendungszweck des generierten geheimen Schlüssels. Derzeit akzeptierte Werte sind 'hmac' und 'aes'.

  • options: <Object>

    • length: <number> Die Bitlänge des zu generierenden Schlüssels.
    • Wenn type 'hmac' ist, ist das Minimum 8 und die maximale Länge 2-1. Wenn der Wert kein Vielfaches von 8 ist, wird der generierte Schlüssel auf Math.floor(length / 8) gekürzt.
    • Wenn type 'aes' ist, muss die Länge einer von 128, 192 oder 256 sein.

  • Rückgabewert: <KeyObject>

Generiert synchron einen neuen zufälligen geheimen Schlüssel der angegebenen length. Der type bestimmt, welche Validierungen für die length durchgeführt werden.

js
const { generateKeySync } = await import('node:crypto')

const key = generateKeySync('hmac', { length: 512 })
console.log(key.export().toString('hex')) // e89..........41e
js
const { generateKeySync } = require('node:crypto')

const key = generateKeySync('hmac', { length: 512 })
console.log(key.export().toString('hex')) // e89..........41e

Die Größe eines generierten HMAC-Schlüssels sollte die Blockgröße der zugrunde liegenden Hash-Funktion nicht überschreiten. Weitere Informationen finden Sie unter crypto.createHmac().

crypto.generatePrime(size[, options[, callback]]) ​

[Verlauf]

VersionÄnderungen
v18.0.0Das Übergeben eines ungültigen Callbacks an das callback-Argument löst jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v15.8.0Hinzugefügt in: v15.8.0

Generiert eine pseudorandomisierte Primzahl mit size Bit.

Wenn options.safe true ist, ist die Primzahl eine sichere Primzahl – das heißt, (prime - 1) / 2 ist auch eine Primzahl.

Die Parameter options.add und options.rem können verwendet werden, um zusätzliche Anforderungen zu erfüllen, z. B. für Diffie-Hellman:

  • Wenn sowohl options.add als auch options.rem gesetzt sind, erfüllt die Primzahl die Bedingung, dass prime % add = rem.
  • Wenn nur options.add gesetzt ist und options.safe nicht true ist, erfüllt die Primzahl die Bedingung, dass prime % add = 1.
  • Wenn nur options.add gesetzt ist und options.safe auf true gesetzt ist, erfüllt die Primzahl stattdessen die Bedingung, dass prime % add = 3. Dies ist notwendig, da prime % add = 1 für options.add \> 2 der Bedingung widersprechen würde, die durch options.safe erzwungen wird.
  • options.rem wird ignoriert, wenn options.add nicht angegeben ist.

Sowohl options.add als auch options.rem müssen als Big-Endian-Sequenzen kodiert sein, wenn sie als ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer oder DataView angegeben werden.

Standardmäßig wird die Primzahl als Big-Endian-Sequenz von Oktetten in einem <ArrayBuffer> kodiert. Wenn die Option bigint true ist, wird ein <bigint> bereitgestellt.

crypto.generatePrimeSync(size[, options]) ​

Hinzugefügt in: v15.8.0

Generiert eine pseudorandomisierte Primzahl von size Bit.

Wenn options.safe true ist, ist die Primzahl eine sichere Primzahl – das heißt, (prime - 1) / 2 ist auch eine Primzahl.

Die Parameter options.add und options.rem können verwendet werden, um zusätzliche Anforderungen zu erzwingen, z. B. für Diffie-Hellman:

  • Wenn sowohl options.add als auch options.rem gesetzt sind, erfüllt die Primzahl die Bedingung, dass prime % add = rem.
  • Wenn nur options.add gesetzt ist und options.safe nicht true ist, erfüllt die Primzahl die Bedingung, dass prime % add = 1.
  • Wenn nur options.add gesetzt ist und options.safe auf true gesetzt ist, erfüllt die Primzahl stattdessen die Bedingung, dass prime % add = 3. Dies ist notwendig, da prime % add = 1 für options.add \> 2 der Bedingung widersprechen würde, die durch options.safe erzwungen wird.
  • options.rem wird ignoriert, wenn options.add nicht angegeben ist.

Sowohl options.add als auch options.rem müssen als Big-Endian-Sequenzen kodiert sein, wenn sie als ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer oder DataView angegeben werden.

Standardmäßig wird die Primzahl als Big-Endian-Sequenz von Oktetten in einem <ArrayBuffer> codiert. Wenn die Option bigint true ist, wird ein <bigint> bereitgestellt.

crypto.getCipherInfo(nameOrNid[, options]) ​

Hinzugefügt in: v15.0.0

  • nameOrNid: <string> | <number> Der Name oder die nid der abzufragenden Chiffre.

  • options: <Object>

    • keyLength: <number> Eine Test-Schlüssellänge.
    • ivLength: <number> Eine Test-IV-Länge.

  • Gibt zurück: <Object>

    • name <string> Der Name der Chiffre
    • nid <number> Die nid der Chiffre
    • blockSize <number> Die Blockgröße der Chiffre in Bytes. Diese Eigenschaft wird weggelassen, wenn mode 'stream' ist.
    • ivLength <number> Die erwartete oder Standardlänge des Initialisierungsvektors in Bytes. Diese Eigenschaft wird weggelassen, wenn die Chiffre keinen Initialisierungsvektor verwendet.
    • keyLength <number> Die erwartete oder Standard-Schlüssellänge in Bytes.
    • mode <string> Der Chiffriermodus. Einer von 'cbc', 'ccm', 'cfb', 'ctr', 'ecb', 'gcm', 'ocb', 'ofb', 'stream', 'wrap', 'xts'.

Gibt Informationen über eine gegebene Chiffre zurück.

Einige Chiffren akzeptieren Schlüssel und Initialisierungsvektoren variabler Länge. Standardmäßig gibt die Methode crypto.getCipherInfo() die Standardwerte für diese Chiffren zurück. Um zu testen, ob eine gegebene Schlüssellänge oder IV-Länge für eine gegebene Chiffre akzeptabel ist, verwenden Sie die Optionen keyLength und ivLength. Wenn die angegebenen Werte nicht akzeptabel sind, wird undefined zurückgegeben.

crypto.getCiphers() ​

Hinzugefügt in: v0.9.3

  • Gibt zurück: <string[]> Ein Array mit den Namen der unterstützten Chiffrieralgorithmen.
js
const { getCiphers } = await import('node:crypto')

console.log(getCiphers()) // ['aes-128-cbc', 'aes-128-ccm', ...]
js
const { getCiphers } = require('node:crypto')

console.log(getCiphers()) // ['aes-128-cbc', 'aes-128-ccm', ...]

crypto.getCurves() ​

Hinzugefügt in: v2.3.0

  • Gibt zurück: <string[]> Ein Array mit den Namen der unterstützten elliptischen Kurven.
js
const { getCurves } = await import('node:crypto')

console.log(getCurves()) // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]
js
const { getCurves } = require('node:crypto')

console.log(getCurves()) // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]

crypto.getDiffieHellman(groupName) ​

Hinzugefügt in: v0.7.5

Erstellt ein vordefiniertes DiffieHellmanGroup-Schlüsselaustauschobjekt. Die unterstützten Gruppen sind in der Dokumentation zu DiffieHellmanGroup aufgeführt.

Das zurückgegebene Objekt ahmt die Schnittstelle von Objekten nach, die von crypto.createDiffieHellman() erstellt wurden, erlaubt aber nicht die Änderung der Schlüssel (z. B. mit diffieHellman.setPublicKey()). Der Vorteil dieser Methode besteht darin, dass die Parteien keinen Gruppenmodul generieren oder austauschen müssen, wodurch sowohl Prozessor- als auch Kommunikationszeit gespart werden.

Beispiel (Erhalten eines gemeinsamen Geheimnisses):

js
const { getDiffieHellman } = await import('node:crypto')
const alice = getDiffieHellman('modp14')
const bob = getDiffieHellman('modp14')

alice.generateKeys()
bob.generateKeys()

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex')
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex')

/* aliceSecret und bobSecret sollten identisch sein */
console.log(aliceSecret === bobSecret)
js
const { getDiffieHellman } = require('node:crypto')

const alice = getDiffieHellman('modp14')
const bob = getDiffieHellman('modp14')

alice.generateKeys()
bob.generateKeys()

const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex')
const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex')

/* aliceSecret und bobSecret sollten identisch sein */
console.log(aliceSecret === bobSecret)

crypto.getFips() ​

Hinzugefügt in: v10.0.0

  • Rückgabewert: <number> 1, wenn und nur wenn ein FIPS-kompatibler Krypto-Anbieter derzeit verwendet wird, andernfalls 0. Eine zukünftige semver-major-Version kann den Rückgabetyp dieser API in einen <boolean> ändern.

crypto.getHashes() ​

Hinzugefügt in: v0.9.3

  • Rückgabewert: <string[]> Ein Array mit den Namen der unterstützten Hash-Algorithmen, wie z. B. 'RSA-SHA256'. Hash-Algorithmen werden auch als "Digest"-Algorithmen bezeichnet.
js
const { getHashes } = await import('node:crypto')

console.log(getHashes()) // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]
js
const { getHashes } = require('node:crypto')

console.log(getHashes()) // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...]

crypto.getRandomValues(typedArray) ​

Hinzugefügt in: v17.4.0

Ein praktischer Alias für crypto.webcrypto.getRandomValues(). Diese Implementierung entspricht nicht der Web Crypto-Spezifikation. Um webkompatible Code zu schreiben, verwenden Sie stattdessen crypto.webcrypto.getRandomValues().

crypto.hash(algorithm, data[, outputEncoding]) ​

Hinzugefügt in: v21.7.0, v20.12.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1.2 - Release Candidate

  • algorithm <string> | <undefined>
  • data <string> | <Buffer> | <TypedArray> | <DataView> Wenn data eine Zeichenkette ist, wird sie vor dem Hashing als UTF-8 codiert. Wenn eine andere Eingabecodierung für eine Zeichenketteneingabe gewünscht wird, kann der Benutzer die Zeichenkette mit TextEncoder oder Buffer.from() in ein TypedArray codieren und das codierte TypedArray stattdessen an diese API übergeben.
  • outputEncoding <string> | <undefined> Codierung, die verwendet wird, um die zurückgegebene Prüfsumme zu codieren. Standard: 'hex'.
  • Gibt zurück: <string> | <Buffer>

Ein Dienstprogramm zum Erstellen von einmaligen Hash-Prüfsummen von Daten. Es kann schneller sein als das objektbasierte crypto.createHash(), wenn eine kleinere Datenmenge (<= 5 MB) gehasht wird, die leicht verfügbar ist. Wenn die Daten groß sein können oder gestreamt werden, empfiehlt es sich dennoch, stattdessen crypto.createHash() zu verwenden.

Der algorithm hängt von den verfügbaren Algorithmen ab, die von der OpenSSL-Version auf der Plattform unterstützt werden. Beispiele sind 'sha256', 'sha512' usw. Bei neueren Versionen von OpenSSL zeigt openssl list -digest-algorithms die verfügbaren Digest-Algorithmen an.

Beispiel:

js
const crypto = require('node:crypto')
const { Buffer } = require('node:buffer')

// Hashing einer Zeichenkette und Rückgabe des Ergebnisses als hexadezimal codierte Zeichenkette.
const string = 'Node.js'
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string))

// Codieren einer Base64-codierten Zeichenkette in einen Buffer, Hashen und Rückgabe
// des Ergebnisses als Buffer.
const base64 = 'Tm9kZS5qcw=='
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'))
js
import crypto from 'node:crypto'
import { Buffer } from 'node:buffer'

// Hashing einer Zeichenkette und Rückgabe des Ergebnisses als hexadezimal codierte Zeichenkette.
const string = 'Node.js'
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string))

// Codieren einer Base64-codierten Zeichenkette in einen Buffer, Hashen und Rückgabe
// des Ergebnisses als Buffer.
const base64 = 'Tm9kZS5qcw=='
// <Buffer 10 b3 49 32 87 f8 31 e8 1a 43 88 11 a1 ff ba 01 f8 ce c4 b7>
console.log(crypto.hash('sha1', Buffer.from(base64, 'base64'), 'buffer'))

crypto.hkdf(digest, ikm, salt, info, keylen, callback) ​

[Historie]

VersionÄnderungen
v18.0.0Das Übergeben eines ungültigen Callbacks an das Argument callback löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v18.8.0, v16.18.0Das Eingabe-Keying-Material kann nun die Länge Null haben.
v15.0.0Hinzugefügt in: v15.0.0

HKDF ist eine einfache Schlüsselableitungsfunktion, die in RFC 5869 definiert ist. Die angegebenen ikm, salt und info werden mit dem digest verwendet, um einen Schlüssel mit keylen Bytes abzuleiten.

Die bereitgestellte callback-Funktion wird mit zwei Argumenten aufgerufen: err und derivedKey. Wenn während der Ableitung des Schlüssels ein Fehler auftritt, wird err gesetzt; andernfalls ist err null. Der erfolgreich generierte derivedKey wird als <ArrayBuffer> an den Callback übergeben. Ein Fehler wird ausgelöst, wenn eines der Eingabeargumente ungültige Werte oder Typen angibt.

js
import { Buffer } from 'node:buffer'
const { hkdf } = await import('node:crypto')

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(Buffer.from(derivedKey).toString('hex')) // '24156e2...5391653'
})
js
const { hkdf } = require('node:crypto')
const { Buffer } = require('node:buffer')

hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(Buffer.from(derivedKey).toString('hex')) // '24156e2...5391653'
})

crypto.hkdfSync(digest, ikm, salt, info, keylen) ​

[Historie]

VersionÄnderungen
v18.8.0, v16.18.0Das Eingabe-Keying-Material kann jetzt die Länge Null haben.
v15.0.0Hinzugefügt in: v15.0.0

Stellt eine synchrone HKDF-Schlüsselerzeugungsfunktion gemäß RFC 5869 bereit. Die angegebenen ikm, salt und info werden mit dem digest verwendet, um einen Schlüssel mit keylen Bytes abzuleiten.

Der erfolgreich generierte derivedKey wird als <ArrayBuffer> zurückgegeben.

Ein Fehler wird ausgelöst, wenn einer der Eingabeargumente ungültige Werte oder Typen angibt oder wenn der abgeleitete Schlüssel nicht generiert werden kann.

js
import { Buffer } from 'node:buffer'
const { hkdfSync } = await import('node:crypto')

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64)
console.log(Buffer.from(derivedKey).toString('hex')) // '24156e2...5391653'
js
const { hkdfSync } = require('node:crypto')
const { Buffer } = require('node:buffer')

const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64)
console.log(Buffer.from(derivedKey).toString('hex')) // '24156e2...5391653'

crypto.pbkdf2(password, salt, iterations, keylen, digest, callback) ​

[Verlauf]

VersionÄnderungen
v18.0.0Das Übergeben eines ungültigen Callbacks an das Argument callback löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v15.0.0Die Argumente password und salt können auch ArrayBuffer-Instanzen sein.
v14.0.0Der Parameter iterations ist jetzt auf positive Werte beschränkt. Frühere Versionen behandelten andere Werte als eins.
v8.0.0Der Parameter digest ist jetzt immer erforderlich.
v6.0.0Das Aufrufen dieser Funktion ohne den Parameter digest ist jetzt veraltet und gibt eine Warnung aus.
v6.0.0Die Standardcodierung für password, wenn es sich um eine Zeichenkette handelt, wurde von binary auf utf8 geändert.
v0.5.5Hinzugefügt in: v0.5.5

Stellt eine asynchrone Implementierung der Password-Based Key Derivation Function 2 (PBKDF2) bereit. Ein ausgewählter HMAC-Digest-Algorithmus, der durch digest angegeben wird, wird angewendet, um einen Schlüssel der angeforderten Bytelänge (keylen) aus dem password, salt und iterations abzuleiten.

Die bereitgestellte callback-Funktion wird mit zwei Argumenten aufgerufen: err und derivedKey. Wenn während der Ableitung des Schlüssels ein Fehler auftritt, wird err gesetzt; andernfalls ist err null. Standardmäßig wird der erfolgreich generierte derivedKey als Buffer an den Callback übergeben. Ein Fehler wird geworfen, wenn eines der Eingabeargumente ungültige Werte oder Typen angibt.

Das Argument iterations muss eine Zahl sein, die so hoch wie möglich eingestellt ist. Je höher die Anzahl der Iterationen, desto sicherer ist der abgeleitete Schlüssel, aber die Ausführung dauert länger.

Der salt sollte so eindeutig wie möglich sein. Es wird empfohlen, dass ein Salt zufällig und mindestens 16 Bytes lang ist. Details finden Sie in NIST SP 800-132.

Bitte beachten Sie die Warnhinweise bei der Verwendung von Zeichenketten als Eingaben für kryptografische APIs, wenn Sie Zeichenketten für password oder salt übergeben.

js
const { pbkdf2 } = await import('node:crypto')

pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})
js
const { pbkdf2 } = require('node:crypto')

pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})

Ein Array unterstützter Digest-Funktionen kann mit crypto.getHashes() abgerufen werden.

Diese API verwendet den Threadpool von libuv, der für einige Anwendungen überraschende und negative Auswirkungen auf die Leistung haben kann; siehe die Dokumentation zu UV_THREADPOOL_SIZE für weitere Informationen.

crypto.pbkdf2Sync(password, salt, iterations, keylen, digest) ​

[Verlauf]

VersionÄnderungen
v14.0.0Der Parameter iterations ist jetzt auf positive Werte beschränkt. Frühere Versionen behandelten andere Werte als eins.
v6.0.0Das Aufrufen dieser Funktion ohne den Parameter digest ist jetzt veraltet und gibt eine Warnung aus.
v6.0.0Die Standardcodierung für password, wenn es sich um eine Zeichenkette handelt, wurde von binary auf utf8 geändert.
v0.9.3Hinzugefügt in: v0.9.3

Stellt eine synchrone Implementierung der Password-Based Key Derivation Function 2 (PBKDF2) bereit. Ein ausgewählter HMAC-Digest-Algorithmus, der durch digest angegeben wird, wird angewendet, um einen Schlüssel der angeforderten Bytelänge (keylen) aus dem password, salt und iterations abzuleiten.

Wenn ein Fehler auftritt, wird ein Error ausgelöst, andernfalls wird der abgeleitete Schlüssel als Buffer zurückgegeben.

Das Argument iterations muss eine möglichst hohe Zahl sein. Je höher die Anzahl der Iterationen, desto sicherer ist der abgeleitete Schlüssel, aber die Ausführung dauert länger.

Der salt sollte möglichst eindeutig sein. Es wird empfohlen, dass ein Salt zufällig und mindestens 16 Byte lang ist. Details finden Sie in NIST SP 800-132.

Wenn Sie Zeichenketten für password oder salt übergeben, beachten Sie bitte die Warnungen bei der Verwendung von Zeichenketten als Eingaben für kryptografische APIs.

js
const { pbkdf2Sync } = await import('node:crypto')

const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512')
console.log(key.toString('hex')) // '3745e48...08d59ae'
js
const { pbkdf2Sync } = require('node:crypto')

const key = pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512')
console.log(key.toString('hex')) // '3745e48...08d59ae'

Ein Array der unterstützten Digest-Funktionen kann mit crypto.getHashes() abgerufen werden.

crypto.privateDecrypt(privateKey, buffer) ​

[Historie]

VersionÄnderungen
v21.6.2, v20.11.1, v18.19.1Die RSA_PKCS1_PADDING-Füllung wurde deaktiviert, es sei denn, der OpenSSL-Build unterstützt die implizite Ablehnung.
v15.0.0String, ArrayBuffer und CryptoKey als zulässige Schlüsseltypen hinzugefügt. Das oaepLabel kann ein ArrayBuffer sein. Der Puffer kann ein String oder ArrayBuffer sein. Alle Typen, die Puffer akzeptieren, sind auf maximal 2 ** 31 - 1 Bytes beschränkt.
v12.11.0Die Option oaepLabel wurde hinzugefügt.
v12.9.0Die Option oaepHash wurde hinzugefügt.
v11.6.0Diese Funktion unterstützt jetzt Schlüssel Objekte.
v0.11.14Hinzugefügt in: v0.11.14

Entschlüsselt buffer mit privateKey. buffer wurde zuvor mit dem entsprechenden öffentlichen Schlüssel verschlüsselt, z. B. mit crypto.publicEncrypt().

Wenn privateKey kein KeyObject ist, verhält sich diese Funktion so, als wäre privateKey an crypto.createPrivateKey() übergeben worden. Wenn es sich um ein Objekt handelt, kann die Eigenschaft padding übergeben werden. Andernfalls verwendet diese Funktion RSA_PKCS1_OAEP_PADDING.

Die Verwendung von crypto.constants.RSA_PKCS1_PADDING in crypto.privateDecrypt() erfordert, dass OpenSSL die implizite Ablehnung (rsa_pkcs1_implicit_rejection) unterstützt. Wenn die von Node.js verwendete OpenSSL-Version diese Funktion nicht unterstützt, schlägt der Versuch, RSA_PKCS1_PADDING zu verwenden, fehl.

crypto.privateEncrypt(privateKey, buffer) ​

[Historie]

VersionÄnderungen
v15.0.0String, ArrayBuffer und CryptoKey als zulässige Schlüsseltypen hinzugefügt. Die Passphrase kann ein ArrayBuffer sein. Der Puffer kann ein String oder ArrayBuffer sein. Alle Typen, die Puffer akzeptieren, sind auf maximal 2 ** 31 - 1 Bytes begrenzt.
v11.6.0Diese Funktion unterstützt jetzt Schlüssel-Objekte.
v1.1.0Hinzugefügt in: v1.1.0

Verschlüsselt buffer mit privateKey. Die zurückgegebenen Daten können mit dem entsprechenden öffentlichen Schlüssel entschlüsselt werden, beispielsweise mit crypto.publicDecrypt().

Wenn privateKey kein KeyObject ist, verhält sich diese Funktion so, als wäre privateKey an crypto.createPrivateKey() übergeben worden. Wenn es sich um ein Objekt handelt, kann die Eigenschaft padding übergeben werden. Andernfalls verwendet diese Funktion RSA_PKCS1_PADDING.

crypto.publicDecrypt(key, buffer) ​

[Verlauf]

VersionÄnderungen
v15.0.0String, ArrayBuffer und CryptoKey als zulässige Schlüsseltypen hinzugefügt. Das Passwort kann ein ArrayBuffer sein. Der Puffer kann ein String oder ArrayBuffer sein. Alle Typen, die Puffer akzeptieren, sind auf maximal 2 ** 31 - 1 Byte begrenzt.
v11.6.0Diese Funktion unterstützt jetzt Schlüssel Objekte.
v1.1.0Hinzugefügt in: v1.1.0

Entschlüsselt buffer mit key. buffer wurde zuvor mit dem entsprechenden privaten Schlüssel verschlüsselt, z. B. mit crypto.privateEncrypt().

Wenn key kein KeyObject ist, verhält sich diese Funktion so, als wäre key an crypto.createPublicKey() übergeben worden. Wenn es sich um ein Objekt handelt, kann die Eigenschaft padding übergeben werden. Andernfalls verwendet diese Funktion RSA_PKCS1_PADDING.

Da RSA-öffentliche Schlüssel von privaten Schlüsseln abgeleitet werden können, kann stattdessen ein privater Schlüssel anstelle eines öffentlichen Schlüssels übergeben werden.

crypto.publicEncrypt(key, buffer) ​

[Historie]

VersionÄnderungen
v15.0.0String, ArrayBuffer und CryptoKey als zulässige Schlüsseltypen hinzugefügt. oaepLabel und passphrase können ArrayBuffers sein. Der Puffer kann ein String oder ArrayBuffer sein. Alle Typen, die Puffer akzeptieren, sind auf maximal 2 ** 31 - 1 Bytes begrenzt.
v12.11.0Die Option oaepLabel wurde hinzugefügt.
v12.9.0Die Option oaepHash wurde hinzugefügt.
v11.6.0Diese Funktion unterstützt jetzt Schlüssel Objekte.
v0.11.14Hinzugefügt in: v0.11.14

Verschlüsselt den Inhalt von buffer mit key und gibt einen neuen Buffer mit dem verschlüsselten Inhalt zurück. Die zurückgegebenen Daten können mit dem entsprechenden privaten Schlüssel entschlüsselt werden, z. B. mit crypto.privateDecrypt().

Wenn key kein KeyObject ist, verhält sich diese Funktion so, als wäre key an crypto.createPublicKey() übergeben worden. Wenn es sich um ein Objekt handelt, kann die Eigenschaft padding übergeben werden. Andernfalls verwendet diese Funktion RSA_PKCS1_OAEP_PADDING.

Da öffentliche RSA-Schlüssel von privaten Schlüsseln abgeleitet werden können, kann stattdessen ein privater Schlüssel anstelle eines öffentlichen Schlüssels übergeben werden.

crypto.randomBytes(size[, callback]) ​

[Verlauf]

VersionÄnderungen
v18.0.0Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v9.0.0Das Übergeben von null als callback-Argument löst nun ERR_INVALID_CALLBACK aus.
v0.5.8Hinzugefügt in: v0.5.8

  • size <number> Die Anzahl der zu generierenden Bytes. size darf nicht größer als 2**31 - 1 sein.

  • callback <Function>

  • Rückgabewert: <Buffer> wenn die callback-Funktion nicht angegeben wird.

Generiert kryptografisch sichere pseudorandom Daten. Das Argument size ist eine Zahl, die die Anzahl der zu generierenden Bytes angibt.

Wenn eine callback-Funktion angegeben wird, werden die Bytes asynchron generiert und die callback-Funktion wird mit zwei Argumenten aufgerufen: err und buf. Tritt ein Fehler auf, ist err ein Error-Objekt; andernfalls ist es null. Das Argument buf ist ein Buffer, der die generierten Bytes enthält.

js
// Asynchron
const { randomBytes } = await import('node:crypto')

randomBytes(256, (err, buf) => {
  if (err) throw err
  console.log(`${buf.length} Bytes Zufallsdaten: ${buf.toString('hex')}`)
})
js
// Asynchron
const { randomBytes } = require('node:crypto')

randomBytes(256, (err, buf) => {
  if (err) throw err
  console.log(`${buf.length} Bytes Zufallsdaten: ${buf.toString('hex')}`)
})

Wird die callback-Funktion nicht angegeben, werden die Zufallsbytes synchron generiert und als Buffer zurückgegeben. Ein Fehler wird ausgelöst, wenn bei der Generierung der Bytes ein Problem auftritt.

js
// Synchron
const { randomBytes } = await import('node:crypto')

const buf = randomBytes(256)
console.log(`${buf.length} Bytes Zufallsdaten: ${buf.toString('hex')}`)
js
// Synchron
const { randomBytes } = require('node:crypto')

const buf = randomBytes(256)
console.log(`${buf.length} Bytes Zufallsdaten: ${buf.toString('hex')}`)

Die Methode crypto.randomBytes() wird erst abgeschlossen, wenn genügend Entropie verfügbar ist. Dies sollte normalerweise nie länger als ein paar Millisekunden dauern. Die einzige Zeit, in der die Generierung der Zufallsbytes möglicherweise für einen längeren Zeitraum blockiert, ist direkt nach dem Booten, wenn das gesamte System noch wenig Entropie hat.

Diese API verwendet den Threadpool von libuv, der für einige Anwendungen überraschende und negative Auswirkungen auf die Leistung haben kann; siehe die Dokumentation zu UV_THREADPOOL_SIZE für weitere Informationen.

Die asynchrone Version von crypto.randomBytes() wird in einer einzigen Threadpool-Anforderung ausgeführt. Um die Varianz der Threadpool-Tasklänge zu minimieren, teilen Sie große randomBytes-Anforderungen auf, wenn dies im Rahmen der Erfüllung einer Client-Anforderung geschieht.

crypto.randomFill(buffer[, offset][, size], callback) ​

[Verlauf]

VersionÄnderungen
v18.0.0Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v9.0.0Das Argument buffer kann ein beliebiger TypedArray oder DataView sein.
v7.10.0, v6.13.0Hinzugefügt in: v7.10.0, v6.13.0

Diese Funktion ähnelt crypto.randomBytes(), erfordert aber, dass das erste Argument ein Buffer ist, der gefüllt wird. Es ist auch erforderlich, einen Callback zu übergeben.

Wenn die callback-Funktion nicht bereitgestellt wird, wird ein Fehler ausgelöst.

js
import { Buffer } from 'node:buffer'
const { randomFill } = await import('node:crypto')

const buf = Buffer.alloc(10)
randomFill(buf, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

randomFill(buf, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

// Das Obige entspricht folgendem:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})
js
const { randomFill } = require('node:crypto')
const { Buffer } = require('node:buffer')

const buf = Buffer.alloc(10)
randomFill(buf, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

randomFill(buf, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

// Das Obige entspricht folgendem:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

Jede ArrayBuffer, TypedArray oder DataView Instanz kann als buffer übergeben werden.

Obwohl dies Instanzen von Float32Array und Float64Array einschließt, sollte diese Funktion nicht zum Generieren von zufälligen Gleitkommazahlen verwendet werden. Das Ergebnis kann +Infinity, -Infinity und NaN enthalten, und selbst wenn das Array nur endliche Zahlen enthält, werden diese nicht aus einer gleichmäßigen Zufallsverteilung gezogen und haben keine sinnvollen unteren oder oberen Grenzen.

js
import { Buffer } from 'node:buffer'
const { randomFill } = await import('node:crypto')

const a = new Uint32Array(10)
randomFill(a, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString('hex'))
})

const b = new DataView(new ArrayBuffer(10))
randomFill(b, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString('hex'))
})

const c = new ArrayBuffer(10)
randomFill(c, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf).toString('hex'))
})
js
const { randomFill } = require('node:crypto')
const { Buffer } = require('node:buffer')

const a = new Uint32Array(10)
randomFill(a, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString('hex'))
})

const b = new DataView(new ArrayBuffer(10))
randomFill(b, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString('hex'))
})

const c = new ArrayBuffer(10)
randomFill(c, (err, buf) => {
  if (err) throw err
  console.log(Buffer.from(buf).toString('hex'))
})

Diese API verwendet den Threadpool von libuv, der für einige Anwendungen überraschende und negative Auswirkungen auf die Leistung haben kann; siehe die Dokumentation zu UV_THREADPOOL_SIZE für weitere Informationen.

Die asynchrone Version von crypto.randomFill() wird in einer einzigen Threadpool-Anforderung ausgeführt. Um die Varianz der Threadpool-Tasklänge zu minimieren, sollten große randomFill-Anforderungen partitioniert werden, wenn dies im Rahmen der Erfüllung einer Client-Anforderung geschieht.

crypto.randomFillSync(buffer[, offset][, size]) ​

[Verlauf]

VersionÄnderungen
v9.0.0Das Argument buffer kann ein beliebiges TypedArray oder DataView sein.
v7.10.0, v6.13.0Hinzugefügt in: v7.10.0, v6.13.0

Synchrone Version von crypto.randomFill().

js
import { Buffer } from 'node:buffer'
const { randomFillSync } = await import('node:crypto')

const buf = Buffer.alloc(10)
console.log(randomFillSync(buf).toString('hex'))

randomFillSync(buf, 5)
console.log(buf.toString('hex'))

// Das Obige entspricht folgendem:
randomFillSync(buf, 5, 5)
console.log(buf.toString('hex'))
js
const { randomFillSync } = require('node:crypto')
const { Buffer } = require('node:buffer')

const buf = Buffer.alloc(10)
console.log(randomFillSync(buf).toString('hex'))

randomFillSync(buf, 5)
console.log(buf.toString('hex'))

// Das Obige entspricht folgendem:
randomFillSync(buf, 5, 5)
console.log(buf.toString('hex'))

Es kann jede ArrayBuffer, TypedArray oder DataView Instanz als buffer übergeben werden.

js
import { Buffer } from 'node:buffer'
const { randomFillSync } = await import('node:crypto')

const a = new Uint32Array(10)
console.log(Buffer.from(randomFillSync(a).buffer, a.byteOffset, a.byteLength).toString('hex'))

const b = new DataView(new ArrayBuffer(10))
console.log(Buffer.from(randomFillSync(b).buffer, b.byteOffset, b.byteLength).toString('hex'))

const c = new ArrayBuffer(10)
console.log(Buffer.from(randomFillSync(c)).toString('hex'))
js
const { randomFillSync } = require('node:crypto')
const { Buffer } = require('node:buffer')

const a = new Uint32Array(10)
console.log(Buffer.from(randomFillSync(a).buffer, a.byteOffset, a.byteLength).toString('hex'))

const b = new DataView(new ArrayBuffer(10))
console.log(Buffer.from(randomFillSync(b).buffer, b.byteOffset, b.byteLength).toString('hex'))

const c = new ArrayBuffer(10)
console.log(Buffer.from(randomFillSync(c)).toString('hex'))

crypto.randomInt([min, ]max[, callback]) ​

[Verlauf]

VersionÄnderungen
v18.0.0Das Übergeben einer ungültigen Callback-Funktion an das Argument callback löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v14.10.0, v12.19.0Hinzugefügt in: v14.10.0, v12.19.0
  • min <Ganzzahl> Beginn des Zufallsbereichs (inklusiv). Standardwert: 0.
  • max <Ganzzahl> Ende des Zufallsbereichs (exklusiv).
  • callback <Funktion> function(err, n) {}.

Gibt eine Zufallsganzzah n zurück, so dass min \<= n \< max. Diese Implementierung vermeidet Modulo-Bias.

Der Bereich (max - min) muss kleiner als 2 sein. min und max müssen sichere Ganzzahlen sein.

Wenn die callback-Funktion nicht angegeben wird, wird die Zufallsganzzah synchron generiert.

js
// Asynchron
const { randomInt } = await import('node:crypto')

randomInt(3, (err, n) => {
  if (err) throw err
  console.log(`Zufallszahl aus (0, 1, 2) gewählt: ${n}`)
})
js
// Asynchron
const { randomInt } = require('node:crypto')

randomInt(3, (err, n) => {
  if (err) throw err
  console.log(`Zufallszahl aus (0, 1, 2) gewählt: ${n}`)
})
js
// Synchron
const { randomInt } = await import('node:crypto')

const n = randomInt(3)
console.log(`Zufallszahl aus (0, 1, 2) gewählt: ${n}`)
js
// Synchron
const { randomInt } = require('node:crypto')

const n = randomInt(3)
console.log(`Zufallszahl aus (0, 1, 2) gewählt: ${n}`)
js
// Mit `min`-Argument
const { randomInt } = await import('node:crypto')

const n = randomInt(1, 7)
console.log(`Der Würfel zeigt: ${n}`)
js
// Mit `min`-Argument
const { randomInt } = require('node:crypto')

const n = randomInt(1, 7)
console.log(`Der Würfel zeigt: ${n}`)

crypto.randomUUID([options]) ​

Hinzugefügt in: v15.6.0, v14.17.0

  • options <Object>

    • disableEntropyCache <boolean> Standardmäßig generiert und zwischert Node.js zur Performance-Steigerung genügend Zufallsdaten, um bis zu 128 zufällige UUIDs zu generieren. Um eine UUID zu generieren, ohne den Cache zu verwenden, setzen Sie disableEntropyCache auf true. Standard: false.

  • Rückgabewert: <string>

Generiert eine zufällige RFC 4122 Version 4 UUID. Die UUID wird mithilfe eines kryptografischen pseudorandom number generators generiert.

crypto.scrypt(password, salt, keylen[, options], callback) ​

[Verlauf]

VersionÄnderungen
v18.0.0Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v15.0.0Die Argumente password und salt können auch ArrayBuffer-Instanzen sein.
v12.8.0, v10.17.0Der maxmem-Wert kann nun jede sichere ganze Zahl sein.
v10.9.0Die Optionsnamen cost, blockSize und parallelization wurden hinzugefügt.
v10.5.0Hinzugefügt in: v10.5.0

Stellt eine asynchrone scrypt-Implementierung bereit. Scrypt ist eine kennwortbasierte Schlüsselherleitungsfunktion, die so konzipiert ist, dass sie rechen- und speicherintensiv ist, um Brute-Force-Angriffe unrentabel zu machen.

Der salt sollte so einzigartig wie möglich sein. Es wird empfohlen, dass ein Salt zufällig und mindestens 16 Byte lang ist. Siehe NIST SP 800-132 für Details.

Bei der Verwendung von Strings für password oder salt beachten Sie bitte die Warnungen bei der Verwendung von Strings als Eingabe für kryptografische APIs.

Die callback-Funktion wird mit zwei Argumenten aufgerufen: err und derivedKey. err ist ein Ausnahmeobjekt, wenn die Schlüsselherleitung fehlschlägt, andernfalls ist err null. derivedKey wird als Buffer an den Callback übergeben.

Eine Ausnahme wird ausgelöst, wenn eines der Eingabeargumente ungültige Werte oder Typen angibt.

js
const { scrypt } = await import('node:crypto')

// Verwendung der Standardwerte.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})
// Verwendung eines benutzerdefinierten N-Parameters. Muss eine Zweierpotenz sein.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...aa39b34'
})
js
const { scrypt } = require('node:crypto')

// Verwendung der Standardwerte.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})
// Verwendung eines benutzerdefinierten N-Parameters. Muss eine Zweierpotenz sein.
scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...aa39b34'
})

crypto.scryptSync(password, salt, keylen[, options]) ​

[Verlauf]

VersionÄnderungen
v12.8.0, v10.17.0Der Wert von maxmem kann nun eine beliebige sichere Ganzzahl sein.
v10.9.0Die Optionsnamen cost, blockSize und parallelization wurden hinzugefügt.
v10.5.0Hinzugefügt in: v10.5.0

Stellt eine synchrone scrypt-Implementierung bereit. Scrypt ist eine passwortbasierte Schlüsselableitungsfunktion, die so konzipiert ist, dass sie rechen- und speicherintensiv ist, um Brute-Force-Angriffe unrentabel zu machen.

Der salt sollte so eindeutig wie möglich sein. Es wird empfohlen, dass ein Salt zufällig und mindestens 16 Byte lang ist. Einzelheiten finden Sie in NIST SP 800-132.

Wenn Sie Strings für password oder salt übergeben, beachten Sie bitte die Warnungen bei der Verwendung von Strings als Eingaben für kryptografische APIs.

Eine Ausnahme wird ausgelöst, wenn die Schlüsselableitung fehlschlägt, andernfalls wird der abgeleitete Schlüssel als Buffer zurückgegeben.

Eine Ausnahme wird ausgelöst, wenn einer der Eingabeargumente ungültige Werte oder Typen angibt.

js
const { scryptSync } = await import('node:crypto')
// Verwendung der werkseitigen Standardeinstellungen.

const key1 = scryptSync('password', 'salt', 64)
console.log(key1.toString('hex')) // '3745e48...08d59ae'
// Verwendung eines benutzerdefinierten N-Parameters. Muss eine Zweierpotenz sein.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 })
console.log(key2.toString('hex')) // '3745e48...aa39b34'
js
const { scryptSync } = require('node:crypto')
// Verwendung der werkseitigen Standardeinstellungen.

const key1 = scryptSync('password', 'salt', 64)
console.log(key1.toString('hex')) // '3745e48...08d59ae'
// Verwendung eines benutzerdefinierten N-Parameters. Muss eine Zweierpotenz sein.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 })
console.log(key2.toString('hex')) // '3745e48...aa39b34'

crypto.secureHeapUsed() ​

Hinzugefügt in: v15.6.0

  • Rückgabewert: <Object>
    • total <number> Die insgesamt zugewiesene Größe des sicheren Heaps, wie mit dem Befehlszeilenflag --secure-heap=n angegeben.
    • min <number> Die minimale Zuweisung aus dem sicheren Heap, wie mit dem Befehlszeilenflag --secure-heap-min angegeben.
    • used <number> Die Gesamtzahl der aktuell aus dem sicheren Heap zugewiesenen Bytes.
    • utilization <number> Das berechnete Verhältnis von used zu total zugewiesenen Bytes.

crypto.setEngine(engine[, flags]) ​

[Verlauf]

VersionÄnderungen
v22.4.0, v20.16.0Unterstützung benutzerdefinierter Engines in OpenSSL 3 ist veraltet.
v0.11.11Hinzugefügt in: v0.11.11

Lädt und setzt die engine für einige oder alle OpenSSL-Funktionen (ausgewählt durch flags). Die Unterstützung für benutzerdefinierte Engines in OpenSSL ist ab OpenSSL 3 veraltet.

engine kann entweder eine ID oder ein Pfad zur gemeinsam genutzten Bibliothek der Engine sein.

Das optionale Argument flags verwendet standardmäßig ENGINE_METHOD_ALL. flags ist ein Bitfeld, das eines oder eine Mischung der folgenden Flags (definiert in crypto.constants) annimmt:

  • crypto.constants.ENGINE_METHOD_RSA
  • crypto.constants.ENGINE_METHOD_DSA
  • crypto.constants.ENGINE_METHOD_DH
  • crypto.constants.ENGINE_METHOD_RAND
  • crypto.constants.ENGINE_METHOD_EC
  • crypto.constants.ENGINE_METHOD_CIPHERS
  • crypto.constants.ENGINE_METHOD_DIGESTS
  • crypto.constants.ENGINE_METHOD_PKEY_METHS
  • crypto.constants.ENGINE_METHOD_PKEY_ASN1_METHS
  • crypto.constants.ENGINE_METHOD_ALL
  • crypto.constants.ENGINE_METHOD_NONE

crypto.setFips(bool) ​

Hinzugefügt in: v10.0.0

  • bool <boolean> true um den FIPS-Modus zu aktivieren.

Aktiviert den FIPS-konformen Kryptografie-Provider in einem FIPS-fähigen Node.js-Build. Wirft einen Fehler, wenn der FIPS-Modus nicht verfügbar ist.

crypto.sign(algorithm, data, key[, callback]) ​

[Verlauf]

VersionÄnderungen
v18.0.0Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v15.12.0Optionales Callback-Argument hinzugefügt.
v13.2.0, v12.16.0Diese Funktion unterstützt jetzt IEEE-P1363 DSA- und ECDSA-Signaturen.
v12.0.0Hinzugefügt in: v12.0.0

Berechnet und gibt die Signatur für data unter Verwendung des angegebenen privaten Schlüssels und Algorithmus zurück. Wenn algorithm null oder undefined ist, hängt der Algorithmus vom Schlüsseltyp ab (insbesondere Ed25519 und Ed448).

Wenn key kein KeyObject ist, verhält sich diese Funktion so, als ob key an crypto.createPrivateKey() übergeben worden wäre. Wenn es sich um ein Objekt handelt, können die folgenden zusätzlichen Eigenschaften übergeben werden:

  • dsaEncoding <string> Für DSA und ECDSA gibt diese Option das Format der generierten Signatur an. Es kann einer der folgenden Werte sein:

    • 'der' (Standard): DER-codierte ASN.1-Signaturstrukturcodierung (r, s).
    • 'ieee-p1363': Signaturformat r || s wie in IEEE-P1363 vorgeschlagen.

  • padding <integer> Optionaler Padding-Wert für RSA, einer der folgenden:

    • crypto.constants.RSA_PKCS1_PADDING (Standard)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

RSA_PKCS1_PSS_PADDING verwendet MGF1 mit der gleichen Hash-Funktion, die zum Signieren der Nachricht verwendet wird, wie in Abschnitt 3.1 von RFC 4055 angegeben.

  • saltLength <integer> Saltlänge, wenn Padding RSA_PKCS1_PSS_PADDING ist. Der spezielle Wert crypto.constants.RSA_PSS_SALTLEN_DIGEST setzt die Saltlänge auf die Digestgröße, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (Standard) setzt sie auf den maximal zulässigen Wert.

Wenn die callback-Funktion angegeben wird, verwendet diese Funktion den Threadpool von libuv.

crypto.subtle ​

Hinzugefügt in: v17.4.0

Ein praktischer Alias für crypto.webcrypto.subtle.

crypto.timingSafeEqual(a, b) ​

[Verlauf]

VersionÄnderungen
v15.0.0Die Argumente a und b können auch ArrayBuffer sein.
v6.6.0Hinzugefügt in: v6.6.0

Diese Funktion vergleicht die zugrundeliegenden Bytes, die die gegebenen ArrayBuffer, TypedArray oder DataView Instanzen repräsentieren, unter Verwendung eines konstanten Zeit-Algorithmus.

Diese Funktion gibt keine Zeitinformationen preis, die es einem Angreifer ermöglichen würden, einen der Werte zu erraten. Dies ist geeignet für den Vergleich von HMAC-Digests oder geheimer Werte wie Authentifizierungscookies oder Capability URLs.

a und b müssen beide Buffer, TypedArray oder DataView sein und die gleiche Bytelänge haben. Ein Fehler wird geworfen, wenn a und b unterschiedliche Bytelängen haben.

Wenn mindestens einer von a und b ein TypedArray mit mehr als einem Byte pro Eintrag ist, wie z.B. Uint16Array, wird das Ergebnis unter Verwendung der Plattform-Byte-Reihenfolge berechnet.

Wenn beide Eingaben Float32Arrays oder Float64Arrays sind, kann diese Funktion unerwartete Ergebnisse liefern, aufgrund der IEEE 754 Kodierung von Gleitkommazahlen. Insbesondere impliziert weder x === y noch Object.is(x, y), dass die Byte-Darstellungen von zwei Gleitkommazahlen x und y gleich sind.

Die Verwendung von crypto.timingSafeEqual garantiert nicht, dass der umgebende Code zeitsicher ist. Es ist darauf zu achten, dass der umgebende Code keine Zeitangriffe ermöglicht.

crypto.verify(algorithm, data, key, signature[, callback]) ​

[Historie]

VersionÄnderungen
v18.0.0Das Übergeben eines ungültigen Callbacks an das callback-Argument löst nun ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK aus.
v15.12.0Optionales Callback-Argument hinzugefügt.
v15.0.0Die Argumente data, key und signature können auch ArrayBuffer sein.
v13.2.0, v12.16.0Diese Funktion unterstützt jetzt IEEE-P1363 DSA- und ECDSA-Signaturen.
v12.0.0Hinzugefügt in: v12.0.0

Überprüft die gegebene Signatur für data unter Verwendung des gegebenen Schlüssels und Algorithmus. Wenn algorithm null oder undefined ist, hängt der Algorithmus vom Schlüsseltyp ab (insbesondere Ed25519 und Ed448).

Wenn key kein KeyObject ist, verhält sich diese Funktion so, als wäre key an crypto.createPublicKey() übergeben worden. Wenn es sich um ein Objekt handelt, können die folgenden zusätzlichen Eigenschaften übergeben werden:

  • dsaEncoding <string> Für DSA und ECDSA gibt diese Option das Format der Signatur an. Es kann einer der folgenden Werte sein:

    • 'der' (Standard): DER-kodierte ASN.1-Signaturstrukturkodierung (r, s).
    • 'ieee-p1363': Signaturformat r || s wie in IEEE-P1363 vorgeschlagen.

  • padding <integer> Optionaler Padding-Wert für RSA, einer der folgenden:

    • crypto.constants.RSA_PKCS1_PADDING (Standard)
    • crypto.constants.RSA_PKCS1_PSS_PADDING

RSA_PKCS1_PSS_PADDING verwendet MGF1 mit derselben Hash-Funktion, die zum Signieren der Nachricht verwendet wird, wie in Abschnitt 3.1 von RFC 4055 angegeben.

  • saltLength <integer> Saltlänge, wenn Padding RSA_PKCS1_PSS_PADDING ist. Der Sonderwert crypto.constants.RSA_PSS_SALTLEN_DIGEST setzt die Saltlänge auf die Digestgröße, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (Standard) setzt sie auf den maximal zulässigen Wert.

Das Argument signature ist die zuvor berechnete Signatur für data.

Da öffentliche Schlüssel von privaten Schlüsseln abgeleitet werden können, kann ein privater oder ein öffentlicher Schlüssel für key übergeben werden.

Wenn die callback-Funktion bereitgestellt wird, verwendet diese Funktion den Threadpool von libuv.

crypto.webcrypto ​

Hinzugefügt in: v15.0.0

Typ: <Crypto> Eine Implementierung des Web Crypto API Standards.

Siehe die Web Crypto API Dokumentation für Details.

Hinweise ​

Verwendung von Strings als Eingaben für kryptografische APIs ​

Aus historischen Gründen akzeptieren viele kryptografische APIs von Node.js Strings als Eingaben, obwohl der zugrunde liegende kryptografische Algorithmus mit Byte-Sequenzen arbeitet. Diese Fälle umfassen Klartexte, Chiffrate, symmetrische Schlüssel, Initialisierungsvektoren, Passphrasen, Salts, Authentifizierungs-Tags und zusätzliche authentifizierte Daten.

Bei der Übergabe von Strings an kryptografische APIs sollten die folgenden Faktoren berücksichtigt werden.

  • Nicht alle Byte-Sequenzen sind gültige UTF-8-Strings. Wenn daher eine Byte-Sequenz der Länge n von einem String abgeleitet wird, ist ihre Entropie im Allgemeinen niedriger als die Entropie einer zufälligen oder pseudorandomisierten n-Byte-Sequenz. Beispielsweise ergibt keine UTF-8-Zeichenkette die Byte-Sequenz c0 af. Geheime Schlüssel sollten fast ausschließlich zufällige oder pseudorandomisierte Byte-Sequenzen sein.
  • Ebenso können bei der Konvertierung von zufälligen oder pseudorandomisierten Byte-Sequenzen in UTF-8-Strings Teilsequenzen, die keine gültigen Codepunkte darstellen, durch das Unicode-Ersatzzeichen (U+FFFD) ersetzt werden. Die Byte-Darstellung des resultierenden Unicode-Strings ist daher möglicherweise nicht gleich der Byte-Sequenz, aus der der String erstellt wurde. Die Ausgaben von Chiffren, Hash-Funktionen, Signaturalgorithmen und Schlüsselableitungsfunktionen sind pseudorandomisierte Byte-Sequenzen und sollten nicht als Unicode-Strings verwendet werden.
  • Wenn Strings aus Benutzereingaben stammen, können einige Unicode-Zeichen auf mehrere äquivalente Weisen dargestellt werden, die zu unterschiedlichen Byte-Sequenzen führen. Beispielsweise hängt bei der Übergabe einer Benutzerpassphrase an eine Schlüsselableitungsfunktion wie PBKDF2 oder scrypt das Ergebnis der Schlüsselableitungsfunktion davon ab, ob der String zusammengesetzte oder zerlegte Zeichen verwendet. Node.js normalisiert Zeichenrepräsentationen nicht. Entwickler sollten die Verwendung von String.prototype.normalize() für Benutzereingaben in Betracht ziehen, bevor sie diese an kryptografische APIs übergeben.

Legacy Streams API (vor Node.js 0.10) ​

Das Crypto-Modul wurde Node.js hinzugefügt, bevor es das Konzept einer einheitlichen Stream-API und bevor es Buffer-Objekte zur Verarbeitung binärer Daten gab. Daher haben viele crypto-Klassen Methoden, die man typischerweise nicht in anderen Node.js-Klassen findet, die die Streams-API implementieren (z. B. update(), final() oder digest()). Außerdem akzeptierten und gaben viele Methoden standardmäßig 'latin1'-kodierte Zeichenketten anstelle von Buffers zurück. Diese Standardeinstellung wurde nach Node.js v0.8 geändert, um stattdessen standardmäßig Buffer-Objekte zu verwenden.

Unterstützung für schwache oder kompromittierte Algorithmen ​

Das Modul node:crypto unterstützt weiterhin einige Algorithmen, die bereits kompromittiert sind und nicht zur Verwendung empfohlen werden. Die API erlaubt auch die Verwendung von Chiffren und Hashes mit einer kleinen Schlüssellänge, die für eine sichere Verwendung zu schwach sind.

Benutzer tragen die volle Verantwortung für die Auswahl des Krypto-Algorithmus und der Schlüssellänge gemäß ihren Sicherheitsanforderungen.

Basierend auf den Empfehlungen von NIST SP 800-131A:

  • MD5 und SHA-1 sind nicht mehr akzeptabel, wenn Kollisionsresistenz erforderlich ist, z. B. bei digitalen Signaturen.
  • Es wird empfohlen, dass der Schlüssel bei RSA-, DSA- und DH-Algorithmen mindestens 2048 Bit und der der Kurve von ECDSA und ECDH mindestens 224 Bit aufweist, um für mehrere Jahre sicher zu sein.
  • Die DH-Gruppen von modp1, modp2 und modp5 haben eine Schlüssellänge von weniger als 2048 Bit und werden nicht empfohlen.

Weitere Empfehlungen und Details finden Sie in der Referenz.

Einige Algorithmen mit bekannten Schwächen und geringer praktischer Relevanz sind nur über den Legacy-Provider verfügbar, der nicht standardmäßig aktiviert ist.

CCM-Modus ​

CCM ist einer der unterstützten AEAD-Algorithmen. Anwendungen, die diesen Modus verwenden, müssen bestimmte Einschränkungen bei der Verwendung der Chiffre-API beachten:

  • Die Länge des Authentifizierungstags muss bei der Chiffrierstellung durch Setzen der Option authTagLength angegeben werden und muss 4, 6, 8, 10, 12, 14 oder 16 Byte betragen.
  • Die Länge des Initialisierungsvektors (Nonce) N muss zwischen 7 und 13 Byte liegen (7 ≤ N ≤ 13).
  • Die Länge des Klartexts ist auf 2 ** (8 * (15 - N)) Byte begrenzt.
  • Beim Entschlüsseln muss der Authentifizierungstag über setAuthTag() gesetzt werden, bevor update() aufgerufen wird. Andernfalls schlägt die Entschlüsselung fehl und final() löst einen Fehler gemäß Abschnitt 2.6 von RFC 3610 aus.
  • Die Verwendung von Stream-Methoden wie write(data), end(data) oder pipe() im CCM-Modus kann fehlschlagen, da CCM nicht mehr als einen Datenblock pro Instanz verarbeiten kann.
  • Bei der Übergabe zusätzlicher authentifizierter Daten (AAD) muss die Länge der tatsächlichen Nachricht in Byte über die Option plaintextLength an setAAD() übergeben werden. Viele Krypto-Bibliotheken fügen den Authentifizierungstag im Chiffretext ein, was bedeutet, dass sie Chiffretexte der Länge plaintextLength + authTagLength erzeugen. Node.js enthält den Authentifizierungstag nicht, daher ist die Chiffretextlänge immer plaintextLength. Dies ist nicht notwendig, wenn keine AAD verwendet wird.
  • Da CCM die gesamte Nachricht auf einmal verarbeitet, muss update() genau einmal aufgerufen werden.
  • Obwohl der Aufruf von update() zum Ver- bzw. Entschlüsseln der Nachricht ausreicht, müssen Anwendungen final() aufrufen, um den Authentifizierungstag zu berechnen oder zu verifizieren.
js
import { Buffer } from 'node:buffer'
const { createCipheriv, createDecipheriv, randomBytes } = await import('node:crypto')

const key = 'keykeykeykeykeykeykeykey'
const nonce = randomBytes(12)

const aad = Buffer.from('0123456789', 'hex')

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
})
const plaintext = 'Hello world'
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
})
const ciphertext = cipher.update(plaintext, 'utf8')
cipher.final()
const tag = cipher.getAuthTag()

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
})
decipher.setAuthTag(tag)
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
})
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8')

try {
  decipher.final()
} catch (err) {
  throw new Error('Authentication failed!', { cause: err })
}

console.log(receivedPlaintext)
js
const { Buffer } = require('node:buffer')
const { createCipheriv, createDecipheriv, randomBytes } = require('node:crypto')

const key = 'keykeykeykeykeykeykeykey'
const nonce = randomBytes(12)

const aad = Buffer.from('0123456789', 'hex')

const cipher = createCipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
})
const plaintext = 'Hello world'
cipher.setAAD(aad, {
  plaintextLength: Buffer.byteLength(plaintext),
})
const ciphertext = cipher.update(plaintext, 'utf8')
cipher.final()
const tag = cipher.getAuthTag()

// Now transmit { ciphertext, nonce, tag }.

const decipher = createDecipheriv('aes-192-ccm', key, nonce, {
  authTagLength: 16,
})
decipher.setAuthTag(tag)
decipher.setAAD(aad, {
  plaintextLength: ciphertext.length,
})
const receivedPlaintext = decipher.update(ciphertext, null, 'utf8')

try {
  decipher.final()
} catch (err) {
  throw new Error('Authentication failed!', { cause: err })
}

console.log(receivedPlaintext)

FIPS-Modus ​

Bei Verwendung von OpenSSL 3 unterstützt Node.js FIPS 140-2, wenn es mit einem geeigneten OpenSSL 3-Provider verwendet wird, wie z. B. dem FIPS-Provider von OpenSSL 3, der gemäß den Anweisungen in der OpenSSL FIPS-README-Datei installiert werden kann.

Für die FIPS-Unterstützung in Node.js benötigen Sie:

  • Einen korrekt installierten OpenSSL 3 FIPS-Provider.
  • Eine OpenSSL 3 FIPS-Modul-Konfigurationsdatei.
  • Eine OpenSSL 3-Konfigurationsdatei, die auf die FIPS-Modul-Konfigurationsdatei verweist.

Node.js muss mit einer OpenSSL-Konfigurationsdatei konfiguriert werden, die auf den FIPS-Provider verweist. Eine Beispielkonfigurationsdatei sieht wie folgt aus:

text
nodejs_conf = nodejs_init

.include /<absoluter Pfad>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect

[provider_sect]
default = default_sect
# Der Fips-Abschnittsname muss mit dem Abschnittsnamen in der {#the-fips-section-name-should-match-the-section-name-inside-the}
# eingebundenen fipsmodule.cnf übereinstimmen.
fips = fips_sect

[default_sect]
activate = 1

wobei fipsmodule.cnf die FIPS-Modul-Konfigurationsdatei ist, die im Installationsschritt des FIPS-Providers generiert wurde:

bash
openssl fipsinstall

Setzen Sie die Umgebungsvariable OPENSSL_CONF auf Ihren Konfigurationsdatei-Pfad und OPENSSL_MODULES auf den Speicherort der FIPS-Provider-Dynamic-Link-Library. Z.B.:

bash
export OPENSSL_CONF=/<Pfad zur Konfigurationsdatei>/nodejs.cnf
export OPENSSL_MODULES=/<Pfad zur openssl lib>/ossl-modules

Der FIPS-Modus kann dann in Node.js aktiviert werden, entweder durch:

  • Starten von Node.js mit den Befehlszeilenflags --enable-fips oder --force-fips.
  • Programmatisches Aufrufen von crypto.setFips(true).

Optional kann der FIPS-Modus in Node.js über die OpenSSL-Konfigurationsdatei aktiviert werden. Z.B.:

text
nodejs_conf = nodejs_init

.include /<absoluter Pfad>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
default = default_sect
# Der Fips-Abschnittsname muss mit dem Abschnittsnamen in der {#included-fipsmodulecnf}
# eingebundenen fipsmodule.cnf übereinstimmen.
fips = fips_sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

Krypto-Konstanten ​

Die folgenden Konstanten, die von crypto.constants exportiert werden, gelten für verschiedene Verwendungen der Module node:crypto, node:tls und node:https und sind im Allgemeinen OpenSSL-spezifisch.

OpenSSL-Optionen ​

Einzelheiten finden Sie in der Liste der SSL OP Flags.

KonstanteBeschreibung
SSL_OP_ALLWendet mehrere Bug-Workarounds innerhalb von OpenSSL an. Details finden Sie unter https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html .
SSL_OP_ALLOW_NO_DHE_KEXWeist OpenSSL an, einen nicht-[EC]DHE-basierten Key-Exchange-Modus für TLS v1.3 zuzulassen.
SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATIONErmöglicht unsichere Legacy-Renegotiation zwischen OpenSSL und nicht gepatchten Clients oder Servern. Details finden Sie unter https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html .
SSL_OP_CIPHER_SERVER_PREFERENCEVersucht, die Präferenzen des Servers anstelle der des Clients bei der Auswahl einer Chiffre zu verwenden. Das Verhalten hängt von der Protokollversion ab. Details finden Sie unter https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html .
SSL_OP_CISCO_ANYCONNECTWeist OpenSSL an, die Versionskennung von Cisco von DTLS_BAD_VER zu verwenden.
SSL_OP_COOKIE_EXCHANGEWeist OpenSSL an, den Cookie-Austausch zu aktivieren.
SSL_OP_CRYPTOPRO_TLSEXT_BUGWeist OpenSSL an, die Server-Hello-Erweiterung aus einer frühen Version des CryptoPro-Entwurfs hinzuzufügen.
SSL_OP_DONT_INSERT_EMPTY_FRAGMENTSWeist OpenSSL an, einen in OpenSSL 0.9.6d hinzugefügten Workaround für eine Sicherheitslücke in SSL 3.0/TLS 1.0 zu deaktivieren.
SSL_OP_LEGACY_SERVER_CONNECTErmöglicht die anfängliche Verbindung zu Servern, die RI nicht unterstützen.
SSL_OP_NO_COMPRESSIONWeist OpenSSL an, die Unterstützung für SSL/TLS-Komprimierung zu deaktivieren.
SSL_OP_NO_ENCRYPT_THEN_MACWeist OpenSSL an, Encrypt-then-MAC zu deaktivieren.
SSL_OP_NO_QUERY_MTU
SSL_OP_NO_RENEGOTIATIONWeist OpenSSL an, die Renegotiation zu deaktivieren.
SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATIONWeist OpenSSL an, bei der Renegotiation immer eine neue Sitzung zu starten.
SSL_OP_NO_SSLv2Weist OpenSSL an, SSL v2 zu deaktivieren.
SSL_OP_NO_SSLv3Weist OpenSSL an, SSL v3 zu deaktivieren.
SSL_OP_NO_TICKETWeist OpenSSL an, die Verwendung von RFC4507bis-Tickets zu deaktivieren.
SSL_OP_NO_TLSv1Weist OpenSSL an, TLS v1 zu deaktivieren.
SSL_OP_NO_TLSv1_1Weist OpenSSL an, TLS v1.1 zu deaktivieren.
SSL_OP_NO_TLSv1_2Weist OpenSSL an, TLS v1.2 zu deaktivieren.
SSL_OP_NO_TLSv1_3Weist OpenSSL an, TLS v1.3 zu deaktivieren.
SSL_OP_PRIORITIZE_CHACHAWeist den OpenSSL-Server an, ChaCha20-Poly1305 zu priorisieren, wenn der Client dies tut. Diese Option hat keine Auswirkung, wenn SSL_OP_CIPHER_SERVER_PREFERENCE nicht aktiviert ist.
SSL_OP_TLS_ROLLBACK_BUGWeist OpenSSL an, die Erkennung von Version Rollback-Angriffen zu deaktivieren.

OpenSSL Engine-Konstanten ​

KonstanteBeschreibung
ENGINE_METHOD_RSABeschränkt die Engine-Verwendung auf RSA
ENGINE_METHOD_DSABeschränkt die Engine-Verwendung auf DSA
ENGINE_METHOD_DHBeschränkt die Engine-Verwendung auf DH
ENGINE_METHOD_RANDBeschränkt die Engine-Verwendung auf RAND
ENGINE_METHOD_ECBeschränkt die Engine-Verwendung auf EC
ENGINE_METHOD_CIPHERSBeschränkt die Engine-Verwendung auf CIPHERS
ENGINE_METHOD_DIGESTSBeschränkt die Engine-Verwendung auf DIGESTS
ENGINE_METHOD_PKEY_METHSBeschränkt die Engine-Verwendung auf PKEY_METHS
ENGINE_METHOD_PKEY_ASN1_METHSBeschränkt die Engine-Verwendung auf PKEY_ASN1_METHS
ENGINE_METHOD_ALL
ENGINE_METHOD_NONE

Weitere OpenSSL-Konstanten ​

KonstanteBeschreibung
DH_CHECK_P_NOT_SAFE_PRIME
DH_CHECK_P_NOT_PRIME
DH_UNABLE_TO_CHECK_GENERATOR
DH_NOT_SUITABLE_GENERATOR
RSA_PKCS1_PADDING
RSA_SSLV23_PADDING
RSA_NO_PADDING
RSA_PKCS1_OAEP_PADDING
RSA_X931_PADDING
RSA_PKCS1_PSS_PADDING
RSA_PSS_SALTLEN_DIGESTSetzt die Salt-Länge für RSA_PKCS1_PSS_PADDING auf die Digest-Größe beim Signieren oder Verifizieren.
RSA_PSS_SALTLEN_MAX_SIGNSetzt die Salt-Länge für RSA_PKCS1_PSS_PADDING auf den maximal zulässigen Wert beim Signieren von Daten.
RSA_PSS_SALTLEN_AUTOBewirkt, dass die Salt-Länge für RSA_PKCS1_PSS_PADDING automatisch bestimmt wird, wenn eine Signatur verifiziert wird.
POINT_CONVERSION_COMPRESSED
POINT_CONVERSION_UNCOMPRESSED
POINT_CONVERSION_HYBRID

Node.js Krypto-Konstanten ​

KonstanteBeschreibung
defaultCoreCipherListGibt die integrierte Standard-Cipherliste an, die von Node.js verwendet wird.
defaultCipherListGibt die aktive Standard-Cipherliste an, die vom aktuellen Node.js-Prozess verwendet wird.