iDoc.dev

Italiano

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

Italiano

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

Tema

Crypto ​

[Stabile: 2 - Stabile]

Stabile: 2 Stabilità: 2 - Stabile

Codice sorgente: lib/crypto.js

Il modulo node:crypto fornisce funzionalità crittografiche che includono una serie di wrapper per le funzioni hash, HMAC, cipher, decipher, sign e verify di 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)
// Stampa:
//   c0fa1bc00531bd78ef38c628449c5102aeabd49b5dc3a2a516ea6ea959d6658e
js
const { createHmac } = require('node:crypto')

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

Determinare se il supporto crypto non è disponibile ​

È possibile che Node.js venga compilato senza includere il supporto per il modulo node:crypto. In tali casi, tentare di import da crypto o chiamare require('node:crypto') risulterà in un errore.

Quando si utilizza CommonJS, l'errore generato può essere intercettato utilizzando try/catch:

js
let crypto
try {
  crypto = require('node:crypto')
} catch (err) {
  console.error('il supporto crypto è disabilitato!')
}

Quando si utilizza la parola chiave lessicale ESM import, l'errore può essere intercettato solo se viene registrato un gestore per process.on('uncaughtException') prima di qualsiasi tentativo di caricare il modulo (utilizzando, ad esempio, un modulo di precaricamento).

Quando si utilizza ESM, se esiste la possibilità che il codice possa essere eseguito su una build di Node.js in cui il supporto crypto non è abilitato, si consideri l'utilizzo della funzione import() invece della parola chiave lessicale import:

js
let crypto
try {
  crypto = await import('node:crypto')
} catch (err) {
  console.error('il supporto crypto è disabilitato!')
}

Classe: Certificate ​

Aggiunto in: v0.11.8

SPKAC è un meccanismo di richiesta di firma del certificato originariamente implementato da Netscape e specificato formalmente come parte dell'elemento keygen di HTML5.

\<keygen\> è deprecato a partire da HTML 5.2 e i nuovi progetti non dovrebbero più utilizzare questo elemento.

Il modulo node:crypto fornisce la classe Certificate per lavorare con i dati SPKAC. L'uso più comune è la gestione dell'output generato dall'elemento HTML5 \<keygen\>. Node.js utilizza internamente l'implementazione SPKAC di OpenSSL.

Metodo statico: Certificate.exportChallenge(spkac[, encoding]) ​

[Cronologia]

VersioneModifiche
v15.0.0L'argomento spkac può essere un ArrayBuffer. È stata limitata la dimensione dell'argomento spkac a un massimo di 2**31 - 1 byte.
v9.0.0Aggiunto in: v9.0.0
js
const { Certificate } = await import('node:crypto')
const spkac = getSpkacSomehow()
const challenge = Certificate.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// Stampa: il challenge come stringa UTF8
js
const { Certificate } = require('node:crypto')
const spkac = getSpkacSomehow()
const challenge = Certificate.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// Stampa: il challenge come stringa UTF8

Metodo statico: Certificate.exportPublicKey(spkac[, encoding]) ​

[Cronologia]

VersioneModifiche
v15.0.0L'argomento spkac può essere un ArrayBuffer. Limitate le dimensioni dell'argomento spkac a un massimo di 2**31 - 1 byte.
v9.0.0Aggiunto in: v9.0.0
js
const { Certificate } = await import('node:crypto')
const spkac = getSpkacSomehow()
const publicKey = Certificate.exportPublicKey(spkac)
console.log(publicKey)
// Stampa: la chiave pubblica come <Buffer ...>
js
const { Certificate } = require('node:crypto')
const spkac = getSpkacSomehow()
const publicKey = Certificate.exportPublicKey(spkac)
console.log(publicKey)
// Stampa: la chiave pubblica come <Buffer ...>

Metodo statico: Certificate.verifySpkac(spkac[, encoding]) ​

[Cronologia]

VersioneModifiche
v15.0.0L'argomento spkac può essere un ArrayBuffer. Aggiunta la codifica. Limitate le dimensioni dell'argomento spkac a un massimo di 2**31 - 1 byte.
v9.0.0Aggiunto 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)))
// Stampa: true o false
js
const { Buffer } = require('node:buffer')
const { Certificate } = require('node:crypto')

const spkac = getSpkacSomehow()
console.log(Certificate.verifySpkac(Buffer.from(spkac)))
// Stampa: true o false

API Legacy ​

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato

Essendo un'interfaccia legacy, è possibile creare nuove istanze della classe crypto.Certificate come illustrato negli esempi seguenti.

new crypto.Certificate() ​

Le istanze della classe Certificate possono essere create usando la parola chiave new o chiamando crypto.Certificate() come funzione:

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]) ​

Aggiunto 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'))
// Stampa: la challenge come stringa UTF8
js
const { Certificate } = require('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const challenge = cert.exportChallenge(spkac)
console.log(challenge.toString('utf8'))
// Stampa: la challenge come stringa UTF8

certificate.exportPublicKey(spkac[, encoding]) ​

Aggiunto 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)
// Stampa: la chiave pubblica come <Buffer ...>
js
const { Certificate } = require('node:crypto')
const cert = Certificate()
const spkac = getSpkacSomehow()
const publicKey = cert.exportPublicKey(spkac)
console.log(publicKey)
// Stampa: la chiave pubblica come <Buffer ...>

certificate.verifySpkac(spkac[, encoding]) ​

Aggiunto 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)))
// Stampa: true o 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)))
// Stampa: true o false

Classe: Cipher ​

Aggiunto in: v0.1.94

Le istanze della classe Cipher vengono utilizzate per crittografare i dati. La classe può essere utilizzata in uno dei due modi seguenti:

  • Come uno stream che è sia leggibile che scrivibile, dove i dati non crittografati in chiaro vengono scritti per produrre dati crittografati sul lato leggibile, oppure
  • Utilizzando i metodi cipher.update() e cipher.final() per produrre i dati crittografati.

Il metodo crypto.createCipheriv() viene utilizzato per creare istanze Cipher. Gli oggetti Cipher non devono essere creati direttamente utilizzando la parola chiave new.

Esempio: Utilizzo di oggetti Cipher come stream:

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

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

// Per prima cosa, genereremo la chiave. La lunghezza della chiave dipende dall'algoritmo.
// In questo caso per aes192, è di 24 byte (192 bit).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Quindi, genereremo un vettore di inizializzazione casuale
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    // Una volta che abbiamo la chiave e iv, possiamo creare e utilizzare il cifrario...
    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'

// Per prima cosa, genereremo la chiave. La lunghezza della chiave dipende dall'algoritmo.
// In questo caso per aes192, è di 24 byte (192 bit).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Quindi, genereremo un vettore di inizializzazione casuale
  randomFill(new Uint8Array(16), (err, iv) => {
    if (err) throw err

    // Una volta che abbiamo la chiave e iv, possiamo creare e utilizzare il cifrario...
    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()
  })
})

Esempio: Utilizzo di Cipher e stream incanalati:

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'

// Per prima cosa, genereremo la chiave. La lunghezza della chiave dipende dall'algoritmo.
// In questo caso per aes192, è di 24 byte (192 bit).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Quindi, genereremo un vettore di inizializzazione casuale
  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'

// Per prima cosa, genereremo la chiave. La lunghezza della chiave dipende dall'algoritmo.
// In questo caso per aes192, è di 24 byte (192 bit).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Quindi, genereremo un vettore di inizializzazione casuale
  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
    })
  })
})

Esempio: Utilizzo dei metodi cipher.update() e cipher.final():

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

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

// Per prima cosa, genereremo la chiave. La lunghezza della chiave dipende dall'algoritmo.
// In questo caso per aes192, è di 24 byte (192 bit).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Quindi, genereremo un vettore di inizializzazione casuale
  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'

// Per prima cosa, genereremo la chiave. La lunghezza della chiave dipende dall'algoritmo.
// In questo caso per aes192, è di 24 byte (192 bit).
scrypt(password, 'salt', 24, (err, key) => {
  if (err) throw err
  // Quindi, genereremo un vettore di inizializzazione casuale
  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]) ​

Aggiunto in: v0.1.94

  • outputEncoding <string> La codifica del valore restituito.
  • Restituisce: <Buffer> | <string> Eventuali contenuti crittografati rimanenti. Se è specificato outputEncoding, viene restituita una stringa. Se non viene fornito un outputEncoding, viene restituito un Buffer.

Una volta che il metodo cipher.final() è stato chiamato, l'oggetto Cipher non può più essere utilizzato per crittografare i dati. I tentativi di chiamare cipher.final() più di una volta comporteranno la generazione di un errore.

cipher.getAuthTag() ​

Aggiunto in: v1.0.0

  • Restituisce: <Buffer> Quando si utilizza una modalità di crittografia autenticata (attualmente sono supportati GCM, CCM, OCB e chacha20-poly1305), il metodo cipher.getAuthTag() restituisce un Buffer contenente il tag di autenticazione che è stato calcolato dai dati forniti.

Il metodo cipher.getAuthTag() deve essere chiamato solo dopo che la crittografia è stata completata utilizzando il metodo cipher.final().

Se l'opzione authTagLength è stata impostata durante la creazione dell'istanza cipher, questa funzione restituirà esattamente authTagLength byte.

cipher.setAAD(buffer[, options]) ​

Aggiunto in: v1.0.0

Quando si utilizza una modalità di crittografia autenticata (attualmente sono supportati GCM, CCM, OCB e chacha20-poly1305), il metodo cipher.setAAD() imposta il valore utilizzato per il parametro di input dati autenticati aggiuntivi (AAD).

L'opzione plaintextLength è facoltativa per GCM e OCB. Quando si utilizza CCM, l'opzione plaintextLength deve essere specificata e il suo valore deve corrispondere alla lunghezza del testo non crittografato in byte. Vedere modalità CCM.

Il metodo cipher.setAAD() deve essere chiamato prima di cipher.update().

cipher.setAutoPadding([autoPadding]) ​

Aggiunto in: v0.7.1

  • autoPadding <boolean> Predefinito: true
  • Restituisce: <Cipher> La stessa istanza Cipher per l'incatenamento dei metodi.

Quando si utilizzano algoritmi di crittografia a blocchi, la classe Cipher aggiungerà automaticamente il padding ai dati di input alla dimensione di blocco appropriata. Per disabilitare il padding predefinito, chiamare cipher.setAutoPadding(false).

Quando autoPadding è false, la lunghezza dell'intero input deve essere un multiplo della dimensione del blocco del cifrario oppure cipher.final() genererà un errore. La disabilitazione del padding automatico è utile per il padding non standard, ad esempio utilizzando 0x0 anziché il padding PKCS.

Il metodo cipher.setAutoPadding() deve essere chiamato prima di cipher.final().

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

[Cronologia]

VersioneModifiche
v6.0.0L'inputEncoding predefinito è cambiato da binary a utf8.
v0.1.94Aggiunto in: v0.1.94

Aggiorna il cifrario con data. Se viene fornito l'argomento inputEncoding, l'argomento data è una stringa che utilizza la codifica specificata. Se l'argomento inputEncoding non viene fornito, data deve essere un Buffer, TypedArray o DataView. Se data è un Buffer, TypedArray o DataView, allora inputEncoding viene ignorato.

outputEncoding specifica il formato di output dei dati cifrati. Se outputEncoding viene specificato, viene restituita una stringa che utilizza la codifica specificata. Se non viene fornito outputEncoding, viene restituito un Buffer.

Il metodo cipher.update() può essere chiamato più volte con nuovi dati fino a quando non viene chiamato cipher.final(). La chiamata a cipher.update() dopo cipher.final() comporterà la generazione di un errore.

Classe: Decipher ​

Aggiunto in: v0.1.94

Le istanze della classe Decipher vengono utilizzate per decifrare i dati. La classe può essere utilizzata in uno dei due modi seguenti:

  • Come uno stream sia leggibile che scrivibile, dove i dati crittografati semplici vengono scritti per produrre dati non crittografati sul lato leggibile, oppure
  • Utilizzando i metodi decipher.update() e decipher.final() per produrre i dati non crittografati.

Il metodo crypto.createDecipheriv() viene utilizzato per creare istanze Decipher. Gli oggetti Decipher non devono essere creati direttamente utilizzando la parola chiave new.

Esempio: Utilizzo di oggetti Decipher come stream:

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'
// La lunghezza della chiave dipende dall'algoritmo. In questo caso per aes192, è
// 24 byte (192 bit).
// Utilizzare l'async `crypto.scrypt()` invece.
const key = scryptSync(password, 'salt', 24)
// L'IV viene solitamente passato insieme al testo cifrato.
const iv = Buffer.alloc(16, 0) // Vettore di inizializzazione.

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)
  // Stampa: some clear text data
})

// Crittografato con lo stesso algoritmo, chiave e 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'
// La lunghezza della chiave dipende dall'algoritmo. In questo caso per aes192, è
// 24 byte (192 bit).
// Utilizzare l'async `crypto.scrypt()` invece.
const key = scryptSync(password, 'salt', 24)
// L'IV viene solitamente passato insieme al testo cifrato.
const iv = Buffer.alloc(16, 0) // Vettore di inizializzazione.

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)
  // Stampa: some clear text data
})

// Crittografato con lo stesso algoritmo, chiave e iv.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
decipher.write(encrypted, 'hex')
decipher.end()

Esempio: Utilizzo di Decipher e stream piped:

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'
// Utilizzare l'async `crypto.scrypt()` invece.
const key = scryptSync(password, 'salt', 24)
// L'IV viene solitamente passato insieme al testo cifrato.
const iv = Buffer.alloc(16, 0) // Vettore di inizializzazione.

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'
// Utilizzare l'async `crypto.scrypt()` invece.
const key = scryptSync(password, 'salt', 24)
// L'IV viene solitamente passato insieme al testo cifrato.
const iv = Buffer.alloc(16, 0) // Vettore di inizializzazione.

const decipher = createDecipheriv(algorithm, key, iv)

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

input.pipe(decipher).pipe(output)

Esempio: Utilizzo dei metodi decipher.update() e 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'
// Utilizzare l'async `crypto.scrypt()` invece.
const key = scryptSync(password, 'salt', 24)
// L'IV viene solitamente passato insieme al testo cifrato.
const iv = Buffer.alloc(16, 0) // Vettore di inizializzazione.

const decipher = createDecipheriv(algorithm, key, iv)

// Crittografato utilizzando lo stesso algoritmo, chiave e iv.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
let decrypted = decipher.update(encrypted, 'hex', 'utf8')
decrypted += decipher.final('utf8')
console.log(decrypted)
// Stampa: 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'
// Utilizzare l'async `crypto.scrypt()` invece.
const key = scryptSync(password, 'salt', 24)
// L'IV viene solitamente passato insieme al testo cifrato.
const iv = Buffer.alloc(16, 0) // Vettore di inizializzazione.

const decipher = createDecipheriv(algorithm, key, iv)

// Crittografato utilizzando lo stesso algoritmo, chiave e iv.
const encrypted = 'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa'
let decrypted = decipher.update(encrypted, 'hex', 'utf8')
decrypted += decipher.final('utf8')
console.log(decrypted)
// Stampa: some clear text data

decipher.final([outputEncoding]) ​

Aggiunto in: v0.1.94

  • outputEncoding <stringa> La codifica del valore di ritorno.
  • Restituisce: <Buffer> | <stringa> Qualsiasi contenuto decifrato rimanente. Se viene specificato outputEncoding, viene restituita una stringa. Se non viene fornito outputEncoding, viene restituito un Buffer.

Una volta chiamato il metodo decipher.final(), l'oggetto Decipher non può più essere utilizzato per decrittografare i dati. I tentativi di chiamare decipher.final() più di una volta comporteranno la generazione di un errore.

decipher.setAAD(buffer[, options]) ​

[Cronologia]

VersioneModifiche
v15.0.0L'argomento buffer può essere una stringa o ArrayBuffer e non può superare i 2 ** 31 - 1 byte.
v7.2.0Questo metodo ora restituisce un riferimento a decipher.
v1.0.0Aggiunto in: v1.0.0

Quando si utilizza una modalità di crittografia autenticata (attualmente sono supportate GCM, CCM, OCB e chacha20-poly1305), il metodo decipher.setAAD() imposta il valore utilizzato per il parametro di input dati autenticati aggiuntivi (AAD).

L'argomento options è facoltativo per GCM. Quando si utilizza CCM, è necessario specificare l'opzione plaintextLength e il suo valore deve corrispondere alla lunghezza del testo cifrato in byte. Vedere modalità CCM.

Il metodo decipher.setAAD() deve essere chiamato prima di decipher.update().

Quando si passa una stringa come buffer, si prega di considerare le avvertenze quando si utilizzano stringhe come input per le API crittografiche.

decipher.setAuthTag(buffer[, encoding]) ​

[Cronologia]

VersioneModifiche
v22.0.0, v20.13.0L'utilizzo di lunghezze del tag GCM diverse da 128 bit senza specificare l'opzione authTagLength durante la creazione di decipher è deprecato.
v15.0.0L'argomento buffer può essere una stringa o un ArrayBuffer ed è limitato a non più di 2 ** 31 - 1 byte.
v11.0.0Questo metodo ora genera un'eccezione se la lunghezza del tag GCM non è valida.
v7.2.0Questo metodo ora restituisce un riferimento a decipher.
v1.0.0Aggiunto in: v1.0.0

Quando si utilizza una modalità di crittografia autenticata (attualmente sono supportati GCM, CCM, OCB e chacha20-poly1305), il metodo decipher.setAuthTag() viene utilizzato per passare il tag di autenticazione ricevuto. Se non viene fornito alcun tag, o se il testo cifrato è stato manomesso, decipher.final() genererà un'eccezione, indicando che il testo cifrato deve essere scartato a causa di un'autenticazione non riuscita. Se la lunghezza del tag non è valida in base a NIST SP 800-38D o non corrisponde al valore dell'opzione authTagLength, decipher.setAuthTag() genererà un errore.

Il metodo decipher.setAuthTag() deve essere chiamato prima di decipher.update() per la modalità CCM o prima di decipher.final() per le modalità GCM e OCB e chacha20-poly1305. decipher.setAuthTag() può essere chiamato una sola volta.

Quando si passa una stringa come tag di autenticazione, si prega di considerare avvertenze quando si utilizzano stringhe come input per le API crittografiche.

decipher.setAutoPadding([autoPadding]) ​

Aggiunto in: v0.7.1

  • autoPadding <boolean> Predefinito: true
  • Restituisce: <Decipher> Lo stesso Decipher per l'incatenamento dei metodi.

Quando i dati sono stati crittografati senza padding a blocchi standard, chiamando decipher.setAutoPadding(false) si disabilita il padding automatico per evitare che decipher.final() controlli e rimuova il padding.

La disattivazione del padding automatico funzionerà solo se la lunghezza dei dati di input è un multiplo della dimensione del blocco del cifrario.

Il metodo decipher.setAutoPadding() deve essere chiamato prima di decipher.final().

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

[Cronologia]

VersioneCambiamenti
v6.0.0L'inputEncoding predefinito è cambiato da binary a utf8.
v0.1.94Aggiunto in: v0.1.94

Aggiorna il decifratore con data. Se viene fornito l'argomento inputEncoding, l'argomento data è una stringa che utilizza la codifica specificata. Se l'argomento inputEncoding non viene fornito, data deve essere un Buffer. Se data è un Buffer allora inputEncoding viene ignorato.

L'outputEncoding specifica il formato di output dei dati cifrati. Se viene specificato l'outputEncoding, viene restituita una stringa che utilizza la codifica specificata. Se non viene fornito alcun outputEncoding, viene restituito un Buffer.

Il metodo decipher.update() può essere chiamato più volte con nuovi dati fino a quando non viene chiamato decipher.final(). La chiamata a decipher.update() dopo decipher.final() comporterà la generazione di un errore.

Anche se il cifrario sottostante implementa l'autenticazione, l'autenticità e l'integrità del testo in chiaro restituito da questa funzione potrebbero essere incerte in questo momento. Per gli algoritmi di crittografia autenticata, l'autenticità viene generalmente stabilita solo quando l'applicazione chiama decipher.final().

Classe: DiffieHellman ​

Aggiunto in: v0.5.0

La classe DiffieHellman è un'utilità per la creazione di scambi di chiavi Diffie-Hellman.

Le istanze della classe DiffieHellman possono essere create usando la funzione crypto.createDiffieHellman().

js
import assert from 'node:assert'

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

// Genera le chiavi di Alice...
const alice = createDiffieHellman(2048)
const aliceKey = alice.generateKeys()

// Genera le chiavi di Bob...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator())
const bobKey = bob.generateKeys()

// Scambia e genera il segreto...
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')

// Genera le chiavi di Alice...
const alice = createDiffieHellman(2048)
const aliceKey = alice.generateKeys()

// Genera le chiavi di Bob...
const bob = createDiffieHellman(alice.getPrime(), alice.getGenerator())
const bobKey = bob.generateKeys()

// Scambia e genera il segreto...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

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

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

Aggiunto in: v0.5.0

Calcola il segreto condiviso usando otherPublicKey come chiave pubblica dell'altra parte e restituisce il segreto condiviso calcolato. La chiave fornita viene interpretata usando la inputEncoding specificata e il segreto viene codificato usando la outputEncoding specificata. Se inputEncoding non viene fornita, si prevede che otherPublicKey sia un Buffer, TypedArray, o DataView.

Se viene fornita outputEncoding viene restituita una stringa; altrimenti, viene restituito un Buffer.

diffieHellman.generateKeys([encoding]) ​

Aggiunto in: v0.5.0

Genera i valori della chiave privata e pubblica di Diffie-Hellman a meno che non siano già stati generati o calcolati, e restituisce la chiave pubblica nella encoding specificata. Questa chiave deve essere trasferita all'altra parte. Se viene fornita la encoding, viene restituita una stringa; altrimenti viene restituito un Buffer.

Questa funzione è un wrapper sottile attorno a DH_generate_key(). In particolare, una volta che una chiave privata è stata generata o impostata, la chiamata a questa funzione aggiorna solo la chiave pubblica ma non genera una nuova chiave privata.

diffieHellman.getGenerator([encoding]) ​

Aggiunto in: v0.5.0

Restituisce il generatore Diffie-Hellman nella encoding specificata. Se viene fornita la encoding, viene restituita una stringa; altrimenti viene restituito un Buffer.

diffieHellman.getPrime([encoding]) ​

Aggiunto in: v0.5.0

Restituisce il numero primo di Diffie-Hellman nella encoding specificata. Se viene fornita la encoding, viene restituita una stringa; altrimenti viene restituito un Buffer.

diffieHellman.getPrivateKey([encoding]) ​

Aggiunto in: v0.5.0

Restituisce la chiave privata di Diffie-Hellman nella encoding specificata. Se viene fornita encoding, viene restituita una stringa; altrimenti viene restituito un Buffer.

diffieHellman.getPublicKey([encoding]) ​

Aggiunto in: v0.5.0

Restituisce la chiave pubblica di Diffie-Hellman nella encoding specificata. Se viene fornita encoding, viene restituita una stringa; altrimenti viene restituito un Buffer.

diffieHellman.setPrivateKey(privateKey[, encoding]) ​

Aggiunto in: v0.5.0

Imposta la chiave privata di Diffie-Hellman. Se viene fornito l'argomento encoding, si prevede che privateKey sia una stringa. Se non viene fornito alcun encoding, si prevede che privateKey sia un Buffer, TypedArray o DataView.

Questa funzione non calcola automaticamente la chiave pubblica associata. È possibile utilizzare diffieHellman.setPublicKey() o diffieHellman.generateKeys() per fornire manualmente la chiave pubblica o per derivarla automaticamente.

diffieHellman.setPublicKey(publicKey[, encoding]) ​

Aggiunto in: v0.5.0

Imposta la chiave pubblica Diffie-Hellman. Se viene fornito l'argomento encoding, si prevede che publicKey sia una stringa. Se non viene fornita alcuna encoding, si prevede che publicKey sia un Buffer, TypedArray o DataView.

diffieHellman.verifyError ​

Aggiunto in: v0.11.12

Un campo di bit contenente eventuali avvisi e/o errori risultanti da un controllo eseguito durante l'inizializzazione dell'oggetto DiffieHellman.

I seguenti valori sono validi per questa proprietà (come definiti nel modulo node:constants):

  • DH_CHECK_P_NOT_SAFE_PRIME
  • DH_CHECK_P_NOT_PRIME
  • DH_UNABLE_TO_CHECK_GENERATOR
  • DH_NOT_SUITABLE_GENERATOR

Classe: DiffieHellmanGroup ​

Aggiunto in: v0.7.5

La classe DiffieHellmanGroup accetta un gruppo modp noto come argomento. Funziona allo stesso modo di DiffieHellman, tranne per il fatto che non consente di modificare le sue chiavi dopo la creazione. In altre parole, non implementa i metodi setPublicKey() o setPrivateKey().

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

Sono supportati i seguenti gruppi:

I seguenti gruppi sono ancora supportati, ma sono deprecati (vedi Avvertenze):

Questi gruppi deprecati potrebbero essere rimossi nelle future versioni di Node.js.

Classe: ECDH ​

Aggiunto in: v0.11.14

La classe ECDH è un'utilità per la creazione di scambi di chiavi Elliptic Curve Diffie-Hellman (ECDH).

Le istanze della classe ECDH possono essere create usando la funzione crypto.createECDH().

js
import assert from 'node:assert'

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

// Genera le chiavi di Alice...
const alice = createECDH('secp521r1')
const aliceKey = alice.generateKeys()

// Genera le chiavi di Bob...
const bob = createECDH('secp521r1')
const bobKey = bob.generateKeys()

// Scambia e genera il segreto...
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')

// Genera le chiavi di Alice...
const alice = createECDH('secp521r1')
const aliceKey = alice.generateKeys()

// Genera le chiavi di Bob...
const bob = createECDH('secp521r1')
const bobKey = bob.generateKeys()

// Scambia e genera il segreto...
const aliceSecret = alice.computeSecret(bobKey)
const bobSecret = bob.computeSecret(aliceKey)

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

Metodo statico: ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]]) ​

Aggiunto in: v10.0.0

Converte la chiave pubblica EC Diffie-Hellman specificata da key e curve nel formato specificato da format. L'argomento format specifica la codifica del punto e può essere 'compressed', 'uncompressed' o 'hybrid'. La chiave fornita viene interpretata usando la inputEncoding specificata e la chiave restituita viene codificata usando la outputEncoding specificata.

Usa crypto.getCurves() per ottenere una lista di nomi di curve disponibili. Nelle versioni recenti di OpenSSL, openssl ecparam -list_curves mostrerà anche il nome e la descrizione di ogni curva ellittica disponibile.

Se format non è specificato, il punto verrà restituito in formato 'uncompressed'.

Se la inputEncoding non è fornita, si presume che key sia un Buffer, TypedArray o DataView.

Esempio (decompressione di una chiave):

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')

// La chiave convertita e la chiave pubblica non compressa dovrebbero essere uguali
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')

// La chiave convertita e la chiave pubblica non compressa dovrebbero essere uguali
console.log(uncompressedKey === ecdh.getPublicKey('hex'))

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

[Cronologia]

VersioneCambiamenti
v10.0.0Formato dell'errore modificato per supportare meglio l'errore di chiave pubblica non valida.
v6.0.0L'inputEncoding predefinito è cambiato da binary a utf8.
v0.11.14Aggiunto in: v0.11.14

Calcola il segreto condiviso usando otherPublicKey come chiave pubblica dell'altra parte e restituisce il segreto condiviso calcolato. La chiave fornita viene interpretata utilizzando l'inputEncoding specificato e il segreto restituito viene codificato utilizzando l'outputEncoding specificato. Se inputEncoding non viene fornito, si prevede che otherPublicKey sia un Buffer, TypedArray o DataView.

Se viene fornito outputEncoding, verrà restituita una stringa; altrimenti viene restituito un Buffer.

ecdh.computeSecret lancerà un errore ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY quando otherPublicKey si trova al di fuori della curva ellittica. Poiché otherPublicKey viene solitamente fornito da un utente remoto su una rete non sicura, assicurarsi di gestire questa eccezione di conseguenza.

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

Aggiunto in: v0.11.14

Genera valori di chiave privata e pubblica EC Diffie-Hellman e restituisce la chiave pubblica nel format e nella encoding specificate. Questa chiave deve essere trasferita all'altra parte.

L'argomento format specifica la codifica del punto e può essere 'compressed' o 'uncompressed'. Se format non è specificato, il punto verrà restituito nel formato 'uncompressed'.

Se viene fornita una encoding, viene restituita una stringa; altrimenti viene restituito un Buffer.

ecdh.getPrivateKey([encoding]) ​

Aggiunto in: v0.11.14

Se è specificata una encoding, viene restituita una stringa; altrimenti viene restituito un Buffer.

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

Aggiunto in: v0.11.14

L'argomento format specifica la codifica del punto e può essere 'compressed' o 'uncompressed'. Se format non è specificato, il punto verrà restituito nel formato 'uncompressed'.

Se è specificata una encoding, viene restituita una stringa; altrimenti viene restituito un Buffer.

ecdh.setPrivateKey(privateKey[, encoding]) ​

Aggiunto in: v0.11.14

Imposta la chiave privata EC Diffie-Hellman. Se viene fornito encoding, si prevede che privateKey sia una stringa; altrimenti si prevede che privateKey sia un Buffer, TypedArray o DataView.

Se privateKey non è valido per la curva specificata quando è stato creato l'oggetto ECDH, viene generato un errore. Al momento dell'impostazione della chiave privata, viene generato e impostato nell'oggetto ECDH anche il punto pubblico (chiave) associato.

ecdh.setPublicKey(publicKey[, encoding]) ​

Aggiunto in: v0.11.14

Deprecato dal: v5.2.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato

Imposta la chiave pubblica EC Diffie-Hellman. Se viene fornito encoding, si prevede che publicKey sia una stringa; altrimenti si prevede un Buffer, TypedArray o DataView.

Normalmente non c'è motivo di chiamare questo metodo perché ECDH richiede solo una chiave privata e la chiave pubblica dell'altra parte per calcolare il segreto condiviso. In genere verrà chiamato ecdh.generateKeys() o ecdh.setPrivateKey(). Il metodo ecdh.setPrivateKey() tenta di generare il punto/chiave pubblica associata alla chiave privata che viene impostata.

Esempio (ottenimento di un segreto condiviso):

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

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

// Questo è un modo scorciatoia per specificare una delle precedenti chiavi private di Alice.
// Sarebbe imprudente utilizzare una chiave privata così prevedibile in un'applicazione reale.
alice.setPrivateKey(createHash('sha256').update('alice', 'utf8').digest())

// Bob usa una coppia di chiavi pseudocasuali crittograficamente robuste appena generate
bob.generateKeys()

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

// aliceSecret e bobSecret dovrebbero essere lo stesso valore segreto condiviso
console.log(aliceSecret === bobSecret)
js
const { createECDH, createHash } = require('node:crypto')

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

// Questo è un modo scorciatoia per specificare una delle precedenti chiavi private di Alice.
// Sarebbe imprudente utilizzare una chiave privata così prevedibile in un'applicazione reale.
alice.setPrivateKey(createHash('sha256').update('alice', 'utf8').digest())

// Bob usa una coppia di chiavi pseudocasuali crittograficamente robuste appena generate
bob.generateKeys()

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

// aliceSecret e bobSecret dovrebbero essere lo stesso valore segreto condiviso
console.log(aliceSecret === bobSecret)

Classe: Hash ​

Aggiunto in: v0.1.92

La classe Hash è un'utilità per la creazione di hash digest di dati. Può essere utilizzata in due modi:

  • Come uno stream che è sia leggibile che scrivibile, dove i dati vengono scritti per produrre un hash digest calcolato sul lato leggibile, oppure
  • Utilizzando i metodi hash.update() e hash.digest() per produrre l'hash calcolato.

Il metodo crypto.createHash() viene utilizzato per creare istanze Hash. Gli oggetti Hash non devono essere creati direttamente utilizzando la parola chiave new.

Esempio: Utilizzo di oggetti Hash come stream:

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

const hash = createHash('sha256')

hash.on('readable', () => {
  // Solo un elemento verrà prodotto dallo
  // stream hash.
  const data = hash.read()
  if (data) {
    console.log(data.toString('hex'))
    // Stampa:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
})

hash.write('alcuni dati da hashare')
hash.end()
js
const { createHash } = require('node:crypto')

const hash = createHash('sha256')

hash.on('readable', () => {
  // Solo un elemento verrà prodotto dallo
  // stream hash.
  const data = hash.read()
  if (data) {
    console.log(data.toString('hex'))
    // Stampa:
    //   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
  }
})

hash.write('alcuni dati da hashare')
hash.end()

Esempio: Utilizzo di Hash e stream piped:

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)

Esempio: Utilizzo dei metodi hash.update() e hash.digest():

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

const hash = createHash('sha256')

hash.update('alcuni dati da hashare')
console.log(hash.digest('hex'))
// Stampa:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
js
const { createHash } = require('node:crypto')

const hash = createHash('sha256')

hash.update('alcuni dati da hashare')
console.log(hash.digest('hex'))
// Stampa:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50

hash.copy([options]) ​

Aggiunto in: v13.1.0

Crea un nuovo oggetto Hash che contiene una copia profonda dello stato interno dell'oggetto Hash corrente.

L'argomento opzionale options controlla il comportamento dello stream. Per le funzioni hash XOF come 'shake256', l'opzione outputLength può essere utilizzata per specificare la lunghezza di output desiderata in byte.

Viene generato un errore quando si tenta di copiare l'oggetto Hash dopo che è stato chiamato il suo metodo hash.digest().

js
// Calcola un hash rolling.
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'))

// Ecc.
js
// Calcola un hash rolling.
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'))

// Ecc.

hash.digest([encoding]) ​

Aggiunto in: v0.1.92

Calcola il digest di tutti i dati passati per essere sottoposti a hash (utilizzando il metodo hash.update()). Se viene fornita encoding, verrà restituita una stringa; altrimenti, viene restituito un Buffer.

L'oggetto Hash non può essere riutilizzato dopo che è stato chiamato il metodo hash.digest(). Chiamate multiple causeranno la generazione di un errore.

hash.update(data[, inputEncoding]) ​

[Cronologia]

VersioneModifiche
v6.0.0L' inputEncoding predefinito è cambiato da binary a utf8.
v0.1.92Aggiunto in: v0.1.92

Aggiorna il contenuto dell'hash con i data forniti, la cui codifica è specificata in inputEncoding. Se encoding non viene fornito, e data è una stringa, viene forzata la codifica 'utf8'. Se data è un Buffer, TypedArray, o DataView, allora inputEncoding viene ignorato.

Questo può essere chiamato più volte con nuovi dati mentre vengono trasmessi in streaming.

Classe: Hmac ​

Aggiunto in: v0.1.94

La classe Hmac è un'utilità per la creazione di digest crittografici HMAC. Può essere utilizzata in uno dei due modi seguenti:

  • Come uno stream che è sia leggibile che scrivibile, dove i dati vengono scritti per produrre un digest HMAC calcolato sul lato leggibile, oppure
  • Utilizzando i metodi hmac.update() e hmac.digest() per produrre il digest HMAC calcolato.

Il metodo crypto.createHmac() viene utilizzato per creare istanze Hmac. Gli oggetti Hmac non devono essere creati direttamente utilizzando la parola chiave new.

Esempio: Utilizzo di oggetti Hmac come stream:

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

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

hmac.on('readable', () => {
  // Verrà prodotto un solo elemento dallo
  // stream di hash.
  const data = hmac.read()
  if (data) {
    console.log(data.toString('hex'))
    // Stampa:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
})

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

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

hmac.on('readable', () => {
  // Verrà prodotto un solo elemento dallo
  // stream di hash.
  const data = hmac.read()
  if (data) {
    console.log(data.toString('hex'))
    // Stampa:
    //   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
  }
})

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

Esempio: Utilizzo di Hmac e stream piped:

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)

Esempio: Utilizzo dei metodi hmac.update() e 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'))
// Stampa:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
js
const { createHmac } = require('node:crypto')

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

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

hmac.digest([encoding]) ​

Aggiunto in: v0.1.94

Calcola il digest HMAC di tutti i dati passati utilizzando hmac.update(). Se viene fornita la encoding, viene restituita una stringa; altrimenti viene restituito un Buffer;

L'oggetto Hmac non può essere riutilizzato dopo che è stato chiamato hmac.digest(). Chiamate multiple a hmac.digest() genereranno un errore.

hmac.update(data[, inputEncoding]) ​

[Cronologia]

VersioneCambiamenti
v6.0.0La inputEncoding predefinita è cambiata da binary a utf8.
v0.1.94Aggiunto in: v0.1.94

Aggiorna il contenuto di Hmac con i data forniti, la cui codifica è specificata in inputEncoding. Se encoding non viene fornita, e i data sono una stringa, viene applicata la codifica 'utf8'. Se data è un Buffer, TypedArray o DataView, allora inputEncoding viene ignorata.

Questo può essere chiamato più volte con nuovi dati mentre vengono trasmessi in streaming.

Classe: KeyObject ​

[Cronologia]

VersioneCambiamenti
v14.5.0, v12.19.0Le istanze di questa classe ora possono essere passate a thread worker usando postMessage.
v11.13.0Questa classe è ora esportata.
v11.6.0Aggiunto in: v11.6.0

Node.js utilizza una classe KeyObject per rappresentare una chiave simmetrica o asimmetrica, e ogni tipo di chiave espone funzioni diverse. I metodi crypto.createSecretKey(), crypto.createPublicKey() e crypto.createPrivateKey() vengono utilizzati per creare istanze KeyObject. Gli oggetti KeyObject non devono essere creati direttamente utilizzando la parola chiave new.

La maggior parte delle applicazioni dovrebbe considerare l'utilizzo della nuova API KeyObject invece di passare le chiavi come stringhe o Buffer a causa delle migliori funzionalità di sicurezza.

Le istanze KeyObject possono essere passate ad altri thread tramite postMessage(). Il ricevitore ottiene un KeyObject clonato e KeyObject non deve essere elencato nell'argomento transferList.

Metodo statico: KeyObject.from(key) ​

Aggiunto in: v15.0.0

Esempio: Conversione di un'istanza CryptoKey in un 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)
// Stampa: 32 (dimensione della chiave simmetrica in byte)
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)
  // Stampa: 32 (dimensione della chiave simmetrica in byte)
})()

keyObject.asymmetricKeyDetails ​

[Cronologia]

VersioneModifiche
v16.9.0Espone i parametri della sequenza RSASSA-PSS-params per le chiavi RSA-PSS.
v15.7.0Aggiunto in: v15.7.0
  • <Object>
    • modulusLength: <number> Dimensione della chiave in bit (RSA, DSA).
    • publicExponent: <bigint> Esponente pubblico (RSA).
    • hashAlgorithm: <string> Nome del digest del messaggio (RSA-PSS).
    • mgf1HashAlgorithm: <string> Nome del digest del messaggio utilizzato da MGF1 (RSA-PSS).
    • saltLength: <number> Lunghezza minima del salt in byte (RSA-PSS).
    • divisorLength: <number> Dimensione di q in bit (DSA).
    • namedCurve: <string> Nome della curva (EC).

Questa proprietà esiste solo sulle chiavi asimmetriche. A seconda del tipo di chiave, questo oggetto contiene informazioni sulla chiave. Nessuna delle informazioni ottenute tramite questa proprietà può essere utilizzata per identificare in modo univoco una chiave o per compromettere la sicurezza della chiave.

Per le chiavi RSA-PSS, se il materiale della chiave contiene una sequenza RSASSA-PSS-params, le proprietà hashAlgorithm, mgf1HashAlgorithm e saltLength verranno impostate.

Altri dettagli della chiave potrebbero essere esposti tramite questa API utilizzando attributi aggiuntivi.

keyObject.asymmetricKeyType ​

[Cronologia]

VersioneModifiche
v13.9.0, v12.17.0Aggiunto il supporto per 'dh'.
v12.0.0Aggiunto il supporto per 'rsa-pss'.
v12.0.0Questa proprietà ora restituisce undefined per le istanze di KeyObject di tipo non riconosciuto invece di interrompersi.
v12.0.0Aggiunto il supporto per 'x25519' e 'x448'.
v12.0.0Aggiunto il supporto per 'ed25519' e 'ed448'.
v11.6.0Aggiunto in: v11.6.0

Per le chiavi asimmetriche, questa proprietà rappresenta il tipo di chiave. I tipi di chiave supportati sono:

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

Questa proprietà è undefined per i tipi KeyObject non riconosciuti e le chiavi simmetriche.

keyObject.equals(otherKeyObject) ​

Aggiunto in: v17.7.0, v16.15.0

Restituisce true o false a seconda che le chiavi abbiano esattamente lo stesso tipo, valore e parametri. Questo metodo non è a tempo costante.

keyObject.export([options]) ​

[Cronologia]

VersioneModifiche
v15.9.0Aggiunto il supporto per il formato 'jwk'.
v11.6.0Aggiunto in: v11.6.0

Per le chiavi simmetriche, è possibile utilizzare le seguenti opzioni di codifica:

  • format: <stringa> Deve essere 'buffer' (predefinito) o 'jwk'.

Per le chiavi pubbliche, è possibile utilizzare le seguenti opzioni di codifica:

  • type: <stringa> Deve essere uno tra 'pkcs1' (solo RSA) o 'spki'.
  • format: <stringa> Deve essere 'pem', 'der', o 'jwk'.

Per le chiavi private, è possibile utilizzare le seguenti opzioni di codifica:

  • type: <stringa> Deve essere uno tra 'pkcs1' (solo RSA), 'pkcs8' o 'sec1' (solo EC).
  • format: <stringa> Deve essere 'pem', 'der', o 'jwk'.
  • cipher: <stringa> Se specificato, la chiave privata verrà crittografata con il dato cipher e passphrase utilizzando la crittografia basata su password PKCS#5 v2.0.
  • passphrase: <stringa> | <Buffer> La passphrase da utilizzare per la crittografia, vedere cipher.

Il tipo di risultato dipende dal formato di codifica selezionato, quando PEM il risultato è una stringa, quando DER sarà un buffer contenente i dati codificati come DER, quando JWK sarà un oggetto.

Quando è stato selezionato il formato di codifica JWK, tutte le altre opzioni di codifica vengono ignorate.

Le chiavi di tipo PKCS#1, SEC1 e PKCS#8 possono essere crittografate utilizzando una combinazione delle opzioni cipher e format. Il type PKCS#8 può essere utilizzato con qualsiasi format per crittografare qualsiasi algoritmo di chiave (RSA, EC o DH) specificando un cipher. PKCS#1 e SEC1 possono essere crittografati solo specificando un cipher quando viene utilizzato il format PEM. Per la massima compatibilità, utilizzare PKCS#8 per le chiavi private crittografate. Poiché PKCS#8 definisce il proprio meccanismo di crittografia, la crittografia a livello PEM non è supportata quando si crittografa una chiave PKCS#8. Vedere RFC 5208 per la crittografia PKCS#8 e RFC 1421 per la crittografia PKCS#1 e SEC1.

keyObject.symmetricKeySize ​

Aggiunto in: v11.6.0

Per le chiavi segrete, questa proprietà rappresenta la dimensione della chiave in byte. Questa proprietà è undefined per le chiavi asimmetriche.

keyObject.toCryptoKey(algorithm, extractable, keyUsages) ​

Aggiunto in: v23.0.0

Converte un'istanza KeyObject in una CryptoKey.

keyObject.type ​

Aggiunto in: v11.6.0

A seconda del tipo di questo KeyObject, questa proprietà è 'secret' per le chiavi segrete (simmetriche), 'public' per le chiavi pubbliche (asimmetriche) o 'private' per le chiavi private (asimmetriche).

Classe: Sign ​

Aggiunto in: v0.1.92

La classe Sign è un'utilità per generare firme. Può essere utilizzata in uno dei due modi:

  • Come uno stream scrivibile, dove vengono scritti i dati da firmare e il metodo sign.sign() viene utilizzato per generare e restituire la firma, oppure
  • Utilizzando i metodi sign.update() e sign.sign() per produrre la firma.

Il metodo crypto.createSign() viene utilizzato per creare istanze Sign. L'argomento è il nome stringa della funzione hash da utilizzare. Gli oggetti Sign non devono essere creati direttamente utilizzando la parola chiave new.

Esempio: Utilizzo degli oggetti Sign e Verify come stream:

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

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

const sign = createSign('SHA256')
sign.write('alcuni dati da firmare')
sign.end()
const signature = sign.sign(privateKey, 'hex')

const verify = createVerify('SHA256')
verify.write('alcuni dati da firmare')
verify.end()
console.log(verify.verify(publicKey, signature, 'hex'))
// Stampa: true
js
const { generateKeyPairSync, createSign, createVerify } = require('node:crypto')

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

const sign = createSign('SHA256')
sign.write('alcuni dati da firmare')
sign.end()
const signature = sign.sign(privateKey, 'hex')

const verify = createVerify('SHA256')
verify.write('alcuni dati da firmare')
verify.end()
console.log(verify.verify(publicKey, signature, 'hex'))
// Stampa: true

Esempio: Utilizzo dei metodi sign.update() e verify.update():

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

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

const sign = createSign('SHA256')
sign.update('alcuni dati da firmare')
sign.end()
const signature = sign.sign(privateKey)

const verify = createVerify('SHA256')
verify.update('alcuni dati da firmare')
verify.end()
console.log(verify.verify(publicKey, signature))
// Stampa: true
js
const { generateKeyPairSync, createSign, createVerify } = require('node:crypto')

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

const sign = createSign('SHA256')
sign.update('alcuni dati da firmare')
sign.end()
const signature = sign.sign(privateKey)

const verify = createVerify('SHA256')
verify.update('alcuni dati da firmare')
verify.end()
console.log(verify.verify(publicKey, signature))
// Stampa: true

sign.sign(privateKey[, outputEncoding]) ​

[Cronologia]

VersioneModifiche
v15.0.0privateKey può essere anche un ArrayBuffer e CryptoKey.
v13.2.0, v12.16.0Questa funzione ora supporta le firme DSA e ECDSA IEEE-P1363.
v12.0.0Questa funzione ora supporta le chiavi RSA-PSS.
v11.6.0Questa funzione ora supporta gli oggetti chiave.
v8.0.0È stato aggiunto il supporto per RSASSA-PSS e opzioni aggiuntive.
v0.1.92Aggiunto in: v0.1.92

Calcola la firma su tutti i dati passati utilizzando sign.update() o sign.write().

Se privateKey non è un KeyObject, questa funzione si comporta come se privateKey fosse stata passata a crypto.createPrivateKey(). Se è un oggetto, possono essere passate le seguenti proprietà aggiuntive:

  • dsaEncoding <string> Per DSA ed ECDSA, questa opzione specifica il formato della firma generata. Può essere uno dei seguenti:

    • 'der' (predefinito): struttura di firma ASN.1 codificata DER che codifica (r, s).
    • 'ieee-p1363': formato della firma r || s come proposto in IEEE-P1363.

  • padding <integer> Valore di riempimento opzionale per RSA, uno dei seguenti:

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

RSA_PKCS1_PSS_PADDING userà MGF1 con la stessa funzione hash utilizzata per firmare il messaggio come specificato nella sezione 3.1 di RFC 4055, a meno che una funzione hash MGF1 non sia stata specificata come parte della chiave in conformità con la sezione 3.3 di RFC 4055.

  • saltLength <integer> Lunghezza del sale quando il riempimento è RSA_PKCS1_PSS_PADDING. Il valore speciale crypto.constants.RSA_PSS_SALTLEN_DIGEST imposta la lunghezza del sale alla dimensione del digest, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (predefinito) la imposta al valore massimo consentito.

Se viene fornito outputEncoding, viene restituita una stringa; altrimenti viene restituito un Buffer.

L'oggetto Sign non può essere riutilizzato dopo che il metodo sign.sign() è stato chiamato. Più chiamate a sign.sign() comporteranno la generazione di un errore.

sign.update(data[, inputEncoding]) ​

[Cronologia]

VersioneModifiche
v6.0.0La inputEncoding predefinita è cambiata da binary a utf8.
v0.1.92Aggiunto in: v0.1.92

Aggiorna il contenuto di Sign con i data specificati, la cui codifica è specificata in inputEncoding. Se encoding non viene fornito e data è una stringa, viene applicata la codifica 'utf8'. Se data è un Buffer, TypedArray o DataView, allora inputEncoding viene ignorato.

Questa funzione può essere chiamata più volte con nuovi dati mentre vengono trasmessi in streaming.

Classe: Verify ​

Aggiunto in: v0.1.92

La classe Verify è un'utilità per la verifica delle firme. Può essere utilizzata in due modi:

  • Come uno stream scrivibile in cui i dati scritti vengono utilizzati per la convalida rispetto alla firma fornita, oppure
  • Utilizzando i metodi verify.update() e verify.verify() per verificare la firma.

Il metodo crypto.createVerify() viene utilizzato per creare istanze Verify. Gli oggetti Verify non devono essere creati direttamente usando la parola chiave new.

Vedi Sign per esempi.

verify.update(data[, inputEncoding]) ​

[Cronologia]

VersioneModifiche
v6.0.0La inputEncoding predefinita è cambiata da binary a utf8.
v0.1.92Aggiunto in: v0.1.92

Aggiorna il contenuto di Verify con i data specificati, la cui codifica è specificata in inputEncoding. Se inputEncoding non viene fornito e data è una stringa, viene applicata la codifica 'utf8'. Se data è un Buffer, TypedArray o DataView, allora inputEncoding viene ignorato.

Questa funzione può essere chiamata più volte con nuovi dati mentre vengono trasmessi in streaming.

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

[Cronologia]

VersioneModifiche
v15.0.0L'oggetto può essere anche un ArrayBuffer e una CryptoKey.
v13.2.0, v12.16.0Questa funzione ora supporta firme DSA e ECDSA IEEE-P1363.
v12.0.0Questa funzione ora supporta chiavi RSA-PSS.
v11.7.0La chiave ora può essere una chiave privata.
v8.0.0È stato aggiunto il supporto per RSASSA-PSS e opzioni aggiuntive.
v0.1.92Aggiunto in: v0.1.92

Verifica i dati forniti utilizzando l'object e la signature indicati.

Se object non è un KeyObject, questa funzione si comporta come se object fosse stato passato a crypto.createPublicKey(). Se è un oggetto, è possibile passare le seguenti proprietà aggiuntive:

  • dsaEncoding <string> Per DSA e ECDSA, questa opzione specifica il formato della firma. Può essere uno dei seguenti:

    • 'der' (predefinito): Struttura della firma ASN.1 con codifica DER che codifica (r, s).
    • 'ieee-p1363': Formato della firma r || s come proposto in IEEE-P1363.

  • padding <integer> Valore di padding opzionale per RSA, uno dei seguenti:

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

RSA_PKCS1_PSS_PADDING userà MGF1 con la stessa funzione hash utilizzata per verificare il messaggio come specificato nella sezione 3.1 di RFC 4055, a meno che non sia stata specificata una funzione hash MGF1 come parte della chiave in conformità alla sezione 3.3 di RFC 4055.

  • saltLength <integer> Lunghezza del salt per quando il padding è RSA_PKCS1_PSS_PADDING. Il valore speciale crypto.constants.RSA_PSS_SALTLEN_DIGEST imposta la lunghezza del salt alla dimensione del digest, crypto.constants.RSA_PSS_SALTLEN_AUTO (predefinito) fa sì che venga determinata automaticamente.

L'argomento signature è la firma calcolata in precedenza per i dati, nella signatureEncoding. Se viene specificata una signatureEncoding, si prevede che signature sia una stringa; altrimenti, si prevede che signature sia un Buffer, TypedArray o DataView.

L'oggetto verify non può essere riutilizzato dopo che è stato chiamato verify.verify(). Chiamate multiple a verify.verify() genereranno un errore.

Poiché le chiavi pubbliche possono essere derivate dalle chiavi private, è possibile passare una chiave privata invece di una chiave pubblica.

Classe: X509Certificate ​

Aggiunto in: v15.6.0

Incapsula un certificato X509 e fornisce accesso in sola lettura alle sue informazioni.

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

const x509 = new X509Certificate('{... certificato codificato pem ...}')

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

const x509 = new X509Certificate('{... certificato codificato pem ...}')

console.log(x509.subject)

new X509Certificate(buffer) ​

Aggiunto in: v15.6.0

x509.ca ​

Aggiunto in: v15.6.0

  • Tipo: <boolean> Sarà true se questo è un certificato di Autorità di Certificazione (CA).

x509.checkEmail(email[, options]) ​

[Cronologia]

VersioneCambiamenti
v18.0.0L'opzione subject ora ha come predefinito 'default'.
v17.5.0, v16.15.0L'opzione subject ora può essere impostata su 'default'.
v17.5.0, v16.14.1Le opzioni wildcards, partialWildcards, multiLabelWildcards e singleLabelSubdomains sono state rimosse poiché non avevano effetto.
v15.6.0Aggiunto in: v15.6.0

  • email <string>

  • options <Object>

    • subject <string> 'default', 'always' o 'never'. Predefinito: 'default'.

  • Restituisce: <string> | <undefined> Restituisce email se il certificato corrisponde, undefined se non corrisponde.

Verifica se il certificato corrisponde all'indirizzo email specificato.

Se l'opzione 'subject' è indefinita o impostata su 'default', il soggetto del certificato viene preso in considerazione solo se l'estensione del nome alternativo del soggetto o non esiste o non contiene alcun indirizzo email.

Se l'opzione 'subject' è impostata su 'always' e se l'estensione del nome alternativo del soggetto o non esiste o non contiene un indirizzo email corrispondente, viene considerato il soggetto del certificato.

Se l'opzione 'subject' è impostata su 'never', il soggetto del certificato non viene mai preso in considerazione, anche se il certificato non contiene nomi alternativi del soggetto.

x509.checkHost(name[, options]) ​

[Cronologia]

VersioneModifiche
v18.0.0L'opzione subject ora ha come valore predefinito 'default'.
v17.5.0, v16.15.0L'opzione subject ora può essere impostata su 'default'.
v15.6.0Aggiunto in: v15.6.0

  • name <string>

  • options <Object>

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

  • Restituisce: <string> | <undefined> Restituisce un nome soggetto che corrisponde a name, o undefined se nessun nome soggetto corrisponde a name.

Verifica se il certificato corrisponde al nome host specificato.

Se il certificato corrisponde al nome host specificato, viene restituito il nome soggetto corrispondente. Il nome restituito potrebbe essere una corrispondenza esatta (ad es. foo.example.com) oppure potrebbe contenere caratteri jolly (ad es. *.example.com). Poiché i confronti dei nomi host non fanno distinzione tra maiuscole e minuscole, il nome soggetto restituito potrebbe anche differire dal name specificato per la capitalizzazione.

Se l'opzione 'subject' è non definita o impostata su 'default', il soggetto del certificato viene considerato solo se l'estensione del nome alternativo del soggetto non esiste o non contiene alcun nome DNS. Questo comportamento è coerente con RFC 2818 ("HTTP Over TLS").

Se l'opzione 'subject' è impostata su 'always' e se l'estensione del nome alternativo del soggetto non esiste o non contiene un nome DNS corrispondente, viene considerato il soggetto del certificato.

Se l'opzione 'subject' è impostata su 'never', il soggetto del certificato non viene mai considerato, anche se il certificato non contiene nomi alternativi del soggetto.

x509.checkIP(ip) ​

[Cronologia]

VersioneModifiche
v17.5.0, v16.14.1L'argomento options è stato rimosso poiché non aveva alcun effetto.
v15.6.0Aggiunto in: v15.6.0

Verifica se il certificato corrisponde all'indirizzo IP specificato (IPv4 o IPv6).

Vengono presi in considerazione solo i nomi alternativi del soggetto iPAddress RFC 5280 e devono corrispondere esattamente all'indirizzo ip specificato. Altri nomi alternativi del soggetto, così come il campo soggetto del certificato, vengono ignorati.

x509.checkIssued(otherCert) ​

Aggiunto in: v15.6.0

Verifica se questo certificato è stato rilasciato dal otherCert specificato.

x509.checkPrivateKey(privateKey) ​

Aggiunto in: v15.6.0

Verifica se la chiave pubblica per questo certificato è coerente con la chiave privata specificata.

x509.extKeyUsage ​

Aggiunto in: v15.6.0

Un array che dettaglia gli usi estesi della chiave per questo certificato.

x509.fingerprint ​

Aggiunto in: v15.6.0

L'impronta SHA-1 di questo certificato.

Poiché SHA-1 è crittograficamente rotto e poiché la sicurezza di SHA-1 è significativamente inferiore a quella degli algoritmi che vengono comunemente utilizzati per firmare i certificati, considera l'utilizzo di x509.fingerprint256 invece.

x509.fingerprint256 ​

Aggiunto in: v15.6.0

L'impronta digitale SHA-256 di questo certificato.

x509.fingerprint512 ​

Aggiunto in: v17.2.0, v16.14.0

L'impronta digitale SHA-512 di questo certificato.

Poiché il calcolo dell'impronta digitale SHA-256 è generalmente più veloce e perché è solo la metà della dimensione dell'impronta digitale SHA-512, x509.fingerprint256 potrebbe essere una scelta migliore. Mentre SHA-512 presumibilmente fornisce un livello di sicurezza più elevato in generale, la sicurezza di SHA-256 corrisponde a quella della maggior parte degli algoritmi comunemente usati per firmare i certificati.

x509.infoAccess ​

[Cronologia]

VersioneModifiche
v17.3.1, v16.13.2Parti di questa stringa potrebbero essere codificate come valori letterali stringa JSON in risposta a CVE-2021-44532.
v15.6.0Aggiunto in: v15.6.0

Una rappresentazione testuale dell'estensione di accesso alle informazioni dell'autorità del certificato.

Si tratta di un elenco di descrizioni di accesso separate da un'interruzione di riga. Ogni riga inizia con il metodo di accesso e il tipo della posizione di accesso, seguiti da due punti e dal valore associato alla posizione di accesso.

Dopo il prefisso che indica il metodo di accesso e il tipo della posizione di accesso, il resto di ogni riga potrebbe essere racchiuso tra virgolette per indicare che il valore è un valore letterale stringa JSON. Per compatibilità con le versioni precedenti, Node.js utilizza i valori letterali stringa JSON all'interno di questa proprietà solo quando necessario per evitare ambiguità. Il codice di terze parti dovrebbe essere preparato a gestire entrambi i possibili formati di ingresso.

x509.issuer ​

Aggiunto in: v15.6.0

L'identificazione dell'emittente inclusa in questo certificato.

x509.issuerCertificate ​

Aggiunto in: v15.9.0

Il certificato dell'emittente o undefined se il certificato dell'emittente non è disponibile.

x509.publicKey ​

Aggiunto in: v15.6.0

La chiave pubblica <KeyObject> per questo certificato.

x509.raw ​

Aggiunto in: v15.6.0

Un Buffer contenente la codifica DER di questo certificato.

x509.serialNumber ​

Aggiunto in: v15.6.0

Il numero di serie di questo certificato.

I numeri di serie sono assegnati dalle autorità di certificazione e non identificano univocamente i certificati. Considera di usare x509.fingerprint256 come identificatore univoco.

x509.subject ​

Aggiunto in: v15.6.0

Il soggetto completo di questo certificato.

x509.subjectAltName ​

[Cronologia]

VersioneModifiche
v17.3.1, v16.13.2Parti di questa stringa possono essere codificate come stringhe letterali JSON in risposta a CVE-2021-44532.
v15.6.0Aggiunto in: v15.6.0

Il nome alternativo del soggetto specificato per questo certificato.

Si tratta di un elenco di nomi alternativi del soggetto separati da virgole. Ogni voce inizia con una stringa che identifica il tipo del nome alternativo del soggetto seguita da due punti e dal valore associato alla voce.

Le versioni precedenti di Node.js presupponevano erroneamente che fosse sicuro dividere questa proprietà alla sequenza di due caratteri ', ' (vedi CVE-2021-44532). Tuttavia, certificati sia dannosi che legittimi possono contenere nomi alternativi del soggetto che includono questa sequenza quando rappresentati come stringa.

Dopo il prefisso che indica il tipo della voce, il resto di ciascuna voce potrebbe essere racchiuso tra virgolette per indicare che il valore è una stringa letterale JSON. Per la retrocompatibilità, Node.js usa stringhe letterali JSON all'interno di questa proprietà solo quando necessario per evitare ambiguità. Il codice di terze parti dovrebbe essere pronto a gestire entrambi i possibili formati di voce.

x509.toJSON() ​

Aggiunto in: v15.6.0

Non esiste una codifica JSON standard per i certificati X509. Il metodo toJSON() restituisce una stringa contenente il certificato codificato PEM.

x509.toLegacyObject() ​

Aggiunto in: v15.6.0

Restituisce informazioni su questo certificato utilizzando la codifica legacy oggetto certificato.

x509.toString() ​

Aggiunto in: v15.6.0

Restituisce il certificato codificato PEM.

x509.validFrom ​

Aggiunto in: v15.6.0

La data/ora a partire dalla quale questo certificato è valido.

x509.validFromDate ​

Aggiunto in: v23.0.0

La data/ora a partire dalla quale questo certificato è valido, incapsulata in un oggetto Date.

x509.validTo ​

Aggiunto in: v15.6.0

La data/ora fino alla quale questo certificato è valido.

x509.validToDate ​

Aggiunto in: v23.0.0

La data/ora fino alla quale questo certificato è valido, incapsulata in un oggetto Date.

x509.verify(publicKey) ​

Aggiunto in: v15.6.0

Verifica che questo certificato sia stato firmato dalla chiave pubblica fornita. Non esegue altre verifiche di validazione sul certificato.

Metodi e proprietà del modulo node:crypto ​

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

[Cronologia]

VersioneCambiamenti
v18.0.0Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v15.8.0Aggiunto in: v15.8.0
  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> Un possibile numero primo codificato come una sequenza di ottetti big endian di lunghezza arbitraria.
  • options <Object>
    • checks <number> Il numero di iterazioni di primalità probabilistiche di Miller-Rabin da eseguire. Quando il valore è 0 (zero), viene utilizzato un numero di controlli che produce una percentuale di falsi positivi pari al massimo a 2 per input casuali. È necessario prestare attenzione quando si seleziona un numero di controlli. Fare riferimento alla documentazione OpenSSL per le opzioni nchecks della funzione BN_is_prime_ex per maggiori dettagli. Predefinito: 0
  • callback <Function>
    • err <Error> Impostato su un oggetto <Error> se si è verificato un errore durante il controllo.
    • result <boolean> true se il candidato è un numero primo con una probabilità di errore inferiore a 0.25 ** options.checks.

Verifica la primalità del candidate.

crypto.checkPrimeSync(candidate[, options]) ​

Aggiunto in: v15.8.0

  • candidate <ArrayBuffer> | <SharedArrayBuffer> | <TypedArray> | <Buffer> | <DataView> | <bigint> Un possibile numero primo codificato come una sequenza di ottetti big endian di lunghezza arbitraria.

  • options <Object>

    • checks <number> Il numero di iterazioni probabilistiche di primalità Miller-Rabin da eseguire. Quando il valore è 0 (zero), viene utilizzato un numero di controlli che produce un tasso di falsi positivi al massimo di 2 per l'input casuale. Occorre prestare attenzione quando si seleziona un numero di controlli. Fare riferimento alla documentazione di OpenSSL per le opzioni nchecks della funzione BN_is_prime_ex per maggiori dettagli. Predefinito: 0

  • Restituisce: <boolean> true se il candidato è un numero primo con una probabilità di errore inferiore a 0.25 ** options.checks.

Verifica la primalità del candidate.

crypto.constants ​

Aggiunto in: v6.3.0

Un oggetto contenente costanti di uso comune per operazioni relative alla crittografia e alla sicurezza. Le costanti specifiche attualmente definite sono descritte in Costanti crittografiche.

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

[Cronologia]

VersioneModifiche
v17.9.0, v16.17.0L'opzione authTagLength è ora opzionale quando si utilizza la cifratura chacha20-poly1305 e il valore predefinito è 16 byte.
v15.0.0Gli argomenti password e iv possono essere un ArrayBuffer e sono ciascuno limitati a un massimo di 2 ** 31 - 1 byte.
v11.6.0L'argomento key ora può essere un KeyObject.
v11.2.0, v10.17.0La cifratura chacha20-poly1305 (la variante IETF di ChaCha20-Poly1305) è ora supportata.
v10.10.0Le cifrature in modalità OCB sono ora supportate.
v10.2.0L'opzione authTagLength può ora essere utilizzata per produrre tag di autenticazione più brevi in modalità GCM e il valore predefinito è 16 byte.
v9.9.0Il parametro iv ora può essere null per le cifrature che non necessitano di un vettore di inizializzazione.
v0.1.94Aggiunto in: v0.1.94

Crea e restituisce un oggetto Cipher, con l'algoritmo, la chiave e il vettore di inizializzazione (iv) forniti.

L'argomento options controlla il comportamento del flusso ed è facoltativo tranne quando viene utilizzata una cifratura in modalità CCM o OCB (ad es. 'aes-128-ccm'). In tal caso, l'opzione authTagLength è obbligatoria e specifica la lunghezza del tag di autenticazione in byte, vedi modalità CCM. In modalità GCM, l'opzione authTagLength non è obbligatoria ma può essere utilizzata per impostare la lunghezza del tag di autenticazione che verrà restituito da getAuthTag() e il valore predefinito è 16 byte. Per chacha20-poly1305, l'opzione authTagLength il valore predefinito è 16 byte.

L'algorithm dipende da OpenSSL, ad esempio 'aes192', ecc. Nelle recenti versioni di OpenSSL, openssl list -cipher-algorithms mostrerà gli algoritmi di cifratura disponibili.

La key è la chiave grezza utilizzata dall'algorithm e iv è un vettore di inizializzazione. Entrambi gli argomenti devono essere stringhe con codifica 'utf8', Buffer, TypedArray o DataView. La key può facoltativamente essere un KeyObject di tipo secret. Se la cifratura non necessita di un vettore di inizializzazione, iv può essere null.

Quando si passano stringhe per key o iv, si prega di considerare le avvertenze quando si utilizzano stringhe come input per le API crittografiche.

I vettori di inizializzazione devono essere imprevedibili e unici; idealmente, saranno crittograficamente casuali. Non devono essere segreti: gli IV vengono in genere semplicemente aggiunti ai messaggi di testo cifrato non crittografati. Può sembrare contraddittorio che qualcosa debba essere imprevedibile e unico, ma non debba essere segreto; ricorda che un utente malintenzionato non deve essere in grado di prevedere in anticipo quale sarà un determinato IV.

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

[Cronologia]

VersioneModifiche
v17.9.0, v16.17.0L'opzione authTagLength è ora facoltativa quando si usa la cifratura chacha20-poly1305 e il valore predefinito è di 16 byte.
v11.6.0L'argomento key ora può essere un KeyObject.
v11.2.0, v10.17.0La cifratura chacha20-poly1305 (la variante IETF di ChaCha20-Poly1305) è ora supportata.
v10.10.0Le cifrature in modalità OCB sono ora supportate.
v10.2.0L'opzione authTagLength ora può essere usata per limitare le lunghezze dei tag di autenticazione GCM accettate.
v9.9.0Il parametro iv ora può essere null per le cifrature che non necessitano di un vettore di inizializzazione.
v0.1.94Aggiunto in: v0.1.94

Crea e restituisce un oggetto Decipher che utilizza l'algorithm, la key e il vettore di inizializzazione (iv) forniti.

L'argomento options controlla il comportamento del flusso ed è facoltativo tranne quando viene utilizzata una cifratura in modalità CCM o OCB (ad es. 'aes-128-ccm'). In tal caso, l'opzione authTagLength è richiesta e specifica la lunghezza del tag di autenticazione in byte, vedi modalità CCM. Per AES-GCM e chacha20-poly1305, l'opzione authTagLength è impostata per default a 16 byte e deve essere impostata su un valore diverso se viene utilizzata una lunghezza differente.

L'algorithm dipende da OpenSSL, alcuni esempi sono 'aes192', ecc. Nelle recenti versioni di OpenSSL, openssl list -cipher-algorithms visualizzerà gli algoritmi di cifratura disponibili.

La key è la chiave non elaborata utilizzata dall'algorithm e iv è un vettore di inizializzazione. Entrambi gli argomenti devono essere stringhe con codifica 'utf8', Buffer, TypedArray o DataView. La key può essere opzionalmente un KeyObject di tipo secret. Se la cifratura non necessita di un vettore di inizializzazione, iv può essere null.

Quando si passano stringhe per key o iv, si prega di considerare avvertenze quando si usano stringhe come input per le API crittografiche.

I vettori di inizializzazione devono essere imprevedibili e univoci; idealmente, saranno crittograficamente casuali. Non devono essere segreti: gli IV vengono tipicamente aggiunti ai messaggi di testo cifrato non crittografati. Può sembrare contraddittorio che qualcosa debba essere imprevedibile e univoco, ma non debba essere segreto; ricorda che un attaccante non deve essere in grado di prevedere in anticipo quale sarà un dato IV.

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

[Cronologia]

VersioneModifiche
v8.0.0L'argomento prime ora può essere qualsiasi TypedArray o DataView.
v8.0.0L'argomento prime ora può essere un Uint8Array.
v6.0.0Il valore predefinito per i parametri di codifica è cambiato da binary a utf8.
v0.11.12Aggiunto in: v0.11.12

Crea un oggetto di scambio di chiavi DiffieHellman utilizzando il prime fornito e un generator specifico opzionale.

L'argomento generator può essere un numero, una stringa o un Buffer. Se generator non viene specificato, viene utilizzato il valore 2.

Se viene specificato primeEncoding, si prevede che prime sia una stringa; altrimenti si prevede un Buffer, TypedArray o DataView.

Se viene specificato generatorEncoding, si prevede che generator sia una stringa; altrimenti si prevede un numero, un Buffer, TypedArray o DataView.

crypto.createDiffieHellman(primeLength[, generator]) ​

Aggiunto in: v0.5.0

Crea un oggetto di scambio chiavi DiffieHellman e genera un numero primo di primeLength bit utilizzando un generator numerico specifico opzionale. Se generator non è specificato, viene utilizzato il valore 2.

crypto.createDiffieHellmanGroup(name) ​

Aggiunto in: v0.9.3

Un alias per crypto.getDiffieHellman()

crypto.createECDH(curveName) ​

Aggiunto in: v0.11.14

Crea un oggetto di scambio chiavi Elliptic Curve Diffie-Hellman (ECDH) utilizzando una curva predefinita specificata dalla stringa curveName. Utilizzare crypto.getCurves() per ottenere un elenco di nomi di curve disponibili. Nelle versioni recenti di OpenSSL, openssl ecparam -list_curves visualizzerà anche il nome e la descrizione di ciascuna curva ellittica disponibile.

crypto.createHash(algorithm[, options]) ​

[Cronologia]

VersioneModifiche
v12.8.0L'opzione outputLength è stata aggiunta per le funzioni hash XOF.
v0.1.92Aggiunto in: v0.1.92

Crea e restituisce un oggetto Hash che può essere utilizzato per generare digest hash utilizzando l'algorithm specificato. L'argomento opzionale options controlla il comportamento del flusso. Per le funzioni hash XOF come 'shake256', l'opzione outputLength può essere utilizzata per specificare la lunghezza di output desiderata in byte.

L'algorithm dipende dagli algoritmi disponibili supportati dalla versione di OpenSSL sulla piattaforma. Esempi sono 'sha256', 'sha512', ecc. Nelle versioni recenti di OpenSSL, openssl list -digest-algorithms visualizzerà gli algoritmi digest disponibili.

Esempio: generazione della somma sha256 di un file

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', () => {
  // Verrà prodotto un solo elemento dal flusso hash.
  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', () => {
  // Verrà prodotto un solo elemento dal flusso hash.
  const data = input.read()
  if (data) hash.update(data)
  else {
    console.log(`${hash.digest('hex')} ${filename}`)
  }
})

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

[Cronologia]

VersioneModifiche
v15.0.0La chiave può anche essere un ArrayBuffer o CryptoKey. È stata aggiunta l'opzione di codifica. La chiave non può contenere più di 2 ** 32 - 1 byte.
v11.6.0L'argomento key ora può essere un KeyObject.
v0.1.94Aggiunto in: v0.1.94

Crea e restituisce un oggetto Hmac che utilizza l'algorithm e la key forniti. L'argomento opzionale options controlla il comportamento dello stream.

L'algorithm dipende dagli algoritmi disponibili supportati dalla versione di OpenSSL sulla piattaforma. Esempi sono 'sha256', 'sha512', ecc. Nelle versioni recenti di OpenSSL, openssl list -digest-algorithms visualizzerà gli algoritmi di digest disponibili.

La key è la chiave HMAC utilizzata per generare l'hash crittografico HMAC. Se è un KeyObject, il suo tipo deve essere secret. Se è una stringa, si prega di considerare avvertenze quando si utilizzano stringhe come input per le API crittografiche. Se è stata ottenuta da una fonte di entropia crittograficamente sicura, come crypto.randomBytes() o crypto.generateKey(), la sua lunghezza non deve superare la dimensione del blocco di algorithm (ad es., 512 bit per SHA-256).

Esempio: generazione dell'HMAC sha256 di un file

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', () => {
  // Verrà prodotto un solo elemento dallo
  // stream hash.
  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', () => {
  // Verrà prodotto un solo elemento dallo
  // stream hash.
  const data = input.read()
  if (data) hmac.update(data)
  else {
    console.log(`${hmac.digest('hex')} ${filename}`)
  }
})

crypto.createPrivateKey(key) ​

[Cronologia]

VersioneModifiche
v15.12.0La chiave può essere anche un oggetto JWK.
v15.0.0La chiave può essere anche un ArrayBuffer. È stata aggiunta l'opzione di codifica. La chiave non può contenere più di 2 ** 32 - 1 byte.
v11.6.0Aggiunto in: v11.6.0

Crea e restituisce un nuovo oggetto chiave contenente una chiave privata. Se key è una stringa o Buffer, si assume che format sia 'pem'; altrimenti, key deve essere un oggetto con le proprietà descritte sopra.

Se la chiave privata è crittografata, deve essere specificata una passphrase. La lunghezza della passphrase è limitata a 1024 byte.

crypto.createPublicKey(key) ​

[Cronologia]

VersioneModifiche
v15.12.0La chiave può essere anche un oggetto JWK.
v15.0.0La chiave può essere anche un ArrayBuffer. È stata aggiunta l'opzione di encoding. La chiave non può contenere più di 2 ** 32 - 1 byte.
v11.13.0L'argomento key ora può essere un KeyObject con tipo private.
v11.7.0L'argomento key ora può essere una chiave privata.
v11.6.0Aggiunto in: v11.6.0

Crea e restituisce un nuovo oggetto chiave contenente una chiave pubblica. Se key è una stringa o un Buffer, si presume che format sia 'pem'; se key è un KeyObject con tipo 'private', la chiave pubblica viene derivata dalla chiave privata data; altrimenti, key deve essere un oggetto con le proprietà descritte sopra.

Se il formato è 'pem', la 'key' può essere anche un certificato X.509.

Poiché le chiavi pubbliche possono essere derivate da chiavi private, è possibile passare una chiave privata invece di una chiave pubblica. In tal caso, questa funzione si comporta come se fosse stato chiamato crypto.createPrivateKey(), tranne per il fatto che il tipo del KeyObject restituito sarà 'public' e che la chiave privata non può essere estratta dal KeyObject restituito. Analogamente, se viene fornito un KeyObject con tipo 'private', verrà restituito un nuovo KeyObject con tipo 'public' e sarà impossibile estrarre la chiave privata dall'oggetto restituito.

crypto.createSecretKey(key[, encoding]) ​

[Cronologia]

VersioneCambiamenti
v18.8.0, v16.18.0La chiave ora può essere di lunghezza zero.
v15.0.0La chiave può essere anche un ArrayBuffer o una stringa. L'argomento encoding è stato aggiunto. La chiave non può contenere più di 2 ** 32 - 1 byte.
v11.6.0Aggiunto in: v11.6.0

Crea e restituisce un nuovo oggetto chiave contenente una chiave segreta per la crittografia simmetrica o Hmac.

crypto.createSign(algorithm[, options]) ​

Aggiunto in: v0.1.92

Crea e restituisce un oggetto Sign che utilizza l'algorithm fornito. Utilizza crypto.getHashes() per ottenere i nomi degli algoritmi di digest disponibili. L'argomento facoltativo options controlla il comportamento di stream.Writable.

In alcuni casi, un'istanza Sign può essere creata usando il nome di un algoritmo di firma, come 'RSA-SHA256', invece di un algoritmo di digest. Questo utilizzerà l'algoritmo di digest corrispondente. Questo non funziona per tutti gli algoritmi di firma, come 'ecdsa-with-SHA256', quindi è meglio utilizzare sempre i nomi degli algoritmi di digest.

crypto.createVerify(algorithm[, options]) ​

Aggiunto in: v0.1.92

Crea e restituisce un oggetto Verify che utilizza l'algoritmo specificato. Utilizzare crypto.getHashes() per ottenere un array di nomi degli algoritmi di firma disponibili. L'argomento opzionale options controlla il comportamento di stream.Writable.

In alcuni casi, un'istanza Verify può essere creata utilizzando il nome di un algoritmo di firma, come 'RSA-SHA256', invece di un algoritmo di digest. Questo utilizzerà l'algoritmo di digest corrispondente. Questo non funziona per tutti gli algoritmi di firma, come 'ecdsa-with-SHA256', quindi è meglio usare sempre i nomi degli algoritmi di digest.

crypto.diffieHellman(options) ​

Aggiunto in: v13.9.0, v12.17.0

Calcola il segreto di Diffie-Hellman in base a una privateKey e una publicKey. Entrambe le chiavi devono avere lo stesso asymmetricKeyType, che deve essere uno tra 'dh' (per Diffie-Hellman), 'ec', 'x448' o 'x25519' (per ECDH).

crypto.fips ​

Aggiunto in: v6.0.0

Deprecato a partire da: v10.0.0

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato

Proprietà per controllare e verificare se è attualmente in uso un provider di crittografia conforme a FIPS. L'impostazione su true richiede una build FIPS di Node.js.

Questa proprietà è deprecata. Si prega di utilizzare invece crypto.setFips() e crypto.getFips().

crypto.generateKey(type, options, callback) ​

[Cronologia]

VersioneModifiche
v18.0.0Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v15.0.0Aggiunto in: v15.0.0

  • type: <string> L'uso previsto della chiave segreta generata. I valori attualmente accettati sono 'hmac' e 'aes'.

  • options: <Object>

    • length: <number> La lunghezza in bit della chiave da generare. Questo deve essere un valore maggiore di 0.
    • Se type è 'hmac', il valore minimo è 8 e la lunghezza massima è 2-1. Se il valore non è un multiplo di 8, la chiave generata verrà troncata a Math.floor(length / 8).
    • Se type è 'aes', la lunghezza deve essere 128, 192 o 256.

  • callback: <Function>

Genera in modo asincrono una nuova chiave segreta casuale della lunghezza specificata. Il type determinerà quali convalide verranno eseguite sulla length.

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
})

La dimensione di una chiave HMAC generata non deve superare la dimensione del blocco della funzione hash sottostante. Vedi crypto.createHmac() per maggiori informazioni.

crypto.generateKeyPair(type, options, callback) ​

[Storia]

VersioneCambiamenti
v18.0.0Passare un callback non valido all'argomento callback ora lancia ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v16.10.0Aggiunta la possibilità di definire i parametri della sequenza RSASSA-PSS-params per le coppie di chiavi RSA-PSS.
v13.9.0, v12.17.0Aggiunto il supporto per Diffie-Hellman.
v12.0.0Aggiunto il supporto per le coppie di chiavi RSA-PSS.
v12.0.0Aggiunta la possibilità di generare coppie di chiavi X25519 e X448.
v12.0.0Aggiunta la possibilità di generare coppie di chiavi Ed25519 e Ed448.
v11.6.0Le funzioni generateKeyPair e generateKeyPairSync ora producono oggetti chiave se non è stata specificata alcuna codifica.
v10.12.0Aggiunto in: v10.12.0

Genera una nuova coppia di chiavi asimmetriche del type specificato. Attualmente sono supportati RSA, RSA-PSS, DSA, EC, Ed25519, Ed448, X25519, X448 e DH.

Se è stato specificato un publicKeyEncoding o privateKeyEncoding, questa funzione si comporta come se fosse stato chiamato keyObject.export() sul suo risultato. Altrimenti, la rispettiva parte della chiave viene restituita come un KeyObject.

Si consiglia di codificare le chiavi pubbliche come 'spki' e le chiavi private come 'pkcs8' con crittografia per l'archiviazione a lungo termine:

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) => {
    // Gestisci gli errori e utilizza la coppia di chiavi generata.
  }
)
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) => {
    // Gestisci gli errori e utilizza la coppia di chiavi generata.
  }
)

Al completamento, callback verrà chiamato con err impostato su undefined e publicKey / privateKey che rappresentano la coppia di chiavi generata.

Se questo metodo viene invocato come sua versione util.promisify()ed, restituisce una Promise per un Oggetto con le proprietà publicKey e privateKey.

crypto.generateKeyPairSync(type, options) ​

[Cronologia]

VersioneModifiche
v16.10.0Aggiunta la possibilità di definire i parametri di sequenza RSASSA-PSS-params per le coppie di chiavi RSA-PSS.
v13.9.0, v12.17.0Aggiunto il supporto per Diffie-Hellman.
v12.0.0Aggiunto il supporto per le coppie di chiavi RSA-PSS.
v12.0.0Aggiunta la possibilità di generare coppie di chiavi X25519 e X448.
v12.0.0Aggiunta la possibilità di generare coppie di chiavi Ed25519 e Ed448.
v11.6.0Le funzioni generateKeyPair e generateKeyPairSync ora producono oggetti chiave se non è stata specificata alcuna codifica.
v10.12.0Aggiunto in: v10.12.0

Genera una nuova coppia di chiavi asimmetriche del type indicato. Attualmente sono supportati RSA, RSA-PSS, DSA, EC, Ed25519, Ed448, X25519, X448 e DH.

Se è stata specificata una publicKeyEncoding o privateKeyEncoding, questa funzione si comporta come se fosse stato chiamato keyObject.export() sul suo risultato. Altrimenti, la rispettiva parte della chiave viene restituita come KeyObject.

Quando si codificano le chiavi pubbliche, si consiglia di utilizzare 'spki'. Quando si codificano le chiavi private, si consiglia di utilizzare 'pkcs8' con una passphrase robusta e di mantenere riservata la passphrase.

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',
  },
})

Il valore di ritorno { publicKey, privateKey } rappresenta la coppia di chiavi generata. Quando è stata selezionata la codifica PEM, la chiave rispettiva sarà una stringa, altrimenti sarà un buffer contenente i dati codificati come DER.

crypto.generateKeySync(type, options) ​

Aggiunto in: v15.0.0

  • type: <string> L'uso previsto per la chiave segreta generata. I valori attualmente accettati sono 'hmac' e 'aes'.

  • options: <Object>

    • length: <number> La lunghezza in bit della chiave da generare.
    • Se type è 'hmac', il valore minimo è 8 e la lunghezza massima è 2-1. Se il valore non è un multiplo di 8, la chiave generata verrà troncata a Math.floor(length / 8).
    • Se type è 'aes', la lunghezza deve essere una tra 128, 192 o 256.

  • Restituisce: <KeyObject>

Genera in modo sincrono una nuova chiave segreta casuale della length specificata. Il type determinerà quali convalide verranno eseguite sulla length.

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

La dimensione di una chiave HMAC generata non deve superare la dimensione del blocco della funzione hash sottostante. Vedere crypto.createHmac() per maggiori informazioni.

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

[Cronologia]

VersioneModifiche
v18.0.0Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE anziché ERR_INVALID_CALLBACK.
v15.8.0Aggiunto in: v15.8.0

Genera un numero primo pseudocasuale di size bit.

Se options.safe è true, il numero primo sarà un numero primo sicuro, ovvero (prime - 1) / 2 sarà anch'esso un numero primo.

I parametri options.add e options.rem possono essere utilizzati per imporre requisiti aggiuntivi, ad esempio per Diffie-Hellman:

  • Se options.add e options.rem sono entrambi impostati, il numero primo soddisferà la condizione che prime % add = rem.
  • Se è impostato solo options.add e options.safe non è true, il numero primo soddisferà la condizione che prime % add = 1.
  • Se è impostato solo options.add e options.safe è impostato su true, il numero primo soddisferà invece la condizione che prime % add = 3. Ciò è necessario perché prime % add = 1 per options.add > 2 contraddirebbe la condizione imposta da options.safe.
  • options.rem viene ignorato se options.add non viene fornito.

Sia options.add che options.rem devono essere codificati come sequenze big-endian se forniti come ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer o DataView.

Per impostazione predefinita, il numero primo viene codificato come sequenza big-endian di ottetti in un <ArrayBuffer>. Se l'opzione bigint è true, viene fornito un <bigint>.

crypto.generatePrimeSync(size[, options]) ​

Aggiunto in: v15.8.0

Genera un numero primo pseudocasuale di size bit.

Se options.safe è true, il numero primo sarà un numero primo sicuro, ovvero (numero primo - 1) / 2 sarà anch'esso un numero primo.

I parametri options.add e options.rem possono essere utilizzati per applicare requisiti aggiuntivi, ad es., per Diffie-Hellman:

  • Se sono impostati sia options.add che options.rem, il numero primo soddisferà la condizione numero primo % add = rem.
  • Se è impostato solo options.add e options.safe non è true, il numero primo soddisferà la condizione numero primo % add = 1.
  • Se è impostato solo options.add e options.safe è impostato su true, il numero primo soddisferà invece la condizione numero primo % add = 3. Ciò è necessario perché numero primo % add = 1 per options.add > 2 contraddirebbe la condizione applicata da options.safe.
  • options.rem viene ignorato se options.add non viene fornito.

Sia options.add che options.rem devono essere codificati come sequenze big-endian se forniti come ArrayBuffer, SharedArrayBuffer, TypedArray, Buffer o DataView.

Per impostazione predefinita, il numero primo viene codificato come una sequenza big-endian di ottetti in un <ArrayBuffer>. Se l'opzione bigint è true, viene fornito un <bigint>.

crypto.getCipherInfo(nameOrNid[, options]) ​

Aggiunto in: v15.0.0

  • nameOrNid: <string> | <number> Il nome o nid della cifratura da interrogare.

  • options: <Object>

    • keyLength: <number> Una lunghezza di chiave di test.
    • ivLength: <number> Una lunghezza IV di test.

  • Restituisce: <Object>

    • name <string> Il nome della cifratura
    • nid <number> Il nid della cifratura
    • blockSize <number> La dimensione del blocco della cifratura in byte. Questa proprietà viene omessa quando mode è 'stream'.
    • ivLength <number> La lunghezza del vettore di inizializzazione previsto o predefinito in byte. Questa proprietà viene omessa se la cifratura non utilizza un vettore di inizializzazione.
    • keyLength <number> La lunghezza della chiave prevista o predefinita in byte.
    • mode <string> La modalità di cifratura. Uno tra 'cbc', 'ccm', 'cfb', 'ctr', 'ecb', 'gcm', 'ocb', 'ofb', 'stream', 'wrap', 'xts'.

Restituisce informazioni su una determinata cifratura.

Alcune cifrature accettano chiavi e vettori di inizializzazione a lunghezza variabile. Per impostazione predefinita, il metodo crypto.getCipherInfo() restituirà i valori predefiniti per queste cifrature. Per verificare se una determinata lunghezza della chiave o lunghezza iv è accettabile per una determinata cifratura, utilizzare le opzioni keyLength e ivLength. Se i valori forniti non sono accettabili, verrà restituito undefined.

crypto.getCiphers() ​

Aggiunto in: v0.9.3

  • Restituisce: <string[]> Un array con i nomi degli algoritmi di cifratura supportati.
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() ​

Aggiunto in: v2.3.0

  • Restituisce: <string[]> Un array con i nomi delle curve ellittiche supportate.
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) ​

Aggiunto in: v0.7.5

Crea un oggetto di scambio di chiavi DiffieHellmanGroup predefinito. I gruppi supportati sono elencati nella documentazione per DiffieHellmanGroup.

L'oggetto restituito simula l'interfaccia degli oggetti creati da crypto.createDiffieHellman(), ma non consentirà la modifica delle chiavi (con diffieHellman.setPublicKey(), ad esempio). Il vantaggio dell'utilizzo di questo metodo è che le parti non devono generare né scambiare preventivamente un modulo di gruppo, risparmiando tempo di processore e di comunicazione.

Esempio (ottenimento di un segreto condiviso):

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 e bobSecret dovrebbero essere uguali */
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 e bobSecret dovrebbero essere uguali */
console.log(aliceSecret === bobSecret)

crypto.getFips() ​

Aggiunto in: v10.0.0

  • Restituisce: <number> 1 se e solo se è in uso un provider di crittografia conforme a FIPS, 0 altrimenti. Una futura release semver-major potrebbe cambiare il tipo di ritorno di questa API in un <boolean>.

crypto.getHashes() ​

Aggiunto in: v0.9.3

  • Restituisce: <string[]> Un array dei nomi degli algoritmi hash supportati, come 'RSA-SHA256'. Gli algoritmi hash sono anche chiamati algoritmi "digest".
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) ​

Aggiunto in: v17.4.0

Un alias conveniente per crypto.webcrypto.getRandomValues(). Questa implementazione non è conforme alla specifica Web Crypto, per scrivere codice compatibile con il web usa invece crypto.webcrypto.getRandomValues().

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

Aggiunto in: v21.7.0, v20.12.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1.2 - Candidato alla release

Un'utilità per creare digest hash una tantum dei dati. Può essere più veloce di crypto.createHash() basato su oggetto quando si esegue l'hashing di una quantità di dati più piccola (<= 5 MB) che è prontamente disponibile. Se i dati possono essere grandi o se vengono trasmessi in streaming, si consiglia comunque di utilizzare crypto.createHash() invece.

L'algorithm dipende dagli algoritmi disponibili supportati dalla versione di OpenSSL sulla piattaforma. Gli esempi sono 'sha256', 'sha512', ecc. Nelle versioni recenti di OpenSSL, openssl list -digest-algorithms visualizzerà gli algoritmi di digest disponibili.

Esempio:

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

// Eseguire l'hashing di una stringa e restituire il risultato come stringa con codifica esadecimale.
const string = 'Node.js'
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string))

// Codificare una stringa con codifica base64 in un Buffer, eseguire l'hashing e restituire
// il risultato come 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'

// Eseguire l'hashing di una stringa e restituire il risultato come stringa con codifica esadecimale.
const string = 'Node.js'
// 10b3493287f831e81a438811a1ffba01f8cec4b7
console.log(crypto.hash('sha1', string))

// Codificare una stringa con codifica base64 in un Buffer, eseguire l'hashing e restituire
// il risultato come 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) ​

[Cronologia]

VersioneModifiche
v18.0.0Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v18.8.0, v16.18.0Il materiale di keying in input ora può essere di lunghezza zero.
v15.0.0Aggiunto in: v15.0.0

HKDF è una semplice funzione di derivazione della chiave definita in RFC 5869. Gli elementi ikm, salt e info forniti vengono utilizzati con il digest per derivare una chiave di keylen byte.

La funzione callback fornita viene chiamata con due argomenti: err e derivedKey. Se si verifica un errore durante la derivazione della chiave, err verrà impostato; altrimenti err sarà null. La derivedKey generata correttamente verrà passata alla callback come <ArrayBuffer>. Verrà generato un errore se uno qualsiasi degli argomenti di input specifica valori o tipi non validi.

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) ​

[Cronologia]

VersioneModifiche
v18.8.0, v16.18.0Il materiale di chiave in ingresso ora può essere di lunghezza zero.
v15.0.0Aggiunto in: v15.0.0

Fornisce una funzione di derivazione della chiave HKDF sincrona come definita in RFC 5869. Gli ikm, salt e info forniti vengono utilizzati con il digest per derivare una chiave di keylen byte.

La derivedKey generata con successo verrà restituita come <ArrayBuffer>.

Verrà generato un errore se uno degli argomenti di input specifica valori o tipi non validi o se la chiave derivata non può essere generata.

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) ​

[Cronologia]

VersioneModifiche
v18.0.0Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v15.0.0Gli argomenti password e salt possono anche essere istanze ArrayBuffer.
v14.0.0Il parametro iterations è ora limitato a valori positivi. Le versioni precedenti trattavano altri valori come uno.
v8.0.0Il parametro digest è ora sempre richiesto.
v6.0.0Chiamare questa funzione senza passare il parametro digest è ora deprecato e genererà un avviso.
v6.0.0La codifica predefinita per password se è una stringa è cambiata da binary a utf8.
v0.5.5Aggiunto in: v0.5.5

Fornisce un'implementazione asincrona della funzione di derivazione di chiavi basata su password 2 (PBKDF2). Un algoritmo di digest HMAC selezionato specificato da digest viene applicato per derivare una chiave della lunghezza in byte richiesta (keylen) dalla password, dal salt e da iterations.

La funzione callback fornita viene chiamata con due argomenti: err e derivedKey. Se si verifica un errore durante la derivazione della chiave, err verrà impostato; altrimenti err sarà null. Per impostazione predefinita, la derivedKey generata con successo verrà passata al callback come Buffer. Verrà generato un errore se uno qualsiasi degli argomenti di input specifica valori o tipi non validi.

L'argomento iterations deve essere un numero impostato il più alto possibile. Maggiore è il numero di iterazioni, più sicura sarà la chiave derivata, ma richiederà più tempo per essere completata.

Il salt dovrebbe essere il più unico possibile. Si raccomanda che un salt sia casuale e di almeno 16 byte di lunghezza. Consultare NIST SP 800-132 per i dettagli.

Quando si passano stringhe per password o salt, si prega di considerare le avvertenze quando si usano stringhe come input per le API crittografiche.

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'
})

Un array di funzioni di digest supportate può essere recuperato utilizzando crypto.getHashes().

Questa API utilizza il threadpool di libuv, che può avere implicazioni prestazionali sorprendenti e negative per alcune applicazioni; vedere la documentazione di UV_THREADPOOL_SIZE per ulteriori informazioni.

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

[Cronologia]

VersioneModifiche
v14.0.0Il parametro iterations è ora limitato a valori positivi. Le versioni precedenti trattavano altri valori come uno.
v6.0.0Chiamare questa funzione senza passare il parametro digest è ora deprecato ed emetterà un avviso.
v6.0.0La codifica predefinita per password se è una stringa è cambiata da binary a utf8.
v0.9.3Aggiunto in: v0.9.3

Fornisce un'implementazione sincrona della funzione di derivazione della chiave basata su password 2 (PBKDF2). Un algoritmo di digest HMAC selezionato specificato da digest viene applicato per derivare una chiave della lunghezza in byte richiesta (keylen) dalla password, salt e iterations.

Se si verifica un errore, verrà generato un Error, altrimenti la chiave derivata verrà restituita come Buffer.

L'argomento iterations deve essere un numero impostato il più alto possibile. Più alto è il numero di iterazioni, più sicura sarà la chiave derivata, ma ci vorrà più tempo per completare.

Il salt dovrebbe essere il più unico possibile. Si raccomanda che un salt sia casuale e lungo almeno 16 byte. Vedi NIST SP 800-132 per i dettagli.

Quando si passano stringhe per password o salt, si prega di considerare avvertenze quando si usano stringhe come input per le API crittografiche.

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'

Un array di funzioni di digest supportate può essere recuperato utilizzando crypto.getHashes().

crypto.privateDecrypt(privateKey, buffer) ​

[Cronologia]

VersioneModifiche
v21.6.2, v20.11.1, v18.19.1Il riempimento RSA_PKCS1_PADDING è stato disabilitato a meno che la build OpenSSL non supporti il rifiuto implicito.
v15.0.0Aggiunti stringa, ArrayBuffer e CryptoKey come tipi di chiave consentiti. Il oaepLabel può essere un ArrayBuffer. Il buffer può essere una stringa o un ArrayBuffer. Tutti i tipi che accettano buffer sono limitati a un massimo di 2 ** 31 - 1 byte.
v12.11.0Aggiunta l'opzione oaepLabel.
v12.9.0Aggiunta l'opzione oaepHash.
v11.6.0Questa funzione ora supporta gli oggetti chiave.
v0.11.14Aggiunto in: v0.11.14

Decrittografa buffer con privateKey. buffer è stato precedentemente crittografato utilizzando la chiave pubblica corrispondente, ad esempio utilizzando crypto.publicEncrypt().

Se privateKey non è un KeyObject, questa funzione si comporta come se privateKey fosse stato passato a crypto.createPrivateKey(). Se è un oggetto, è possibile passare la proprietà padding. In caso contrario, questa funzione utilizza RSA_PKCS1_OAEP_PADDING.

L'utilizzo di crypto.constants.RSA_PKCS1_PADDING in crypto.privateDecrypt() richiede che OpenSSL supporti il rifiuto implicito (rsa_pkcs1_implicit_rejection). Se la versione di OpenSSL utilizzata da Node.js non supporta questa funzionalità, il tentativo di utilizzare RSA_PKCS1_PADDING non riuscirà.

crypto.privateEncrypt(privateKey, buffer) ​

[Cronologia]

VersioneModifiche
v15.0.0Aggiunti stringa, ArrayBuffer e CryptoKey come tipi di chiave ammissibili. La passphrase può essere un ArrayBuffer. Il buffer può essere una stringa o un ArrayBuffer. Tutti i tipi che accettano buffer sono limitati a un massimo di 2 ** 31 - 1 byte.
v11.6.0Questa funzione ora supporta gli oggetti chiave.
v1.1.0Aggiunto in: v1.1.0

Crittografa il buffer con privateKey. I dati restituiti possono essere decrittografati utilizzando la chiave pubblica corrispondente, ad esempio utilizzando crypto.publicDecrypt().

Se privateKey non è un KeyObject, questa funzione si comporta come se privateKey fosse stata passata a crypto.createPrivateKey(). Se è un oggetto, è possibile passare la proprietà padding. Altrimenti, questa funzione utilizza RSA_PKCS1_PADDING.

crypto.publicDecrypt(key, buffer) ​

[Cronologia]

VersioneModifiche
v15.0.0Aggiunti stringa, ArrayBuffer e CryptoKey come tipi di chiave ammissibili. La passphrase può essere un ArrayBuffer. Il buffer può essere una stringa o un ArrayBuffer. Tutti i tipi che accettano buffer sono limitati a un massimo di 2 ** 31 - 1 byte.
v11.6.0Questa funzione ora supporta gli oggetti chiave.
v1.1.0Aggiunto in: v1.1.0

Decrittografa buffer con key. buffer è stato precedentemente crittografato usando la corrispondente chiave privata, ad esempio usando crypto.privateEncrypt().

Se key non è un KeyObject, questa funzione si comporta come se key fosse stato passato a crypto.createPublicKey(). Se è un oggetto, è possibile passare la proprietà padding. Altrimenti, questa funzione usa RSA_PKCS1_PADDING.

Poiché le chiavi pubbliche RSA possono essere derivate dalle chiavi private, è possibile passare una chiave privata invece di una chiave pubblica.

crypto.publicEncrypt(key, buffer) ​

[Cronologia]

VersioneModifiche
v15.0.0Aggiunti string, ArrayBuffer e CryptoKey come tipi di chiave consentiti. oaepLabel e passphrase possono essere ArrayBuffer. Il buffer può essere una stringa o un ArrayBuffer. Tutti i tipi che accettano buffer sono limitati a un massimo di 2 ** 31 - 1 byte.
v12.11.0Aggiunta l'opzione oaepLabel.
v12.9.0Aggiunta l'opzione oaepHash.
v11.6.0Questa funzione ora supporta oggetti chiave.
v0.11.14Aggiunto in: v0.11.14

Crittografa il contenuto di buffer con key e restituisce un nuovo Buffer con il contenuto crittografato. I dati restituiti possono essere decrittografati usando la chiave privata corrispondente, per esempio usando crypto.privateDecrypt().

Se key non è un KeyObject, questa funzione si comporta come se key fosse stata passata a crypto.createPublicKey(). Se è un oggetto, la proprietà padding può essere passata. Altrimenti, questa funzione usa RSA_PKCS1_OAEP_PADDING.

Poiché le chiavi pubbliche RSA possono essere derivate da chiavi private, una chiave privata può essere passata invece di una chiave pubblica.

crypto.randomBytes(size[, callback]) ​

[Cronologia]

VersioneModifiche
v18.0.0Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v9.0.0Il passaggio di null come argomento callback ora genera ERR_INVALID_CALLBACK.
v0.5.8Aggiunto in: v0.5.8

Genera dati pseudocasuali crittograficamente robusti. L'argomento size è un numero che indica il numero di byte da generare.

Se viene fornita una funzione callback, i byte vengono generati in modo asincrono e la funzione callback viene richiamata con due argomenti: err e buf. Se si verifica un errore, err sarà un oggetto Error; altrimenti è null. L'argomento buf è un Buffer contenente i byte generati.

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

randomBytes(256, (err, buf) => {
  if (err) throw err
  console.log(`${buf.length} byte di dati casuali: ${buf.toString('hex')}`)
})
js
// Asincrono
const { randomBytes } = require('node:crypto')

randomBytes(256, (err, buf) => {
  if (err) throw err
  console.log(`${buf.length} byte di dati casuali: ${buf.toString('hex')}`)
})

Se la funzione callback non viene fornita, i byte casuali vengono generati in modo sincrono e restituiti come Buffer. Verrà generato un errore se si verifica un problema durante la generazione dei byte.

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

const buf = randomBytes(256)
console.log(`${buf.length} byte di dati casuali: ${buf.toString('hex')}`)
js
// Sincrono
const { randomBytes } = require('node:crypto')

const buf = randomBytes(256)
console.log(`${buf.length} byte di dati casuali: ${buf.toString('hex')}`)

Il metodo crypto.randomBytes() non verrà completato finché non sarà disponibile una quantità sufficiente di entropia. Normalmente, ciò non dovrebbe mai richiedere più di qualche millisecondo. L'unico momento in cui la generazione dei byte casuali potrebbe bloccare per un periodo di tempo più lungo è subito dopo l'avvio, quando l'intero sistema ha ancora poca entropia.

Questa API utilizza il threadpool di libuv, che può avere implicazioni prestazionali sorprendenti e negative per alcune applicazioni; consultare la documentazione di UV_THREADPOOL_SIZE per maggiori informazioni.

La versione asincrona di crypto.randomBytes() viene eseguita in una singola richiesta del threadpool. Per ridurre al minimo la variazione della lunghezza delle attività del threadpool, partizionare le grandi richieste randomBytes quando ciò viene fatto come parte dell'adempimento di una richiesta client.

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

[Cronologia]

VersioneModifiche
v18.0.0Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE anziché ERR_INVALID_CALLBACK.
v9.0.0L'argomento buffer può essere qualsiasi TypedArray o DataView.
v7.10.0, v6.13.0Aggiunto in: v7.10.0, v6.13.0

Questa funzione è simile a crypto.randomBytes() ma richiede che il primo argomento sia un Buffer che verrà riempito. Richiede anche che venga passata una callback.

Se la funzione callback non viene fornita, verrà generato un errore.

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'))
})

// Quanto sopra equivale a quanto segue:
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'))
})

// Quanto sopra equivale a quanto segue:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err
  console.log(buf.toString('hex'))
})

Qualsiasi istanza di ArrayBuffer, TypedArray o DataView può essere passata come buffer.

Sebbene ciò includa istanze di Float32Array e Float64Array, questa funzione non dovrebbe essere utilizzata per generare numeri in virgola mobile casuali. Il risultato può contenere +Infinity, -Infinity e NaN, e anche se l'array contiene solo numeri finiti, non vengono estratti da una distribuzione casuale uniforme e non hanno limiti inferiori o superiori significativi.

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'))
})

Questa API utilizza il threadpool di libuv, che può avere implicazioni sorprendenti e negative sulle prestazioni per alcune applicazioni; consulta la documentazione UV_THREADPOOL_SIZE per maggiori informazioni.

La versione asincrona di crypto.randomFill() viene eseguita in un'unica richiesta del threadpool. Per ridurre al minimo la variazione della lunghezza delle attività del threadpool, partiziona le richieste randomFill di grandi dimensioni quando lo fai nell'ambito dell'adempimento di una richiesta del client.

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

[Cronologia]

VersioneModifiche
v9.0.0L'argomento buffer può essere qualsiasi TypedArray o DataView.
v7.10.0, v6.13.0Aggiunto in: v7.10.0, v6.13.0

Versione sincrona di 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'))

// Quanto sopra è equivalente a quanto segue:
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'))

// Quanto sopra è equivalente a quanto segue:
randomFillSync(buf, 5, 5)
console.log(buf.toString('hex'))

Qualsiasi istanza di ArrayBuffer, TypedArray o DataView può essere passata come buffer.

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]) ​

[Cronologia]

VersioneModifiche
v18.0.0Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v14.10.0, v12.19.0Aggiunto in: v14.10.0, v12.19.0
  • min <integer> Inizio dell'intervallo casuale (incluso). Predefinito: 0.
  • max <integer> Fine dell'intervallo casuale (escluso).
  • callback <Function> function(err, n) {}.

Restituisce un intero casuale n tale che min \<= n \< max. Questa implementazione evita bias modulo.

L'intervallo (max - min) deve essere inferiore a 2. min e max devono essere interi sicuri.

Se la funzione callback non viene fornita, l'intero casuale viene generato in modo sincrono.

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

randomInt(3, (err, n) => {
  if (err) throw err
  console.log(`Numero casuale scelto tra (0, 1, 2): ${n}`)
})
js
// Asincrono
const { randomInt } = require('node:crypto')

randomInt(3, (err, n) => {
  if (err) throw err
  console.log(`Numero casuale scelto tra (0, 1, 2): ${n}`)
})
js
// Sincrono
const { randomInt } = await import('node:crypto')

const n = randomInt(3)
console.log(`Numero casuale scelto tra (0, 1, 2): ${n}`)
js
// Sincrono
const { randomInt } = require('node:crypto')

const n = randomInt(3)
console.log(`Numero casuale scelto tra (0, 1, 2): ${n}`)
js
// Con argomento `min`
const { randomInt } = await import('node:crypto')

const n = randomInt(1, 7)
console.log(`Il dado è uscito: ${n}`)
js
// Con argomento `min`
const { randomInt } = require('node:crypto')

const n = randomInt(1, 7)
console.log(`Il dado è uscito: ${n}`)

crypto.randomUUID([options]) ​

Aggiunto in: v15.6.0, v14.17.0

  • options <Object>

    • disableEntropyCache <boolean> Per impostazione predefinita, per migliorare le prestazioni, Node.js genera e memorizza nella cache una quantità sufficiente di dati casuali per generare fino a 128 UUID casuali. Per generare un UUID senza utilizzare la cache, impostare disableEntropyCache su true. Predefinito: false.

  • Restituisce: <string>

Genera un UUID casuale RFC 4122 versione 4. L'UUID viene generato utilizzando un generatore di numeri pseudocasuali crittografico.

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

[Cronologia]

VersioneModifiche
v18.0.0Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE anziché ERR_INVALID_CALLBACK.
v15.0.0Gli argomenti password e salt possono essere anche istanze di ArrayBuffer.
v12.8.0, v10.17.0Il valore maxmem può ora essere un qualsiasi numero intero sicuro.
v10.9.0Sono stati aggiunti i nomi delle opzioni cost, blockSize e parallelization.
v10.5.0Aggiunto in: v10.5.0

Fornisce un'implementazione asincrona di scrypt. Scrypt è una funzione di derivazione della chiave basata su password, progettata per essere costosa in termini di calcolo e memoria al fine di rendere gli attacchi di forza bruta non redditizi.

Il salt deve essere il più univoco possibile. Si raccomanda che un salt sia casuale e di almeno 16 byte di lunghezza. Vedere NIST SP 800-132 per i dettagli.

Quando si passano stringhe per password o salt, si prega di considerare le avvertenze quando si utilizzano stringhe come input per le API crittografiche.

La funzione callback viene chiamata con due argomenti: err e derivedKey. err è un oggetto eccezione quando la derivazione della chiave fallisce, altrimenti err è null. derivedKey viene passato alla callback come un Buffer.

Un'eccezione viene generata quando uno qualsiasi degli argomenti di input specifica valori o tipi non validi.

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

// Utilizzo delle impostazioni predefinite di fabbrica.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})
// Utilizzo di un parametro N personalizzato. Deve essere una potenza di due.
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')

// Utilizzo delle impostazioni predefinite di fabbrica.
scrypt('password', 'salt', 64, (err, derivedKey) => {
  if (err) throw err
  console.log(derivedKey.toString('hex')) // '3745e48...08d59ae'
})
// Utilizzo di un parametro N personalizzato. Deve essere una potenza di due.
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]) ​

[Cronologia]

VersioneModifiche
v12.8.0, v10.17.0Il valore maxmem può ora essere qualsiasi numero intero sicuro.
v10.9.0Sono stati aggiunti i nomi delle opzioni cost, blockSize e parallelization.
v10.5.0Aggiunto in: v10.5.0

Fornisce un'implementazione sincrona di scrypt. Scrypt è una funzione di derivazione della chiave basata su password progettata per essere costosa dal punto di vista computazionale e della memoria al fine di rendere gli attacchi di forza bruta non redditizi.

Il salt dovrebbe essere il più unico possibile. Si consiglia che un salt sia casuale e lungo almeno 16 byte. Vedere NIST SP 800-132 per i dettagli.

Quando si passano stringhe per password o salt, si prega di considerare avvertenze quando si utilizzano stringhe come input per le API crittografiche.

Viene generata un'eccezione quando la derivazione della chiave fallisce, altrimenti la chiave derivata viene restituita come Buffer.

Viene generata un'eccezione quando uno qualsiasi degli argomenti di input specifica valori o tipi non validi.

js
const { scryptSync } = await import('node:crypto')
// Utilizzo delle impostazioni predefinite di fabbrica.

const key1 = scryptSync('password', 'salt', 64)
console.log(key1.toString('hex')) // '3745e48...08d59ae'
// Utilizzo di un parametro N personalizzato. Deve essere una potenza di due.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 })
console.log(key2.toString('hex')) // '3745e48...aa39b34'
js
const { scryptSync } = require('node:crypto')
// Utilizzo delle impostazioni predefinite di fabbrica.

const key1 = scryptSync('password', 'salt', 64)
console.log(key1.toString('hex')) // '3745e48...08d59ae'
// Utilizzo di un parametro N personalizzato. Deve essere una potenza di due.
const key2 = scryptSync('password', 'salt', 64, { N: 1024 })
console.log(key2.toString('hex')) // '3745e48...aa39b34'

crypto.secureHeapUsed() ​

Aggiunto in: v15.6.0

  • Restituisce: <Object>
    • total <number> La dimensione totale dell'heap sicuro allocata come specificato utilizzando il flag della riga di comando --secure-heap=n.
    • min <number> L'allocazione minima dall'heap sicuro come specificato utilizzando il flag della riga di comando --secure-heap-min.
    • used <number> Il numero totale di byte attualmente allocati dall'heap sicuro.
    • utilization <number> Il rapporto calcolato tra i byte used e total allocati.

crypto.setEngine(engine[, flags]) ​

[Cronologia]

VersioneModifiche
v22.4.0, v20.16.0Il supporto per i motori personalizzati in OpenSSL 3 è obsoleto.
v0.11.11Aggiunto in: v0.11.11

Carica e imposta il engine per alcune o tutte le funzioni OpenSSL (selezionate da flag). Il supporto per i motori personalizzati in OpenSSL è obsoleto a partire da OpenSSL 3.

engine può essere un ID o un percorso alla libreria condivisa del motore.

L'argomento opzionale flags utilizza ENGINE_METHOD_ALL per impostazione predefinita. Il flags è un campo di bit che assume uno o un mix dei seguenti flag (definiti in crypto.constants):

  • 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) ​

Aggiunto in: v10.0.0

  • bool <boolean> true per abilitare la modalità FIPS.

Abilita il provider di crittografia conforme a FIPS in una build Node.js abilitata per FIPS. Restituisce un errore se la modalità FIPS non è disponibile.

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

[Cronologia]

VersioneModifiche
v18.0.0Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v15.12.0Aggiunto l'argomento callback opzionale.
v13.2.0, v12.16.0Questa funzione ora supporta le firme IEEE-P1363 DSA ed ECDSA.
v12.0.0Aggiunto in: v12.0.0

Calcola e restituisce la firma per data utilizzando la chiave privata e l'algoritmo forniti. Se algorithm è null o undefined, l'algoritmo dipende dal tipo di chiave (in particolare Ed25519 e Ed448).

Se key non è un KeyObject, questa funzione si comporta come se key fosse stata passata a crypto.createPrivateKey(). Se è un oggetto, è possibile passare le seguenti proprietà aggiuntive:

  • dsaEncoding <stringa> Per DSA ed ECDSA, questa opzione specifica il formato della firma generata. Può essere uno dei seguenti:

    • 'der' (predefinito): Struttura di firma ASN.1 con codifica DER che codifica (r, s).
    • 'ieee-p1363': Formato di firma r || s come proposto in IEEE-P1363.

  • padding <numero> Valore di padding opzionale per RSA, uno dei seguenti:

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

RSA_PKCS1_PSS_PADDING userà MGF1 con la stessa funzione hash utilizzata per firmare il messaggio come specificato nella sezione 3.1 di RFC 4055.

  • saltLength <numero> Lunghezza del salt quando il padding è RSA_PKCS1_PSS_PADDING. Il valore speciale crypto.constants.RSA_PSS_SALTLEN_DIGEST imposta la lunghezza del salt alla dimensione del digest, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (predefinito) la imposta al valore massimo consentito.

Se la funzione callback viene fornita, questa funzione usa il threadpool di libuv.

crypto.subtle ​

Aggiunto in: v17.4.0

Un alias conveniente per crypto.webcrypto.subtle.

crypto.timingSafeEqual(a, b) ​

[Cronologia]

VersioneCambiamenti
v15.0.0Gli argomenti a e b possono anche essere ArrayBuffer.
v6.6.0Aggiunto in: v6.6.0

Questa funzione confronta i byte sottostanti che rappresentano le istanze ArrayBuffer, TypedArray o DataView fornite utilizzando un algoritmo a tempo costante.

Questa funzione non rivela informazioni temporali che consentirebbero a un utente malintenzionato di indovinare uno dei valori. Ciò è adatto per confrontare i digest HMAC o valori segreti come i cookie di autenticazione o gli url di capacità.

a e b devono essere entrambi Buffer, TypedArray o DataView e devono avere la stessa lunghezza in byte. Viene generato un errore se a e b hanno lunghezze di byte diverse.

Se almeno uno tra a e b è un TypedArray con più di un byte per voce, come Uint16Array, il risultato verrà calcolato utilizzando l'ordine dei byte della piattaforma.

Quando entrambi gli input sono Float32Array o Float64Array, questa funzione potrebbe restituire risultati inattesi a causa della codifica IEEE 754 dei numeri in virgola mobile. In particolare, né x === y né Object.is(x, y) implica che le rappresentazioni in byte di due numeri in virgola mobile x e y siano uguali.

L'uso di crypto.timingSafeEqual non garantisce che il codice circostante sia a prova di timing. È necessario prestare attenzione per garantire che il codice circostante non introduca vulnerabilità di timing.

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

[Cronologia]

VersioneModifiche
v18.0.0Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v15.12.0Aggiunto l'argomento callback opzionale.
v15.0.0Gli argomenti data, key e signature possono essere anche ArrayBuffer.
v13.2.0, v12.16.0Questa funzione ora supporta le firme DSA ed ECDSA IEEE-P1363.
v12.0.0Aggiunto in: v12.0.0

Verifica la firma data per data usando la chiave e l'algoritmo dati. Se algorithm è null o undefined, l'algoritmo dipende dal tipo di chiave (specialmente Ed25519 e Ed448).

Se key non è un KeyObject, questa funzione si comporta come se key fosse stato passato a crypto.createPublicKey(). Se è un oggetto, si possono passare le seguenti proprietà aggiuntive:

  • dsaEncoding <string> Per DSA ed ECDSA, questa opzione specifica il formato della firma. Può essere uno dei seguenti:

    • 'der' (predefinito): Struttura della firma ASN.1 con codifica DER che codifica (r, s).
    • 'ieee-p1363': Formato della firma r || s come proposto in IEEE-P1363.

  • padding <integer> Valore di padding opzionale per RSA, uno dei seguenti:

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

RSA_PKCS1_PSS_PADDING userà MGF1 con la stessa funzione hash usata per firmare il messaggio come specificato nella sezione 3.1 di RFC 4055.

  • saltLength <integer> Lunghezza del salt quando il padding è RSA_PKCS1_PSS_PADDING. Il valore speciale crypto.constants.RSA_PSS_SALTLEN_DIGEST imposta la lunghezza del salt alla dimensione del digest, crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN (predefinito) lo imposta al valore massimo consentito.

L'argomento signature è la firma precedentemente calcolata per data.

Poiché le chiavi pubbliche possono essere derivate da chiavi private, si può passare una chiave privata o una chiave pubblica per key.

Se viene fornita la funzione callback, questa funzione usa il threadpool di libuv.

crypto.webcrypto ​

Aggiunto in: v15.0.0

Tipo: <Crypto> Un'implementazione dello standard Web Crypto API.

Vedere la documentazione Web Crypto API per i dettagli.

Note ​

Utilizzo di stringhe come input per le API crittografiche ​

Per ragioni storiche, molte API crittografiche fornite da Node.js accettano stringhe come input quando l'algoritmo crittografico sottostante opera su sequenze di byte. Questi casi includono testi in chiaro, testi cifrati, chiavi simmetriche, vettori di inizializzazione, password, salt, tag di autenticazione e dati autenticati aggiuntivi.

Quando si passano stringhe alle API crittografiche, considerare i seguenti fattori.

  • Non tutte le sequenze di byte sono stringhe UTF-8 valide. Pertanto, quando una sequenza di byte di lunghezza n è derivata da una stringa, la sua entropia è generalmente inferiore all'entropia di una sequenza di n byte casuale o pseudocasuale. Ad esempio, nessuna stringa UTF-8 risulterà nella sequenza di byte c0 af. Le chiavi segrete dovrebbero essere quasi esclusivamente sequenze di byte casuali o pseudocasuali.
  • Allo stesso modo, quando si convertono sequenze di byte casuali o pseudocasuali in stringhe UTF-8, le sottosequenze che non rappresentano punti di codice validi possono essere sostituite dal carattere di sostituzione Unicode (U+FFFD). La rappresentazione in byte della stringa Unicode risultante potrebbe, pertanto, non essere uguale alla sequenza di byte da cui è stata creata la stringa. Gli output di cifrari, funzioni hash, algoritmi di firma e funzioni di derivazione della chiave sono sequenze di byte pseudocasuali e non dovrebbero essere usati come stringhe Unicode.
  • Quando le stringhe vengono ottenute dall'input utente, alcuni caratteri Unicode possono essere rappresentati in modi multipli equivalenti che si traducono in sequenze di byte diverse. Ad esempio, quando si passa una password utente a una funzione di derivazione della chiave, come PBKDF2 o scrypt, il risultato della funzione di derivazione della chiave dipende dal fatto che la stringa utilizzi caratteri composti o scomposti. Node.js non normalizza le rappresentazioni dei caratteri. Gli sviluppatori dovrebbero considerare l'utilizzo di String.prototype.normalize() sugli input utente prima di passarli alle API crittografiche.

API legacy di stream (precedente a Node.js 0.10) ​

Il modulo Crypto è stato aggiunto a Node.js prima che esistesse il concetto di un'API Stream unificata e prima che esistessero gli oggetti Buffer per la gestione dei dati binari. Pertanto, molte classi crypto hanno metodi che in genere non si trovano in altre classi Node.js che implementano l'API stream (ad esempio update(), final() o digest()). Inoltre, molti metodi accettavano e restituivano stringhe codificate 'latin1' per impostazione predefinita anziché Buffer. Questa impostazione predefinita è stata modificata dopo Node.js v0.8 per utilizzare gli oggetti Buffer per impostazione predefinita.

Supporto per algoritmi deboli o compromessi ​

Il modulo node:crypto supporta ancora alcuni algoritmi che sono già compromessi e il cui uso non è raccomandato. L'API consente anche l'uso di cifrari e hash con una dimensione di chiave piccola che sono troppo deboli per un uso sicuro.

Gli utenti dovrebbero assumersi la piena responsabilità della selezione dell'algoritmo crittografico e della dimensione della chiave in base ai loro requisiti di sicurezza.

Sulla base delle raccomandazioni di NIST SP 800-131A:

  • MD5 e SHA-1 non sono più accettabili laddove è richiesta la resistenza alle collisioni, come nelle firme digitali.
  • Si raccomanda che la chiave utilizzata con gli algoritmi RSA, DSA e DH abbia almeno 2048 bit e quella della curva di ECDSA e ECDH almeno 224 bit, per essere sicura da usare per diversi anni.
  • I gruppi DH di modp1, modp2 e modp5 hanno una dimensione di chiave inferiore a 2048 bit e non sono raccomandati.

Vedi il riferimento per altre raccomandazioni e dettagli.

Alcuni algoritmi che presentano note debolezze e sono di scarsa rilevanza nella pratica sono disponibili solo tramite il provider legacy, che non è abilitato per impostazione predefinita.

Modalità CCM ​

CCM è uno degli algoritmi AEAD supportati. Le applicazioni che utilizzano questa modalità devono attenersi a determinate restrizioni quando utilizzano l'API di cifratura:

  • La lunghezza del tag di autenticazione deve essere specificata durante la creazione del cifrario impostando l'opzione authTagLength e deve essere uno dei valori 4, 6, 8, 10, 12, 14 o 16 byte.
  • La lunghezza del vettore di inizializzazione (nonce) N deve essere compresa tra 7 e 13 byte (7 ≤ N ≤ 13).
  • La lunghezza del testo in chiaro è limitata a 2 ** (8 * (15 - N)) byte.
  • Durante la decrittazione, il tag di autenticazione deve essere impostato tramite setAuthTag() prima di chiamare update(). In caso contrario, la decrittazione fallirà e final() genererà un errore in conformità con la sezione 2.6 di RFC 3610.
  • L'utilizzo di metodi di stream come write(data), end(data) o pipe() in modalità CCM potrebbe fallire poiché CCM non può gestire più di un blocco di dati per istanza.
  • Quando si passano dati autenticati aggiuntivi (AAD), la lunghezza del messaggio effettivo in byte deve essere passata a setAAD() tramite l'opzione plaintextLength. Molte librerie crittografiche includono il tag di autenticazione nel testo cifrato, il che significa che producono testi cifrati della lunghezza plaintextLength + authTagLength. Node.js non include il tag di autenticazione, quindi la lunghezza del testo cifrato è sempre plaintextLength. Ciò non è necessario se non viene utilizzato alcun AAD.
  • Poiché CCM elabora l'intero messaggio in una sola volta, update() deve essere chiamata esattamente una volta.
  • Anche se chiamare update() è sufficiente per crittografare/decrittografare il messaggio, le applicazioni devono chiamare final() per calcolare o verificare il tag di autenticazione.
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()

// Ora trasmetti { 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('Autenticazione non riuscita!', { 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()

// Ora trasmetti { 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('Autenticazione non riuscita!', { cause: err })
}

console.log(receivedPlaintext)

Modalità FIPS ​

Quando si utilizza OpenSSL 3, Node.js supporta FIPS 140-2 se utilizzato con un provider OpenSSL 3 appropriato, come il provider FIPS di OpenSSL 3 che può essere installato seguendo le istruzioni nel file README FIPS di OpenSSL.

Per il supporto FIPS in Node.js è necessario:

  • Un provider FIPS di OpenSSL 3 installato correttamente.
  • Un file di configurazione del modulo FIPS di OpenSSL 3.
  • Un file di configurazione di OpenSSL 3 che faccia riferimento al file di configurazione del modulo FIPS.

Node.js dovrà essere configurato con un file di configurazione OpenSSL che punti al provider FIPS. Un file di configurazione di esempio è simile a questo:

text
nodejs_conf = nodejs_init

.include /<percorso assoluto>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect

[provider_sect]
default = default_sect
# Il nome della sezione fips deve corrispondere al nome della sezione all'interno del {#the-fips-section-name-should-match-the-section-name-inside-the}
# file fipsmodule.cnf incluso.
fips = fips_sect

[default_sect]
activate = 1

dove fipsmodule.cnf è il file di configurazione del modulo FIPS generato dal passaggio di installazione del provider FIPS:

bash
openssl fipsinstall

Imposta la variabile d'ambiente OPENSSL_CONF in modo che punti al tuo file di configurazione e OPENSSL_MODULES alla posizione della libreria dinamica del provider FIPS. Ad esempio:

bash
export OPENSSL_CONF=/<percorso del file di configurazione>/nodejs.cnf
export OPENSSL_MODULES=/<percorso della libreria openssl>/ossl-modules

La modalità FIPS può quindi essere abilitata in Node.js in due modi:

  • Avviando Node.js con i flag della riga di comando --enable-fips o --force-fips.
  • Chiamando programmaticamente crypto.setFips(true).

Opzionalmente, la modalità FIPS può essere abilitata in Node.js tramite il file di configurazione di OpenSSL. Ad esempio:

text
nodejs_conf = nodejs_init

.include /<percorso assoluto>/fipsmodule.cnf

[nodejs_init]
providers = provider_sect
alg_section = algorithm_sect

[provider_sect]
default = default_sect
# Il nome della sezione fips deve corrispondere al nome della sezione all'interno del {#included-fipsmodulecnf}
# file fipsmodule.cnf incluso.
fips = fips_sect

[default_sect]
activate = 1

[algorithm_sect]
default_properties = fips=yes

Costanti crittografiche ​

Le seguenti costanti esportate da crypto.constants si applicano a vari utilizzi dei moduli node:crypto, node:tls e node:https e sono generalmente specifiche per OpenSSL.

Opzioni OpenSSL ​

Vedere l'elenco dei flag SSL OP per i dettagli.

CostanteDescrizione
SSL_OP_ALLApplica diverse soluzioni per bug all'interno di OpenSSL. Vedere https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html per i dettagli.
SSL_OP_ALLOW_NO_DHE_KEXIstruisce OpenSSL a consentire una modalità di scambio di chiavi non basata su [EC]DHE per TLS v1.3
SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATIONConsente la rinegoziazione legacy non sicura tra OpenSSL e client o server non patchati. Vedere https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html.
SSL_OP_CIPHER_SERVER_PREFERENCETenta di utilizzare le preferenze del server invece di quelle del client quando si seleziona una cifra. Il comportamento dipende dalla versione del protocollo. Vedere https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html.
SSL_OP_CISCO_ANYCONNECTIstruisce OpenSSL a utilizzare l'identificatore di versione Cisco di DTLS_BAD_VER.
SSL_OP_COOKIE_EXCHANGEIstruisce OpenSSL ad attivare lo scambio di cookie.
SSL_OP_CRYPTOPRO_TLSEXT_BUGIstruisce OpenSSL ad aggiungere l'estensione server-hello da una versione precedente della bozza di cryptopro.
SSL_OP_DONT_INSERT_EMPTY_FRAGMENTSIstruisce OpenSSL a disabilitare una soluzione per una vulnerabilità SSL 3.0/TLS 1.0 aggiunta in OpenSSL 0.9.6d.
SSL_OP_LEGACY_SERVER_CONNECTConsente la connessione iniziale a server che non supportano RI.
SSL_OP_NO_COMPRESSIONIstruisce OpenSSL a disabilitare il supporto per la compressione SSL/TLS.
SSL_OP_NO_ENCRYPT_THEN_MACIstruisce OpenSSL a disabilitare encrypt-then-MAC.
SSL_OP_NO_QUERY_MTU
SSL_OP_NO_RENEGOTIATIONIstruisce OpenSSL a disabilitare la rinegoziazione.
SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATIONIstruisce OpenSSL ad avviare sempre una nuova sessione durante l'esecuzione della rinegoziazione.
SSL_OP_NO_SSLv2Istruisce OpenSSL a disattivare SSL v2
SSL_OP_NO_SSLv3Istruisce OpenSSL a disattivare SSL v3
SSL_OP_NO_TICKETIstruisce OpenSSL a disabilitare l'uso dei ticket RFC4507bis.
SSL_OP_NO_TLSv1Istruisce OpenSSL a disattivare TLS v1
SSL_OP_NO_TLSv1_1Istruisce OpenSSL a disattivare TLS v1.1
SSL_OP_NO_TLSv1_2Istruisce OpenSSL a disattivare TLS v1.2
SSL_OP_NO_TLSv1_3Istruisce OpenSSL a disattivare TLS v1.3
SSL_OP_PRIORITIZE_CHACHAIstruisce il server OpenSSL a dare priorità a ChaCha20-Poly1305 quando lo fa il client. Questa opzione non ha effetto se SSL_OP_CIPHER_SERVER_PREFERENCE non è abilitata.
SSL_OP_TLS_ROLLBACK_BUGIstruisce OpenSSL a disabilitare il rilevamento di attacchi di rollback della versione.

Costanti del motore OpenSSL ​

CostanteDescrizione
ENGINE_METHOD_RSALimita l'uso del motore a RSA
ENGINE_METHOD_DSALimita l'uso del motore a DSA
ENGINE_METHOD_DHLimita l'uso del motore a DH
ENGINE_METHOD_RANDLimita l'uso del motore a RAND
ENGINE_METHOD_ECLimita l'uso del motore a EC
ENGINE_METHOD_CIPHERSLimita l'uso del motore a CIPHERS
ENGINE_METHOD_DIGESTSLimita l'uso del motore a DIGESTS
ENGINE_METHOD_PKEY_METHSLimita l'uso del motore a PKEY_METHS
ENGINE_METHOD_PKEY_ASN1_METHSLimita l'uso del motore a PKEY_ASN1_METHS
ENGINE_METHOD_ALL
ENGINE_METHOD_NONE

Altre costanti OpenSSL ​

CostanteDescrizione
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_DIGESTImposta la lunghezza del sale per RSA_PKCS1_PSS_PADDING alla dimensione del digest durante la firma o la verifica.
RSA_PSS_SALTLEN_MAX_SIGNImposta la lunghezza del sale per RSA_PKCS1_PSS_PADDING al valore massimo consentito durante la firma dei dati.
RSA_PSS_SALTLEN_AUTOFa sì che la lunghezza del sale per RSA_PKCS1_PSS_PADDING venga determinata automaticamente durante la verifica di una firma.
POINT_CONVERSION_COMPRESSED
POINT_CONVERSION_UNCOMPRESSED
POINT_CONVERSION_HYBRID

Costanti crypto di Node.js ​

CostanteDescrizione
defaultCoreCipherListSpecifica l'elenco di cifrari predefinito integrato utilizzato da Node.js.
defaultCipherListSpecifica l'elenco di cifrari predefinito attivo utilizzato dal processo Node.js corrente.