TLS (SSL)

[Stabile: 2 - Stabile]

Stabile: 2 Stabilità: 2 - Stabile

Codice Sorgente: lib/tls.js

Il modulo node:tls fornisce un'implementazione dei protocolli Transport Layer Security (TLS) e Secure Socket Layer (SSL) basata su OpenSSL. Il modulo è accessibile tramite:

ESM

import tls from 'node:tls'

CJS

const tls = require('node:tls')

Determinazione della non disponibilità del supporto crittografico

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

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

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

Quando si utilizza la parola chiave import ESM lessicale, 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 usa ESM, se c'è la possibilità che il codice venga eseguito su una build di Node.js in cui il supporto crittografico non è abilitato, si consideri l'utilizzo della funzione import() invece della parola chiave import lessicale:

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

Concetti TLS/SSL

TLS/SSL è un insieme di protocolli che si basano su un'infrastruttura a chiave pubblica (PKI) per abilitare una comunicazione sicura tra un client e un server. Nella maggior parte dei casi comuni, ogni server deve avere una chiave privata.

Le chiavi private possono essere generate in diversi modi. L'esempio seguente illustra l'utilizzo dell'interfaccia a riga di comando di OpenSSL per generare una chiave privata RSA a 2048 bit:

openssl genrsa -out ryans-key.pem 2048

Con TLS/SSL, tutti i server (e alcuni client) devono avere un certificato. I certificati sono chiavi pubbliche che corrispondono a una chiave privata e che sono firmati digitalmente da un'Autorità di Certificazione o dal proprietario della chiave privata (questi certificati sono denominati "autofirmati"). Il primo passo per ottenere un certificato è quello di creare un file Certificate Signing Request (CSR).

L'interfaccia a riga di comando di OpenSSL può essere utilizzata per generare un CSR per una chiave privata:

openssl req -new -sha256 -key ryans-key.pem -out ryans-csr.pem

Una volta generato il file CSR, può essere inviato a un'Autorità di Certificazione per la firma o utilizzato per generare un certificato autofirmato.

La creazione di un certificato autofirmato utilizzando l'interfaccia a riga di comando di OpenSSL è illustrata nell'esempio seguente:

openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem

Una volta generato il certificato, può essere utilizzato per generare un file .pfx o .p12:

openssl pkcs12 -export -in ryans-cert.pem -inkey ryans-key.pem \
      -certfile ca-cert.pem -out ryans.pfx

Dove:

• in: è il certificato firmato
• inkey: è la chiave privata associata
• certfile: è una concatenazione di tutti i certificati dell'Autorità di Certificazione (CA) in un singolo file, ad esempio cat ca1-cert.pem ca2-cert.pem \> ca-cert.pem

Segretezza in avanti perfetta

Il termine segretezza in avanti o segretezza in avanti perfetta descrive una caratteristica dei metodi di accordo sulle chiavi (cioè, di scambio chiavi). Cioè, le chiavi del server e del client vengono utilizzate per negoziare nuove chiavi temporanee che vengono utilizzate specificamente e solo per la sessione di comunicazione corrente. In pratica, ciò significa che anche se la chiave privata del server viene compromessa, la comunicazione può essere decifrata dagli intercettatori solo se l'attaccante riesce ad ottenere la coppia di chiavi generata specificamente per la sessione.

La segretezza in avanti perfetta viene ottenuta generando casualmente una coppia di chiavi per l'accordo sulle chiavi ad ogni handshake TLS/SSL (a differenza dell'utilizzo della stessa chiave per tutte le sessioni). I metodi che implementano questa tecnica sono chiamati "effimeri".

Attualmente vengono comunemente utilizzati due metodi per ottenere la segretezza in avanti perfetta (si noti il carattere "E" aggiunto alle abbreviazioni tradizionali):

• ECDHE: Una versione effimera del protocollo di accordo sulle chiavi Elliptic Curve Diffie-Hellman.
• DHE: Una versione effimera del protocollo di accordo sulle chiavi Diffie-Hellman.

La segretezza in avanti perfetta usando ECDHE è abilitata per impostazione predefinita. L'opzione ecdhCurve può essere utilizzata durante la creazione di un server TLS per personalizzare l'elenco delle curve ECDH supportate da utilizzare. Vedi tls.createServer() per maggiori informazioni.

DHE è disabilitato per impostazione predefinita, ma può essere abilitato insieme a ECDHE impostando l'opzione dhparam su 'auto'. Sono supportati anche parametri DHE personalizzati, ma sono sconsigliati a favore di parametri automaticamente selezionati e ben noti.

La segretezza in avanti perfetta era opzionale fino a TLSv1.2. Da TLSv1.3, (EC)DHE viene sempre utilizzato (ad eccezione delle connessioni solo PSK).

ALPN e SNI

ALPN (Application-Layer Protocol Negotiation Extension) e SNI (Server Name Indication) sono estensioni di handshake TLS:

• ALPN: Consente l'utilizzo di un singolo server TLS per più protocolli (HTTP, HTTP/2)
• SNI: Consente l'utilizzo di un singolo server TLS per più nomi host con certificati diversi.

Chiavi pre-condivisi

Il supporto TLS-PSK è disponibile come alternativa all'autenticazione standard basata su certificati. Utilizza una chiave pre-condivisa invece dei certificati per autenticare una connessione TLS, fornendo un'autenticazione reciproca. TLS-PSK e l'infrastruttura a chiave pubblica non si escludono a vicenda. Client e server possono supportare entrambi, scegliendo uno di essi durante la normale fase di negoziazione delle cifre.

TLS-PSK è una buona scelta solo quando esistono mezzi per condividere in modo sicuro una chiave con ogni macchina che si connette, quindi non sostituisce l'infrastruttura a chiave pubblica (PKI) per la maggior parte degli utilizzi di TLS. L'implementazione TLS-PSK in OpenSSL ha presentato molti difetti di sicurezza negli ultimi anni, principalmente perché è utilizzata solo da una minoranza di applicazioni. Si prega di considerare tutte le soluzioni alternative prima di passare alle cifre PSK. Durante la generazione di PSK è di fondamentale importanza utilizzare un'entropia sufficiente come discusso in RFC 4086. Derivare un segreto condiviso da una password o da altre fonti a bassa entropia non è sicuro.

Le cifre PSK sono disabilitate per impostazione predefinita e l'utilizzo di TLS-PSK richiede quindi la specifica esplicita di una suite di cifre con l'opzione ciphers. L'elenco delle cifre disponibili può essere recuperato tramite openssl ciphers -v 'PSK'. Tutte le cifre TLS 1.3 sono idonee per PSK e possono essere recuperate tramite openssl ciphers -v -s -tls1_3 -psk. Sulla connessione client, deve essere passato un checkServerIdentity personalizzato perché quello predefinito avrà esito negativo in assenza di un certificato.

Secondo la RFC 4279, devono essere supportate identità PSK fino a 128 byte di lunghezza e PSK fino a 64 byte di lunghezza. Da OpenSSL 1.1.0 la dimensione massima dell'identità è di 128 byte e la lunghezza massima di PSK è di 256 byte.

L'implementazione attuale non supporta le callback PSK asincrone a causa delle limitazioni dell'API OpenSSL sottostante.

Per utilizzare TLS-PSK, client e server devono specificare l'opzione pskCallback, una funzione che restituisce il PSK da utilizzare (che deve essere compatibile con il digest della cifra selezionata).

Verrà chiamato prima sul client:

• hint: <string> messaggio opzionale inviato dal server per aiutare il client a decidere quale identità utilizzare durante la negoziazione. Sempre null se viene utilizzato TLS 1.3.
• Restituisce: <Object> nella forma { psk: \<Buffer|TypedArray|DataView\>, identity: \<string\> } o null.

Quindi sul server:

• socket: <tls.TLSSocket> l'istanza del socket server, equivalente a this.
• identity: <string> parametro di identità inviato dal client.
• Restituisce: <Buffer> | <TypedArray> | <DataView> il PSK (o null).

Un valore di ritorno di null interrompe il processo di negoziazione e invia un messaggio di avviso unknown_psk_identity all'altra parte. Se il server desidera nascondere il fatto che l'identità PSK non era nota, la callback deve fornire alcuni dati casuali come psk per far fallire la connessione con decrypt_error prima che la negoziazione sia terminata.

Attenuazione dell'attacco di rinegoziazione avviata dal client

Il protocollo TLS consente ai client di rinegoziare determinati aspetti della sessione TLS. Sfortunatamente, la rinegoziazione della sessione richiede una quantità sproporzionata di risorse lato server, rendendola un potenziale vettore per attacchi di denial-of-service.

Per mitigare il rischio, la rinegoziazione è limitata a tre volte ogni dieci minuti. Un evento 'error' viene emesso sull'istanza tls.TLSSocket quando viene superata questa soglia. I limiti sono configurabili:

• tls.CLIENT_RENEG_LIMIT <numero> Specifica il numero di richieste di rinegoziazione. Default: 3.
• tls.CLIENT_RENEG_WINDOW <numero> Specifica la finestra temporale di rinegoziazione in secondi. Default: 600 (10 minuti).

I limiti di rinegoziazione predefiniti non devono essere modificati senza una completa comprensione delle implicazioni e dei rischi.

TLSv1.3 non supporta la rinegoziazione.

Ripresa della sessione

Stabilire una sessione TLS può essere relativamente lento. Il processo può essere accelerato salvando e riutilizzando in seguito lo stato della sessione. Esistono diversi meccanismi per farlo, discussi qui dal più vecchio al più recente (e preferito).

Identificatori di sessione

I server generano un ID univoco per le nuove connessioni e lo inviano al client. Client e server salvano lo stato della sessione. Al momento della riconnessione, i client inviano l'ID dello stato della loro sessione salvata e, se anche il server ha lo stato per tale ID, può accettare di utilizzarlo. Altrimenti, il server creerà una nuova sessione. Vedi RFC 2246 per maggiori informazioni, pagine 23 e 30.

La ripresa utilizzando gli identificatori di sessione è supportata dalla maggior parte dei browser web quando si effettuano richieste HTTPS.

Per Node.js, i client attendono l'evento 'session' per ottenere i dati della sessione e forniscono i dati all'opzione session di un successivo tls.connect() per riutilizzare la sessione. I server devono implementare handler per gli eventi 'newSession' e 'resumeSession' per salvare e ripristinare i dati della sessione utilizzando l'ID della sessione come chiave di ricerca per riutilizzare le sessioni. Per riutilizzare le sessioni tra bilanciatori di carico o worker del cluster, i server devono utilizzare una cache di sessione condivisa (come Redis) nei loro handler di sessione.

Ticket di sessione

I server crittografano l'intero stato della sessione e lo inviano al client come "ticket". Al momento della riconnessione, lo stato viene inviato al server nella connessione iniziale. Questo meccanismo evita la necessità di una cache di sessione lato server. Se il server non utilizza il ticket, per qualsiasi motivo (impossibilità di decrittografarlo, è troppo vecchio, ecc.), creerà una nuova sessione e invierà un nuovo ticket. Vedi RFC 5077 per maggiori informazioni.

La ripresa utilizzando i ticket di sessione sta diventando comunemente supportata da molti browser web quando si effettuano richieste HTTPS.

Per Node.js, i client utilizzano le stesse API per la ripresa con identificatori di sessione che per la ripresa con ticket di sessione. Per il debug, se tls.TLSSocket.getTLSTicket() restituisce un valore, i dati della sessione contengono un ticket, altrimenti contengono lo stato della sessione lato client.

Con TLSv1.3, si tenga presente che il server potrebbe inviare più ticket, con conseguenti eventi 'session' multipli, vedere 'session' per maggiori informazioni.

I server a singolo processo non richiedono implementazioni specifiche per utilizzare i ticket di sessione. Per utilizzare i ticket di sessione tra riavvii del server o bilanciatori di carico, tutti i server devono avere le stesse chiavi dei ticket. Internamente ci sono tre chiavi a 16 byte, ma l'API tls le espone come un singolo buffer a 48 byte per comodità.

È possibile ottenere le chiavi dei ticket chiamando server.getTicketKeys() su un'istanza del server e poi distribuirle, ma è più ragionevole generare in modo sicuro 48 byte di dati casuali sicuri e impostarli con l'opzione ticketKeys di tls.createServer(). Le chiavi devono essere rigenerate regolarmente e le chiavi del server possono essere ripristinate con server.setTicketKeys().

Le chiavi dei ticket di sessione sono chiavi crittografiche e devono essere archiviate in modo sicuro. Con TLS 1.2 e versioni precedenti, se vengono compromesse, tutte le sessioni che hanno utilizzato ticket crittografati con esse possono essere decrittografate. Non devono essere memorizzate su disco e devono essere rigenerate regolarmente.

Se i client pubblicizzano il supporto per i ticket, il server li invierà. Il server può disabilitare i ticket fornendo require('node:constants').SSL_OP_NO_TICKET in secureOptions.

Sia gli identificatori di sessione che i ticket di sessione scadono, causando la creazione di nuove sessioni da parte del server. Il timeout può essere configurato con l'opzione sessionTimeout di tls.createServer().

Per tutti i meccanismi, quando la ripresa fallisce, i server creeranno nuove sessioni. Poiché l'impossibilità di riprendere la sessione non causa errori di connessione TLS/HTTPS, è facile non notare prestazioni TLS inutilmente scarse. La CLI OpenSSL può essere utilizzata per verificare che i server stiano riprendendo le sessioni. Utilizzare l'opzione -reconnect per openssl s_client, ad esempio:

openssl s_client -connect localhost:443 -reconnect

Leggere l'output di debug. La prima connessione dovrebbe dire "New", ad esempio:

New, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256

Le connessioni successive dovrebbero dire "Reused", ad esempio:

Reused, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256

Modifica della suite di cifratura TLS predefinita

Node.js è costruito con una suite predefinita di cifrature TLS abilitate e disabilitate. Questo elenco di cifrature predefinito può essere configurato durante la compilazione di Node.js per consentire alle distribuzioni di fornire il proprio elenco predefinito.

Il seguente comando può essere utilizzato per visualizzare la suite di cifratura predefinita:

node -p crypto.constants.defaultCoreCipherList | tr ':' '\n'
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-GCM-SHA384
DHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-SHA256
DHE-RSA-AES128-SHA256
ECDHE-RSA-AES256-SHA384
DHE-RSA-AES256-SHA384
ECDHE-RSA-AES256-SHA256
DHE-RSA-AES256-SHA256
HIGH
!aNULL
!eNULL
!EXPORT
!DES
!RC4
!MD5
!PSK
!SRP
!CAMELLIA

Questo valore predefinito può essere sostituito completamente utilizzando l'opzione della riga di comando --tls-cipher-list (direttamente o tramite la variabile di ambiente NODE_OPTIONS). Ad esempio, il seguente comando imposta ECDHE-RSA-AES128-GCM-SHA256:!RC4 come suite di cifratura TLS predefinita:

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' server.js

export NODE_OPTIONS=--tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4'
node server.js

Per verificare, utilizzare il seguente comando per visualizzare l'elenco di cifrature impostato, notare la differenza tra defaultCoreCipherList e defaultCipherList:

node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' -p crypto.constants.defaultCipherList | tr ':' '\n'
ECDHE-RSA-AES128-GCM-SHA256
!RC4

cioè, l'elenco defaultCoreCipherList è impostato al momento della compilazione e defaultCipherList è impostato in fase di esecuzione.

Per modificare le suite di cifratura predefinite dall'interno del runtime, modificare la variabile tls.DEFAULT_CIPHERS. Questa operazione deve essere eseguita prima di ascoltare su qualsiasi socket; non influenzerà i socket già aperti. Ad esempio:

// Rimuove le cifrature CBC obsolete e le cifrature basate sullo scambio di chiavi RSA in quanto non forniscono la segretezza in avanti
tls.DEFAULT_CIPHERS +=
  ':!ECDHE-RSA-AES128-SHA:!ECDHE-RSA-AES128-SHA256:!ECDHE-RSA-AES256-SHA:!ECDHE-RSA-AES256-SHA384' +
  ':!ECDHE-ECDSA-AES128-SHA:!ECDHE-ECDSA-AES128-SHA256:!ECDHE-ECDSA-AES256-SHA:!ECDHE-ECDSA-AES256-SHA384' +
  ':!kRSA'

Il valore predefinito può anche essere sostituito per ciascun client o server utilizzando l'opzione ciphers di tls.createSecureContext(), che è disponibile anche in tls.createServer(), tls.connect() e durante la creazione di nuovi tls.TLSSocket.

L'elenco delle cifrature può contenere una miscela di nomi di suite di cifratura TLSv1.3, quelli che iniziano con 'TLS_', e specifiche per le suite di cifratura TLSv1.2 e precedenti. Le cifrature TLSv1.2 supportano un formato di specifica legacy; consultare la documentazione del formato dell'elenco delle cifrature OpenSSL formato dell'elenco delle cifrature per i dettagli, ma tali specifiche non si applicano alle cifrature TLSv1.3. Le suite TLSv1.3 possono essere abilitate solo includendo il loro nome completo nell'elenco delle cifrature. Non possono, ad esempio, essere abilitate o disabilitate utilizzando la specifica legacy TLSv1.2 'EECDH' o '!EECDH'.

Nonostante l'ordine relativo delle suite di cifratura TLSv1.3 e TLSv1.2, il protocollo TLSv1.3 è significativamente più sicuro di TLSv1.2 e verrà sempre scelto rispetto a TLSv1.2 se la handshake indica che è supportato e se sono abilitate delle suite di cifratura TLSv1.3.

La suite di cifratura predefinita inclusa in Node.js è stata attentamente selezionata per riflettere le attuali best practice di sicurezza e la mitigazione dei rischi. La modifica della suite di cifratura predefinita può avere un impatto significativo sulla sicurezza di un'applicazione. L'opzione --tls-cipher-list e l'opzione ciphers devono essere utilizzate solo se assolutamente necessario.

La suite di cifratura predefinita preferisce le cifrature GCM per l'impostazione della crittografia moderna di Chrome e preferisce anche le cifrature ECDHE e DHE per la segretezza in avanti perfetta, offrendo alcune compatibilità all'indietro.

I vecchi client che si basano su cifrature RC4 o DES obsolete e non sicure (come Internet Explorer 6) non possono completare il processo di handshake con la configurazione predefinita. Se questi client devono essere supportati, le raccomandazioni TLS possono offrire una suite di cifratura compatibile. Per maggiori dettagli sul formato, consultare la documentazione del formato dell'elenco delle cifrature OpenSSL formato dell'elenco delle cifrature.

Esistono solo cinque suite di cifratura TLSv1.3:

• 'TLS_AES_256_GCM_SHA384'
• 'TLS_CHACHA20_POLY1305_SHA256'
• 'TLS_AES_128_GCM_SHA256'
• 'TLS_AES_128_CCM_SHA256'
• 'TLS_AES_128_CCM_8_SHA256'

Le prime tre sono abilitate per impostazione predefinita. Le due suite basate su CCM sono supportate da TLSv1.3 perché potrebbero essere più performanti su sistemi con risorse limitate, ma non sono abilitate per impostazione predefinita poiché offrono meno sicurezza.

Livello di sicurezza OpenSSL

La libreria OpenSSL applica livelli di sicurezza per controllare il livello minimo di sicurezza accettabile per le operazioni crittografiche. I livelli di sicurezza di OpenSSL vanno da 0 a 5, con ogni livello che impone requisiti di sicurezza più stringenti. Il livello di sicurezza predefinito è 1, generalmente adatto alla maggior parte delle applicazioni moderne. Tuttavia, alcune funzionalità e protocolli legacy, come TLSv1, richiedono un livello di sicurezza inferiore (SECLEVEL=0) per funzionare correttamente. Per informazioni più dettagliate, fare riferimento alla documentazione OpenSSL sui livelli di sicurezza.

Impostazione dei livelli di sicurezza

Per regolare il livello di sicurezza nella tua applicazione Node.js, puoi includere @SECLEVEL=X all'interno di una stringa di cifratura, dove X è il livello di sicurezza desiderato. Ad esempio, per impostare il livello di sicurezza su 0 utilizzando l'elenco di cifrature OpenSSL predefinito, puoi utilizzare:

ESM

import { createServer, connect } from 'node:tls'
const port = 443

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function (socket) {
  console.log('Client connected with protocol:', socket.getProtocol())
  socket.end()
  this.close()
}).listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' })
})

CJS

const { createServer, connect } = require('node:tls')
const port = 443

createServer({ ciphers: 'DEFAULT@SECLEVEL=0', minVersion: 'TLSv1' }, function (socket) {
  console.log('Client connected with protocol:', socket.getProtocol())
  socket.end()
  this.close()
}).listen(port, () => {
  connect(port, { ciphers: 'DEFAULT@SECLEVEL=0', maxVersion: 'TLSv1' })
})

Questo approccio imposta il livello di sicurezza su 0, consentendo l'utilizzo di funzionalità legacy pur sfruttando le cifrature OpenSSL predefinite.

Utilizzo

È anche possibile impostare il livello di sicurezza e le cifrature dalla riga di comando utilizzando --tls-cipher-list=DEFAULT@SECLEVEL=X come descritto in Modifica della suite di cifratura TLS predefinita. Tuttavia, in genere è sconsigliato utilizzare l'opzione della riga di comando per l'impostazione delle cifrature ed è preferibile configurare le cifrature per contesti individuali all'interno del codice della tua applicazione, poiché questo approccio offre un controllo più preciso e riduce il rischio di ridurre globalmente il livello di sicurezza.

Codici di errore del certificato X509

Diverse funzioni possono fallire a causa di errori del certificato segnalati da OpenSSL. In tal caso, la funzione fornisce un <Errore> tramite il suo callback che ha la proprietà code che può assumere uno dei seguenti valori:

• 'UNABLE_TO_GET_ISSUER_CERT': Impossibile ottenere il certificato dell'emittente.
• 'UNABLE_TO_GET_CRL': Impossibile ottenere la CRL del certificato.
• 'UNABLE_TO_DECRYPT_CERT_SIGNATURE': Impossibile decrittografare la firma del certificato.
• 'UNABLE_TO_DECRYPT_CRL_SIGNATURE': Impossibile decrittografare la firma della CRL.
• 'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY': Impossibile decodificare la chiave pubblica dell'emittente.
• 'CERT_SIGNATURE_FAILURE': Errore di firma del certificato.
• 'CRL_SIGNATURE_FAILURE': Errore di firma della CRL.
• 'CERT_NOT_YET_VALID': Il certificato non è ancora valido.
• 'CERT_HAS_EXPIRED': Il certificato è scaduto.
• 'CRL_NOT_YET_VALID': La CRL non è ancora valida.
• 'CRL_HAS_EXPIRED': La CRL è scaduta.
• 'ERROR_IN_CERT_NOT_BEFORE_FIELD': Errore di formato nel campo notBefore del certificato.
• 'ERROR_IN_CERT_NOT_AFTER_FIELD': Errore di formato nel campo notAfter del certificato.
• 'ERROR_IN_CRL_LAST_UPDATE_FIELD': Errore di formato nel campo lastUpdate della CRL.
• 'ERROR_IN_CRL_NEXT_UPDATE_FIELD': Errore di formato nel campo nextUpdate della CRL.
• 'OUT_OF_MEM': Memoria insufficiente.
• 'DEPTH_ZERO_SELF_SIGNED_CERT': Certificato autofirmato.
• 'SELF_SIGNED_CERT_IN_CHAIN': Certificato autofirmato nella catena di certificati.
• 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY': Impossibile ottenere il certificato dell'emittente locale.
• 'UNABLE_TO_VERIFY_LEAF_SIGNATURE': Impossibile verificare il primo certificato.
• 'CERT_CHAIN_TOO_LONG': Catena di certificati troppo lunga.
• 'CERT_REVOKED': Certificato revocato.
• 'INVALID_CA': Certificato CA non valido.
• 'PATH_LENGTH_EXCEEDED': Vincolo di lunghezza del percorso superato.
• 'INVALID_PURPOSE': Scopo del certificato non supportato.
• 'CERT_UNTRUSTED': Certificato non attendibile.
• 'CERT_REJECTED': Certificato rifiutato.
• 'HOSTNAME_MISMATCH': Mancata corrispondenza del nome host.

Classe: tls.CryptoStream

Aggiunto in: v0.3.4

Deprecato da: v0.11.3

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato: Utilizzare tls.TLSSocket invece.

La classe tls.CryptoStream rappresenta un flusso di dati crittografati. Questa classe è deprecata e non dovrebbe più essere utilizzata.

cryptoStream.bytesWritten

Aggiunto in: v0.3.4

Deprecato da: v0.11.3

La proprietà cryptoStream.bytesWritten restituisce il numero totale di byte scritti sulla socket sottostante inclusi i byte necessari per l'implementazione del protocollo TLS.

Classe: tls.SecurePair

Aggiunto in: v0.3.2

Deprecato da: v0.11.3

[Stabile: 0 - Deprecato]

Stabile: 0 Stabilità: 0 - Deprecato: Utilizzare tls.TLSSocket invece.

Restituito da tls.createSecurePair().

Evento: 'secure'

Aggiunto in: v0.3.2

Deprecato da: v0.11.3

L'evento 'secure' viene emesso dall'oggetto SecurePair una volta stabilita una connessione sicura.

Come per il controllo dell'evento 'secureConnection' del server, pair.cleartext.authorized dovrebbe essere ispezionato per confermare se il certificato utilizzato è correttamente autorizzato.

Classe: tls.Server

Aggiunto in: v0.3.2

• Estensione: <net.Server>

Accetta connessioni crittografate usando TLS o SSL.

Evento: 'connection'

Aggiunto in: v0.3.2

• socket <stream.Duplex>

Questo evento viene emesso quando viene stabilito un nuovo flusso TCP, prima che inizi la handshake TLS. socket è tipicamente un oggetto di tipo net.Socket ma non riceverà eventi a differenza della socket creata dall'evento 'connection' di net.Server. Di solito gli utenti non vorranno accedere a questo evento.

Questo evento può anche essere emesso esplicitamente dagli utenti per iniettare connessioni nel server TLS. In tal caso, può essere passato qualsiasi flusso Duplex.

Evento: 'keylog'

Aggiunto in: v12.3.0, v10.20.0

• line <Buffer> Riga di testo ASCII, nel formato NSS SSLKEYLOGFILE.
• tlsSocket <tls.TLSSocket> L'istanza tls.TLSSocket su cui è stata generata.

L'evento keylog viene emesso quando il materiale chiave viene generato o ricevuto da una connessione a questo server (tipicamente prima che la handshake sia completata, ma non necessariamente). Questo materiale di chiave può essere memorizzato per il debug, poiché consente la decrittazione del traffico TLS catturato. Può essere emesso più volte per ogni socket.

Un caso d'uso tipico è quello di aggiungere le righe ricevute a un file di testo comune, che viene successivamente utilizzato da un software (come Wireshark) per decrittografare il traffico:

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' })
// ...
server.on('keylog', (line, tlsSocket) => {
  if (tlsSocket.remoteAddress !== '...') return // Registra le chiavi solo per un particolare IP
  logFile.write(line)
})

Evento: 'newSession'

[Cronologia]

Versione	Modifiche
v0.11.12	L'argomento callback è ora supportato.
v0.9.2	Aggiunto in: v0.9.2

L'evento 'newSession' viene emesso al momento della creazione di una nuova sessione TLS. Questo può essere utilizzato per memorizzare le sessioni in un archivio esterno. I dati devono essere forniti al callback 'resumeSession'.

Il callback dell'ascoltatore riceve tre argomenti quando viene chiamato:

• sessionId <Buffer> L'identificatore della sessione TLS
• sessionData <Buffer> I dati della sessione TLS
• callback <Function> Una funzione di callback che non accetta argomenti e che deve essere invocata affinché i dati vengano inviati o ricevuti tramite la connessione sicura.

L'ascolto di questo evento avrà effetto solo sulle connessioni stabilite dopo l'aggiunta dell'ascoltatore di eventi.

Evento: 'OCSPRequest'

Aggiunto in: v0.11.13

L'evento 'OCSPRequest' viene emesso quando il client invia una richiesta di stato del certificato. Il callback dell'ascoltatore riceve tre argomenti quando viene chiamato:

• certificate <Buffer> Il certificato del server
• issuer <Buffer> Il certificato dell'emittente
• callback <Function> Una funzione di callback che deve essere invocata per fornire i risultati della richiesta OCSP.

Il certificato corrente del server può essere analizzato per ottenere l'URL OCSP e l'ID del certificato; dopo aver ottenuto una risposta OCSP, viene quindi invocato callback(null, resp), dove resp è un'istanza Buffer contenente la risposta OCSP. Sia certificate che issuer sono rappresentazioni DER Buffer dei certificati principali e dell'emittente. Questi possono essere utilizzati per ottenere l'ID del certificato OCSP e l'URL del punto finale OCSP.

In alternativa, è possibile chiamare callback(null, null), indicando che non c'era alcuna risposta OCSP.

Chiamare callback(err) comporterà una chiamata socket.destroy(err).

Il flusso tipico di una richiesta OCSP è il seguente:

L'emittente può essere null se il certificato è autofirmato o l'emittente non è presente nell'elenco dei certificati radice. (Un emittente può essere fornito tramite l'opzione ca durante la creazione della connessione TLS.)

L'ascolto di questo evento avrà effetto solo sulle connessioni stabilite dopo l'aggiunta dell'ascoltatore di eventi.

Un modulo npm come asn1.js può essere utilizzato per analizzare i certificati.

Evento: 'resumeSession'

Aggiunto in: v0.9.2

L'evento 'resumeSession' viene emesso quando il client richiede di riprendere una precedente sessione TLS. La callback dell'ascoltatore riceve due argomenti quando viene chiamata:

• sessionId <Buffer> L'identificatore della sessione TLS
• callback <Function> Una funzione di callback da chiamare quando la sessione precedente è stata recuperata: callback([err[, sessionData]])
  • err <Error>
  • sessionData <Buffer>

L'ascoltatore di eventi dovrebbe eseguire una ricerca nell'archiviazione esterna per i dati sessionData salvati dal gestore eventi 'newSession' usando l'id sessionId fornito. Se trovato, chiamare callback(null, sessionData) per riprendere la sessione. Se non trovato, la sessione non può essere ripresa. callback() deve essere chiamato senza sessionData in modo che la handshake possa continuare e venga creata una nuova sessione. È possibile chiamare callback(err) per terminare la connessione in arrivo e distruggere il socket.

L'ascolto di questo evento avrà effetto solo sulle connessioni stabilite dopo l'aggiunta dell'ascoltatore di eventi.

Il seguente esempio illustra la ripresa di una sessione TLS:

const tlsSessionStore = {}
server.on('newSession', (id, data, cb) => {
  tlsSessionStore[id.toString('hex')] = data
  cb()
})
server.on('resumeSession', (id, cb) => {
  cb(null, tlsSessionStore[id.toString('hex')] || null)
})

Evento: 'secureConnection'

Aggiunto in: v0.3.2

L'evento 'secureConnection' viene emesso dopo che il processo di handshake per una nuova connessione è stato completato correttamente. La callback dell'ascoltatore riceve un singolo argomento quando viene chiamata:

• tlsSocket <tls.TLSSocket> Il socket TLS stabilito.

La proprietà tlsSocket.authorized è un booleano che indica se il client è stato verificato da una delle Autorità di Certificazione fornite per il server. Se tlsSocket.authorized è false, allora socket.authorizationError è impostato per descrivere come è fallito l'autorizzazione. A seconda delle impostazioni del server TLS, le connessioni non autorizzate potrebbero comunque essere accettate.

La proprietà tlsSocket.alpnProtocol è una stringa che contiene il protocollo ALPN selezionato. Quando ALPN non ha alcun protocollo selezionato perché il client o il server non hanno inviato un'estensione ALPN, tlsSocket.alpnProtocol è uguale a false.

La proprietà tlsSocket.servername è una stringa che contiene il nome del server richiesto tramite SNI.

Evento: 'tlsClientError'

Aggiunto in: v6.0.0

L'evento 'tlsClientError' viene emesso quando si verifica un errore prima che venga stabilita una connessione sicura. La callback dell'ascoltatore riceve due argomenti quando viene chiamata:

• exception <Error> L'oggetto Error che descrive l'errore
• tlsSocket <tls.TLSSocket> L'istanza tls.TLSSocket da cui ha avuto origine l'errore.

server.addContext(hostname, context)

Aggiunto in: v0.5.3

• hostname <string> Un nome host SNI o un carattere jolly (es. '*')
• context <Object> | <tls.SecureContext> Un oggetto contenente una qualsiasi delle possibili proprietà dagli argomenti options di tls.createSecureContext() (es. key, cert, ca, ecc.), o un oggetto contesto TLS creato con tls.createSecureContext() stesso.

Il metodo server.addContext() aggiunge un contesto sicuro che verrà utilizzato se il nome SNI della richiesta del client corrisponde al hostname fornito (o al carattere jolly).

Quando ci sono più contesti corrispondenti, viene utilizzato quello aggiunto più recentemente.

server.address()

Aggiunto in: v0.6.0

• Restituisce: <Object>

Restituisce l'indirizzo associato, il nome della famiglia di indirizzi e la porta del server come riportato dal sistema operativo. Vedi net.Server.address() per maggiori informazioni.

server.close([callback])

Aggiunto in: v0.3.2

• callback <Function> Una callback di ascoltatore che verrà registrata per ascoltare l'evento 'close' dell'istanza del server.
• Restituisce: <tls.Server>

Il metodo server.close() impedisce al server di accettare nuove connessioni.

Questa funzione opera in modo asincrono. L'evento 'close' verrà emesso quando il server non avrà più connessioni aperte.

server.getTicketKeys()

Aggiunto in: v3.0.0

• Restituisce: <Buffer> Un buffer di 48 byte contenente le chiavi del ticket di sessione.

Restituisce le chiavi del ticket di sessione.

Vedi Ripristino sessione per maggiori informazioni.

server.listen()

Avvia l'ascolto del server per connessioni crittografate. Questo metodo è identico a server.listen() di net.Server.

server.setSecureContext(options)

Aggiunto in: v11.0.0

• options <Object> Un oggetto contenente qualsiasi delle possibili proprietà dagli argomenti options di tls.createSecureContext() (es. key, cert, ca, ecc.).

Il metodo server.setSecureContext() sostituisce il contesto sicuro di un server esistente. Le connessioni esistenti al server non vengono interrotte.

server.setTicketKeys(keys)

Aggiunto in: v3.0.0

• keys <Buffer> | <TypedArray> | <DataView> Un buffer di 48 byte contenente le chiavi del ticket di sessione.

Imposta le chiavi del ticket di sessione.

Le modifiche alle chiavi del ticket sono effettive solo per le future connessioni del server. Le connessioni del server esistenti o attualmente in sospeso utilizzeranno le chiavi precedenti.

Vedi Ripristino sessione per maggiori informazioni.

Classe: tls.TLSSocket

Aggiunto in: v0.11.4

• Estende: <net.Socket>

Esegue la crittografia trasparente dei dati scritti e tutte le necessarie negoziazioni TLS.

Le istanze di tls.TLSSocket implementano l'interfaccia duplex Stream.

I metodi che restituiscono i metadati della connessione TLS (es. tls.TLSSocket.getPeerCertificate()) restituiranno dati solo quando la connessione è aperta.

new tls.TLSSocket(socket[, options])

[Cronologia]

Versione	Modifiche
v12.2.0	Ora è supportata l'opzione enableTrace.
v5.0.0	Ora sono supportate le opzioni ALPN.
v0.11.4	Aggiunta in: v0.11.4

• socket <net.Socket> | <stream.Duplex> Sul lato server, qualsiasi stream Duplex. Sul lato client, qualsiasi istanza di net.Socket (per il supporto di stream Duplex generici sul lato client, deve essere utilizzato tls.connect()).
• options <Object>
  • enableTrace: Vedi tls.createServer()
  • isServer: Il protocollo SSL/TLS è asimmetrico, i TLSSocket devono sapere se devono comportarsi come server o come client. Se true, il socket TLS verrà istanziato come server. Default: false.
  • server <net.Server> Un'istanza di net.Server.
  • requestCert: Se autenticare il peer remoto richiedendo un certificato. I client richiedono sempre un certificato server. I server (isServer è true) possono impostare requestCert su true per richiedere un certificato client.
  • rejectUnauthorized: Vedi tls.createServer()
  • ALPNProtocols: Vedi tls.createServer()
  • SNICallback: Vedi tls.createServer()
  • session <Buffer> Un'istanza Buffer contenente una sessione TLS.
  • requestOCSP <boolean> Se true, specifica che l'estensione della richiesta di stato OCSP verrà aggiunta al client hello e verrà emesso un evento 'OCSPResponse' sul socket prima di stabilire una comunicazione sicura.
  • secureContext: Oggetto di contesto TLS creato con tls.createSecureContext(). Se un secureContext non viene fornito, ne verrà creato uno passando l'intero oggetto options a tls.createSecureContext().
  • ...: opzioni tls.createSecureContext() che vengono utilizzate se l'opzione secureContext manca. Altrimenti, vengono ignorate.

Costruisce un nuovo oggetto tls.TLSSocket da un socket TCP esistente.

Evento: 'keylog'

Aggiunto in: v12.3.0, v10.20.0

• line <Buffer> Riga di testo ASCII, nel formato NSS SSLKEYLOGFILE.

L'evento keylog viene emesso su un tls.TLSSocket quando il materiale chiave viene generato o ricevuto dal socket. Questo materiale di crittografia può essere memorizzato per il debug, poiché consente la decrittazione del traffico TLS catturato. Può essere emesso più volte, prima o dopo il completamento della handshake.

Un caso d'uso tipico è quello di aggiungere le righe ricevute a un file di testo comune, che viene successivamente utilizzato da un software (come Wireshark) per decrittografare il traffico:

const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' })
// ...
tlsSocket.on('keylog', line => logFile.write(line))

Evento: 'OCSPResponse'

Aggiunto in: v0.11.13

L'evento 'OCSPResponse' viene emesso se l'opzione requestOCSP è stata impostata quando è stato creato il tls.TLSSocket ed è stata ricevuta una risposta OCSP. La callback dell'ascoltatore riceve un singolo argomento quando viene chiamata:

• response <Buffer> La risposta OCSP del server

In genere, la response è un oggetto digitalmente firmato dall'autorità di certificazione del server che contiene informazioni sullo stato di revoca del certificato del server.

Evento: 'secureConnect'

Aggiunto in: v0.11.4

L'evento 'secureConnect' viene emesso dopo che il processo di handshake per una nuova connessione è stato completato correttamente. La callback dell'ascoltatore verrà chiamata indipendentemente dal fatto che il certificato del server sia stato autorizzato o meno. È responsabilità del client verificare la proprietà tlsSocket.authorized per determinare se il certificato del server è stato firmato da una delle CA specificate. Se tlsSocket.authorized === false, l'errore può essere trovato esaminando la proprietà tlsSocket.authorizationError. Se è stato utilizzato ALPN, è possibile controllare la proprietà tlsSocket.alpnProtocol per determinare il protocollo negoziato.

L'evento 'secureConnect' non viene emesso quando viene creato un <tls.TLSSocket> utilizzando il costruttore new tls.TLSSocket().

Evento: 'session'

Aggiunto in: v11.10.0

• session <Buffer>

L'evento 'session' viene emesso su un client tls.TLSSocket quando è disponibile una nuova sessione o un ticket TLS. Questo potrebbe avvenire prima o dopo il completamento della handshake, a seconda della versione del protocollo TLS negoziata. L'evento non viene emesso sul server, o se non è stata creata una nuova sessione, ad esempio, quando la connessione è stata ripresa. Per alcune versioni del protocollo TLS l'evento potrebbe essere emesso più volte, nel qual caso tutte le sessioni possono essere utilizzate per la ripresa.

Sul client, la session può essere fornita all'opzione session di tls.connect() per riprendere la connessione.

Vedi Ripresa della Sessione per maggiori informazioni.

Per TLSv1.2 e versioni precedenti, tls.TLSSocket.getSession() può essere chiamato una volta completata la handshake. Per TLSv1.3, il protocollo consente solo la ripresa basata su ticket, vengono inviati più ticket e i ticket non vengono inviati fino al completamento della handshake. Quindi è necessario attendere l'evento 'session' per ottenere una sessione ripristinabile. Le applicazioni dovrebbero utilizzare l'evento 'session' invece di getSession() per assicurarsi che funzionino per tutte le versioni TLS. Le applicazioni che si aspettano di ottenere o utilizzare una sola sessione dovrebbero ascoltare questo evento una sola volta:

tlsSocket.once('session', session => {
  // La sessione può essere utilizzata immediatamente o successivamente.
  tls.connect({
    session: session,
    // Altre opzioni di connessione...
  })
})

tlsSocket.address()

[Cronologia]

Versione	Modifiche
v18.4.0	La proprietà family ora restituisce una stringa invece di un numero.
v18.0.0	La proprietà family ora restituisce un numero invece di una stringa.
v0.11.4	Aggiunto in: v0.11.4

• Restituisce: <Object>

Restituisce l'indirizzo address associato, il nome della famiglia di indirizzi family e la port del socket sottostante come riportato dal sistema operativo: { port: 12346, family: 'IPv4', address: '127.0.0.1' }.

tlsSocket.authorizationError

Aggiunto in: v0.11.4

Restituisce il motivo per cui il certificato del peer non è stato verificato. Questa proprietà viene impostata solo quando tlsSocket.authorized === false.

tlsSocket.authorized

Aggiunto in: v0.11.4

• <boolean>

Questa proprietà è true se il certificato peer è stato firmato da una delle CA specificate durante la creazione dell'istanza tls.TLSSocket, altrimenti false.

tlsSocket.disableRenegotiation()

Aggiunto in: v8.4.0

Disabilita la rinegoziazione TLS per questa istanza TLSSocket. Una volta chiamata, i tentativi di rinegoziazione attiveranno un evento 'error' sul TLSSocket.

tlsSocket.enableTrace()

Aggiunto in: v12.2.0

Quando abilitato, le informazioni di traccia del pacchetto TLS vengono scritte su stderr. Questo può essere utilizzato per eseguire il debug dei problemi di connessione TLS.

Il formato dell'output è identico all'output di openssl s_client -trace o openssl s_server -trace. Sebbene sia prodotto dalla funzione SSL_trace() di OpenSSL, il formato non è documentato, può cambiare senza preavviso e non dovrebbe essere considerato affidabile.

tlsSocket.encrypted

Aggiunto in: v0.11.4

Restituisce sempre true. Questo può essere utilizzato per distinguere i socket TLS dalle istanze net.Socket regolari.

tlsSocket.exportKeyingMaterial(length, label[, context])

Aggiunto in: v13.10.0, v12.17.0

• length <number> numero di byte da recuperare dal materiale di keying
• label <string> un'etichetta specifica dell'applicazione, in genere questo sarà un valore dal Registro etichette esportatore IANA.
• context <Buffer> Facoltativamente fornisci un contesto.
• Restituisce: <Buffer> byte richiesti del materiale di keying

Il materiale di keying viene utilizzato per le convalide per prevenire diversi tipi di attacchi nei protocolli di rete, ad esempio nelle specifiche di IEEE 802.1X.

Esempio

const keyingMaterial = tlsSocket.exportKeyingMaterial(128, 'client finished')

/*
 Esempio di valore restituito di keyingMaterial:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 more bytes>
*/

Vedi la documentazione OpenSSL SSL_export_keying_material per maggiori informazioni.

tlsSocket.getCertificate()

Aggiunto in: v11.2.0

• Restituisce: <Object>

Restituisce un oggetto che rappresenta il certificato locale. L'oggetto restituito ha alcune proprietà corrispondenti ai campi del certificato.

Vedi tls.TLSSocket.getPeerCertificate() per un esempio della struttura del certificato.

Se non esiste un certificato locale, verrà restituito un oggetto vuoto. Se il socket è stato distrutto, verrà restituito null.

tlsSocket.getCipher()

[Cronologia]

Versione	Modifiche
v13.4.0, v12.16.0	Restituisce il nome del cifrario IETF come standardName.
v12.0.0	Restituisce la versione minima del cifrario, invece di una stringa fissa ('TLSv1/SSLv3').
v0.11.4	Aggiunto in: v0.11.4

• Restituisce: <Object>
  • name <string> Nome OpenSSL per la suite di crittografia.
  • standardName <string> Nome IETF per la suite di crittografia.
  • version <string> La versione minima del protocollo TLS supportata da questa suite di crittografia. Per il protocollo effettivamente negoziato, vedere tls.TLSSocket.getProtocol().

Restituisce un oggetto contenente informazioni sulla suite di crittografia negoziata.

Ad esempio, un protocollo TLSv1.2 con crittografia AES256-SHA:

{
  "name": "AES256-SHA",
  "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
  "version": "SSLv3"
}

Vedi SSL_CIPHER_get_name per maggiori informazioni.

tlsSocket.getEphemeralKeyInfo()

Aggiunto in: v5.0.0

• Restituisce: <Object>

Restituisce un oggetto che rappresenta il tipo, il nome e la dimensione del parametro di uno scambio di chiavi effimero nella perfect forward secrecy su una connessione client. Restituisce un oggetto vuoto quando lo scambio di chiavi non è effimero. Poiché questo è supportato solo su un socket client; null viene restituito se chiamato su un socket server. I tipi supportati sono 'DH' e 'ECDH'. La proprietà name è disponibile solo quando il tipo è 'ECDH'.

Ad esempio: { type: 'ECDH', name: 'prime256v1', size: 256 }.

tlsSocket.getFinished()

Aggiunto in: v9.9.0

• Restituisce: <Buffer> | <undefined> L'ultimo messaggio Finished inviato al socket come parte di una handshake SSL/TLS, o undefined se nessun messaggio Finished è stato ancora inviato.

Poiché i messaggi Finished sono digest dei messaggi dell'handshake completo (con un totale di 192 bit per TLS 1.0 e di più per SSL 3.0), possono essere utilizzati per procedure di autenticazione esterne quando l'autenticazione fornita da SSL/TLS non è desiderata o non è sufficiente.

Corrisponde alla routine SSL_get_finished in OpenSSL e può essere utilizzata per implementare il channel binding tls-unique da RFC 5929.

tlsSocket.getPeerCertificate([detailed])

Aggiunto in: v0.11.4

• detailed <boolean> Include l'intera catena di certificati se true, altrimenti include solo il certificato del peer.
• Restituisce: <Object> Un oggetto certificato.

Restituisce un oggetto che rappresenta il certificato del peer. Se il peer non fornisce un certificato, verrà restituito un oggetto vuoto. Se il socket è stato distrutto, verrà restituito null.

Se è stata richiesta l'intera catena di certificati, ogni certificato includerà una proprietà issuerCertificate contenente un oggetto che rappresenta il certificato del suo emittente.

Oggetto certificato

[Cronologia]

Versione	Modifiche
v19.1.0, v18.13.0	Aggiunta proprietà "ca".
v17.2.0, v16.14.0	Aggiunta fingerprint512.
v11.4.0	Supporto informazioni chiave pubblica a curva ellittica.

Un oggetto certificato ha proprietà corrispondenti ai campi del certificato.

• ca <boolean> true se un'Autorità di Certificazione (CA), false altrimenti.
• raw <Buffer> I dati del certificato X.509 codificati DER.
• subject <Object> Il soggetto del certificato, descritto in termini di Paese (C), Stato o Provincia (ST), Località (L), Organizzazione (O), Unità Organizzativa (OU) e Nome Comune (CN). Il Nome Comune è tipicamente un nome DNS con certificati TLS. Esempio: {C: 'UK', ST: 'BC', L: 'Metro', O: 'Node Fans', OU: 'Docs', CN: 'example.com'}.
• issuer <Object> L'emittente del certificato, descritto negli stessi termini del subject.
• valid_from <string> La data e l'ora da cui il certificato è valido.
• valid_to <string> La data e l'ora fino a cui il certificato è valido.
• serialNumber <string> Il numero seriale del certificato, come stringa esadecimale. Esempio: 'B9B0D332A1AA5635'.
• fingerprint <string> Il digest SHA-1 del certificato codificato DER. Viene restituito come stringa esadecimale separata da :. Esempio: '2A:7A:C2:DD:...'.
• fingerprint256 <string> Il digest SHA-256 del certificato codificato DER. Viene restituito come stringa esadecimale separata da :. Esempio: '2A:7A:C2:DD:...'.
• fingerprint512 <string> Il digest SHA-512 del certificato codificato DER. Viene restituito come stringa esadecimale separata da :. Esempio: '2A:7A:C2:DD:...'.
• ext_key_usage <Array> (Opzionale) L'utilizzo esteso della chiave, un insieme di OID.
• subjectaltname <string> (Opzionale) Una stringa contenente nomi concatenati per il soggetto, un'alternativa ai nomi subject.
• infoAccess <Array> (Opzionale) Una matrice che descrive AuthorityInfoAccess, utilizzata con OCSP.
• issuerCertificate <Object> (Opzionale) L'oggetto certificato dell'emittente. Per i certificati autofirmati, potrebbe trattarsi di un riferimento circolare.

Il certificato può contenere informazioni sulla chiave pubblica, a seconda del tipo di chiave.

Per le chiavi RSA, le seguenti proprietà possono essere definite:

• bits <number> La dimensione in bit di RSA. Esempio: 1024.
• exponent <string> L'esponente RSA, come stringa in notazione numerica esadecimale. Esempio: '0x010001'.
• modulus <string> Il modulo RSA, come stringa esadecimale. Esempio: 'B56CE45CB7...'.
• pubkey <Buffer> La chiave pubblica.

Per le chiavi EC, le seguenti proprietà possono essere definite:

• pubkey <Buffer> La chiave pubblica.
• bits <number> La dimensione della chiave in bit. Esempio: 256.
• asn1Curve <string> (Opzionale) Il nome ASN.1 dell'OID della curva ellittica. Le curve note sono identificate da un OID. Sebbene sia insolito, è possibile che la curva sia identificata dalle sue proprietà matematiche, nel qual caso non avrà un OID. Esempio: 'prime256v1'.
• nistCurve <string> (Opzionale) Il nome NIST per la curva ellittica, se ne ha uno (non a tutte le curve note sono stati assegnati nomi da NIST). Esempio: 'P-256'.

Esempio di certificato:

{ subject:
   { OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
     CN: '*.nodejs.org' },
  issuer:
   { C: 'GB',
     ST: 'Greater Manchester',
     L: 'Salford',
     O: 'COMODO CA Limited',
     CN: 'COMODO RSA Domain Validation Secure Server CA' },
  subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
  infoAccess:
   { 'CA Issuers - URI':
      [ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
     'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
  modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59D93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
  exponent: '0x10001',
  pubkey: <Buffer ... >,
  valid_from: 'Aug 14 00:00:00 2017 GMT',
  valid_to: 'Nov 20 23:59:59 2019 GMT',
  fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
  fingerprint256: '69:AE:1A:6A:D4:3D:C6:C1:1B:EA:C6:23:DE:BA:2A:14:62:62:93:5C:7A:EA:06:41:9B:0B:BC:87:CE:48:4E:02',
  fingerprint512: '19:2B:3E:C3:B3:5B:32:E8:AE:BB:78:97:27:E4:BA:6C:39:C9:92:79:4F:31:46:39:E2:70:E5:5F:89:42:17:C9:E8:64:CA:FF:BB:72:56:73:6E:28:8A:92:7E:A3:2A:15:8B:C2:E0:45:CA:C3:BC:EA:40:52:EC:CA:A2:68:CB:32',
  ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
  serialNumber: '66593D57F20CBC573E433381B5FEC280',
  raw: <Buffer ... > }

tlsSocket.getPeerFinished()

Aggiunto in: v9.9.0

• Restituisce: <Buffer> | <undefined> L'ultimo messaggio Finished previsto o effettivamente ricevuto dal socket come parte di una handshake SSL/TLS, oppure undefined se non c'è ancora alcun messaggio Finished.

Poiché i messaggi Finished sono digest dei messaggi dell'handshake completo (con un totale di 192 bit per TLS 1.0 e più per SSL 3.0), possono essere utilizzati per procedure di autenticazione esterne quando l'autenticazione fornita da SSL/TLS non è desiderata o non è sufficiente.

Corrisponde alla routine SSL_get_peer_finished in OpenSSL e può essere utilizzata per implementare il binding del canale tls-unique da RFC 5929.

tlsSocket.getPeerX509Certificate()

Aggiunto in: v15.9.0

• Restituisce: <X509Certificate>

Restituisce il certificato peer come oggetto <X509Certificate>.

Se non c'è alcun certificato peer, o se il socket è stato distrutto, verrà restituito undefined.

tlsSocket.getProtocol()

Aggiunto in: v5.7.0

• Restituisce: <string> | <null>

Restituisce una stringa contenente la versione del protocollo SSL/TLS negoziata della connessione corrente. Il valore 'unknown' verrà restituito per i socket connessi che non hanno completato il processo di handshake. Il valore null verrà restituito per i socket server o i socket client disconnessi.

Le versioni del protocollo sono:

• 'SSLv3'
• 'TLSv1'
• 'TLSv1.1'
• 'TLSv1.2'
• 'TLSv1.3'

Vedere la documentazione OpenSSL SSL_get_version per maggiori informazioni.

tlsSocket.getSession()

Aggiunto in: v0.11.4

• <Buffer>

Restituisce i dati della sessione TLS o undefined se nessuna sessione è stata negoziata. Sul client, i dati possono essere forniti all'opzione session di tls.connect() per riprendere la connessione. Sul server, può essere utile per il debug.

Vedere Ripristino della sessione per maggiori informazioni.

Nota: getSession() funziona solo per TLSv1.2 e versioni precedenti. Per TLSv1.3, le applicazioni devono utilizzare l'evento 'session' (funziona anche per TLSv1.2 e versioni precedenti).

tlsSocket.getSharedSigalgs()

Aggiunto in: v12.11.0

• Restituisce: <Array> Elenco degli algoritmi di firma condivisi tra il server e il client in ordine di preferenza decrescente.

Vedi SSL_get_shared_sigalgs per maggiori informazioni.

tlsSocket.getTLSTicket()

Aggiunto in: v0.11.4

• <Buffer>

Per un client, restituisce il ticket di sessione TLS se disponibile, altrimenti undefined. Per un server, restituisce sempre undefined.

Può essere utile per il debug.

Vedi Ripristino Sessione per maggiori informazioni.

tlsSocket.getX509Certificate()

Aggiunto in: v15.9.0

• Restituisce: <X509Certificate>

Restituisce il certificato locale come oggetto <X509Certificate>.

Se non c'è alcun certificato locale, o se il socket è stato distrutto, verrà restituito undefined.

tlsSocket.isSessionReused()

Aggiunto in: v0.5.6

• Restituisce: <boolean> true se la sessione è stata riutilizzata, false altrimenti.

Vedi Ripristino Sessione per maggiori informazioni.

tlsSocket.localAddress

Aggiunto in: v0.11.4

• <string>

Restituisce la rappresentazione stringa dell'indirizzo IP locale.

tlsSocket.localPort

Aggiunto in: v0.11.4

• <integer>

Restituisce la rappresentazione numerica della porta locale.

tlsSocket.remoteAddress

Aggiunto in: v0.11.4

• <string>

Restituisce la rappresentazione stringa dell'indirizzo IP remoto. Per esempio, '74.125.127.100' o '2001:4860:a005::68'.

tlsSocket.remoteFamily

Aggiunto in: v0.11.4

• <string>

Restituisce la rappresentazione stringa della famiglia IP remota. 'IPv4' o 'IPv6'.

tlsSocket.remotePort

Aggiunto in: v0.11.4

• <integer>

Restituisce la rappresentazione numerica della porta remota. Ad esempio, 443.

tlsSocket.renegotiate(options, callback)

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v0.11.8	Aggiunto in: v0.11.8

• options <Object>

  • rejectUnauthorized <boolean> Se non false, il certificato del server viene verificato rispetto all'elenco delle CA fornite. Viene emesso un evento 'error' se la verifica non riesce; err.code contiene il codice di errore OpenSSL. Predefinito: true.
  • requestCert

• callback <Function> Se renegotiate() restituisce true, il callback viene associato una sola volta all'evento 'secure'. Se renegotiate() restituisce false, callback verrà chiamato nel tick successivo con un errore, a meno che tlsSocket non sia stato distrutto, nel qual caso callback non verrà chiamato affatto.

• Restituisce: <boolean> true se la rinegoziazione è stata avviata, false altrimenti.

Il metodo tlsSocket.renegotiate() avvia un processo di rinegoziazione TLS. Al completamento, alla funzione callback verrà passato un singolo argomento che è un Error (se la richiesta ha avuto esito negativo) o null.

Questo metodo può essere utilizzato per richiedere il certificato di un peer dopo che la connessione sicura è stata stabilita.

Quando viene eseguito come server, il socket verrà distrutto con un errore dopo il timeout handshakeTimeout.

Per TLSv1.3, la rinegoziazione non può essere avviata, non è supportata dal protocollo.

tlsSocket.setKeyCert(context)

Aggiunto in: v22.5.0, v20.17.0

• context <Oggetto> | <tls.SecureContext> Un oggetto contenente almeno le proprietà key e cert dalle opzioni tls.createSecureContext(), o un oggetto contesto TLS creato con tls.createSecureContext() stesso.

Il metodo tlsSocket.setKeyCert() imposta la chiave privata e il certificato da utilizzare per il socket. Questo è principalmente utile se si desidera selezionare un certificato server da un ALPNCallback di un server TLS.

tlsSocket.setMaxSendFragment(size)

Aggiunto in: v0.11.11

• size <numero> La dimensione massima del frammento TLS. Il valore massimo è 16384. Predefinito: 16384.
• Restituisce: <booleano>

Il metodo tlsSocket.setMaxSendFragment() imposta la dimensione massima del frammento TLS. Restituisce true se l'impostazione del limite ha avuto successo; false altrimenti.

Dimensioni di frammento più piccole riducono la latenza di buffering sul client: i frammenti più grandi vengono memorizzati nel buffer dal livello TLS fino a quando l'intero frammento non viene ricevuto e la sua integrità viene verificata; i frammenti grandi possono estendersi su più round trip e la loro elaborazione può essere ritardata a causa di perdita di pacchetti o riordino. Tuttavia, i frammenti più piccoli aggiungono byte di framing TLS extra e overhead della CPU, che possono ridurre la produttività complessiva del server.

tls.checkServerIdentity(hostname, cert)

[Cronologia]

Versione	Modifiche
v17.3.1, v16.13.2, v14.18.3, v12.22.9	Il supporto per i nomi alternativi del soggetto uniformResourceIdentifier è stato disabilitato in risposta a CVE-2021-44531.
v0.8.4	Aggiunto in: v0.8.4

• hostname <stringa> Il nome host o l'indirizzo IP da verificare rispetto al certificato.
• cert <Oggetto> Un oggetto certificato che rappresenta il certificato del peer.
• Restituisce: <Errore> | <non definito>

Verifica che il certificato cert sia rilasciato a hostname.

Restituisce un oggetto <Errore>, popolandolo con reason, host e cert in caso di errore. In caso di successo, restituisce <non definito>.

Questa funzione è destinata all'uso in combinazione con l'opzione checkServerIdentity che può essere passata a tls.connect() e come tale opera su un oggetto certificato. Per altri scopi, si consideri invece l'utilizzo di x509.checkHost().

Questa funzione può essere sovrascritta fornendo una funzione alternativa come opzione options.checkServerIdentity che viene passata a tls.connect(). La funzione di sovrascrittura può chiamare tls.checkServerIdentity() naturalmente, per aumentare i controlli eseguiti con verifiche aggiuntive.

Questa funzione viene chiamata solo se il certificato ha superato tutti gli altri controlli, come l'emissione da parte di un'autorità di certificazione attendibile (options.ca).

Le versioni precedenti di Node.js accettavano erroneamente i certificati per un dato hostname se era presente un nome alternativo del soggetto uniformResourceIdentifier corrispondente (vedere CVE-2021-44531). Le applicazioni che desiderano accettare nomi alternativi del soggetto uniformResourceIdentifier possono utilizzare una funzione personalizzata options.checkServerIdentity che implementa il comportamento desiderato.

tls.connect(options[, callback])

[Cronologia]

Versione	Modifiche
v15.1.0, v14.18.0	Aggiunta opzione onread.
v14.1.0, v13.14.0	L'opzione highWaterMark è ora accettata.
v13.6.0, v12.16.0	L'opzione pskCallback è ora supportata.
v12.9.0	Supporto dell'opzione allowHalfOpen.
v12.4.0	L'opzione hints è ora supportata.
v12.2.0	L'opzione enableTrace è ora supportata.
v11.8.0, v10.16.0	L'opzione timeout è ora supportata.
v8.0.0	L'opzione lookup è ora supportata.
v8.0.0	L'opzione ALPNProtocols può ora essere un TypedArray o un DataView.
v5.0.0	Le opzioni ALPN sono ora supportate.
v5.3.0, v4.7.0	L'opzione secureContext è ora supportata.
v0.11.3	Aggiunta in: v0.11.3

• options <Oggetto>

  • enableTrace: Vedi tls.createServer()
  • host <stringa> Host a cui il client dovrebbe connettersi. Default: 'localhost'.
  • port <numero> Porta a cui il client dovrebbe connettersi.
  • path <stringa> Crea una connessione socket Unix al percorso. Se questa opzione è specificata, host e port vengono ignorati.
  • socket <stream.Duplex> Stabilisce una connessione sicura su un socket dato invece di creare un nuovo socket. Tipicamente, questa è un'istanza di net.Socket, ma è consentito qualsiasi stream Duplex. Se questa opzione è specificata, path, host e port vengono ignorati, tranne per la convalida del certificato. Solitamente, un socket è già connesso quando viene passato a tls.connect(), ma può essere connesso in seguito. La connessione/disconnessione/distruzione di socket è responsabilità dell'utente; la chiamata a tls.connect() non causerà la chiamata a net.connect().
  • allowHalfOpen <booleano> Se impostato su false, il socket terminerà automaticamente il lato scrivibile quando il lato leggibile termina. Se l'opzione socket è impostata, questa opzione non ha effetto. Vedi l'opzione allowHalfOpen di net.Socket per i dettagli. Default: false.
  • rejectUnauthorized <booleano> Se non false, il certificato del server viene verificato rispetto all'elenco delle CA fornite. Viene emesso un evento 'error' se la verifica fallisce; err.code contiene il codice di errore OpenSSL. Default: true.
  • pskCallback <Funzione> Per la negoziazione TLS-PSK, vedi Chiavi pre-concordi.
  • ALPNProtocols: <stringa[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Una matrice di stringhe, Buffer, TypedArray o DataView, o un singolo Buffer, TypedArray o DataView contenente i protocolli ALPN supportati. I Buffer dovrebbero avere il formato [len][name][len][name]... es. '\x08http/1.1\x08http/1.0', dove il byte len è la lunghezza del successivo nome del protocollo. Passare una matrice è generalmente molto più semplice, es. ['http/1.1', 'http/1.0']. I protocolli all'inizio dell'elenco hanno una priorità maggiore rispetto a quelli successivi.
  • servername: <stringa> Nome del server per l'estensione TLS SNI (Server Name Indication). È il nome dell'host a cui ci si sta connettendo e deve essere un nome host, non un indirizzo IP. Può essere utilizzato da un server multi-home per scegliere il certificato corretto da presentare al client, vedere l'opzione SNICallback di tls.createServer().
  • checkServerIdentity(servername, cert) <Funzione> Una funzione di callback da utilizzare (invece della funzione predefinita tls.checkServerIdentity()) quando si verifica il nome host del server (o il servername fornito quando impostato esplicitamente) rispetto al certificato. Questo dovrebbe restituire un <Errore> se la verifica fallisce. Il metodo dovrebbe restituire undefined se servername e cert sono verificati.
  • session <Buffer> Un'istanza Buffer, contenente la sessione TLS.
  • minDHSize <numero> Dimensione minima del parametro DH in bit per accettare una connessione TLS. Quando un server offre un parametro DH con una dimensione inferiore a minDHSize, la connessione TLS viene distrutta e viene generato un errore. Default: 1024.
  • highWaterMark: <numero> Coerente con il parametro highWaterMark dello stream leggibile. Default: 16 * 1024.
  • secureContext: Oggetto contesto TLS creato con tls.createSecureContext(). Se un secureContext non viene fornito, ne verrà creato uno passando l'intero oggetto options a tls.createSecureContext().
  • onread <Oggetto> Se l'opzione socket è mancante, i dati in arrivo vengono memorizzati in un singolo buffer e passati alla callback fornita quando i dati arrivano sul socket, altrimenti l'opzione viene ignorata. Vedi l'opzione onread di net.Socket per i dettagli.
  • ...: opzioni tls.createSecureContext() che vengono utilizzate se l'opzione secureContext è mancante, altrimenti vengono ignorate.
  • ...: Qualsiasi opzione socket.connect() non ancora elencata.

• callback <Funzione>

• Restituisce: <tls.TLSSocket>

La funzione callback, se specificata, verrà aggiunta come listener per l'evento 'secureConnect'.

tls.connect() restituisce un oggetto tls.TLSSocket.

A differenza dell'API https, tls.connect() non abilita l'estensione SNI (Server Name Indication) per impostazione predefinita, il che potrebbe causare il ritorno di un certificato errato da parte di alcuni server o il rifiuto completo della connessione. Per abilitare SNI, impostare l'opzione servername oltre a host.

Di seguito è illustrato un client per l'esempio del server echo da tls.createServer():

ESM

// Presuppone un server echo in ascolto sulla porta 8000.
import { connect } from 'node:tls'
import { readFileSync } from 'node:fs'
import { stdin } from 'node:process'

const options = {
  // Necessario solo se il server richiede l'autenticazione del certificato client.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // Necessario solo se il server utilizza un certificato autofirmato.
  ca: [readFileSync('server-cert.pem')],

  // Necessario solo se il certificato del server non è per "localhost".
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('client connesso', socket.authorized ? 'autorizzato' : 'non autorizzato')
  stdin.pipe(socket)
  stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('il server termina la connessione')
})

CJS

// Presuppone un server echo in ascolto sulla porta 8000.
const { connect } = require('node:tls')
const { readFileSync } = require('node:fs')

const options = {
  // Necessario solo se il server richiede l'autenticazione del certificato client.
  key: readFileSync('client-key.pem'),
  cert: readFileSync('client-cert.pem'),

  // Necessario solo se il server utilizza un certificato autofirmato.
  ca: [readFileSync('server-cert.pem')],

  // Necessario solo se il certificato del server non è per "localhost".
  checkServerIdentity: () => {
    return null
  },
}

const socket = connect(8000, options, () => {
  console.log('client connesso', socket.authorized ? 'autorizzato' : 'non autorizzato')
  process.stdin.pipe(socket)
  process.stdin.resume()
})
socket.setEncoding('utf8')
socket.on('data', data => {
  console.log(data)
})
socket.on('end', () => {
  console.log('il server termina la connessione')
})

Per generare il certificato e la chiave per questo esempio, eseguire:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout client-key.pem -out client-cert.pem

Quindi, per generare il certificato server-cert.pem per questo esempio, eseguire:

openssl pkcs12 -certpbe AES-256-CBC -export -out server-cert.pem \
  -inkey client-key.pem -in client-cert.pem

tls.connect(path[, options][, callback])

Aggiunto in: v0.11.3

• path <string> Valore predefinito per options.path.
• options <Object> Vedi tls.connect().
• callback <Function> Vedi tls.connect().
• Restituisce: <tls.TLSSocket>

Stesso di tls.connect() eccetto che path può essere fornito come argomento invece che come opzione.

Un'opzione path, se specificata, avrà la precedenza sull'argomento path.

tls.connect(port[, host][, options][, callback])

Aggiunto in: v0.11.3

• port <number> Valore predefinito per options.port.
• host <string> Valore predefinito per options.host.
• options <Object> Vedi tls.connect().
• callback <Function> Vedi tls.connect().
• Restituisce: <tls.TLSSocket>

Stesso di tls.connect() eccetto che port e host possono essere forniti come argomenti invece che come opzioni.

Un'opzione port o host, se specificata, avrà la precedenza su qualsiasi argomento port o host.

tls.createSecureContext([options])

[Cronologia]

Versione	Modifiche
v22.9.0, v20.18.0	È stata aggiunta l'opzione allowPartialTrustChain.
v22.4.0, v20.16.0	Le opzioni clientCertEngine, privateKeyEngine e privateKeyIdentifier dipendono dal supporto del motore personalizzato in OpenSSL, che è deprecato in OpenSSL 3.
v19.8.0, v18.16.0	L'opzione dhparam può ora essere impostata su 'auto' per abilitare DHE con parametri noti appropriati.
v12.12.0	Aggiunte le opzioni privateKeyIdentifier e privateKeyEngine per ottenere la chiave privata da un motore OpenSSL.
v12.11.0	Aggiunta l'opzione sigalgs per sovrascrivere gli algoritmi di firma supportati.
v12.0.0	Aggiunto supporto TLSv1.3.
v11.5.0	L'opzione ca: ora supporta BEGIN TRUSTED CERTIFICATE.
v11.4.0, v10.16.0	minVersion e maxVersion possono essere utilizzati per limitare le versioni del protocollo TLS consentite.
v10.0.0	ecdhCurve non può più essere impostato su false a causa di una modifica in OpenSSL.
v9.3.0	Il parametro options può ora includere clientCertEngine.
v9.0.0	L'opzione ecdhCurve può ora essere costituita da più nomi di curve separati da ':' o da 'auto'.
v7.3.0	Se l'opzione key è una matrice, le singole voci non hanno più bisogno di una proprietà passphrase. Le voci Array possono ora essere anche solo stringhe o Buffer.
v5.2.0	L'opzione ca può ora essere una singola stringa contenente più certificati CA.
v0.11.13	Aggiunto in: v0.11.13

• options <Object>
  • allowPartialTrustChain <boolean> Tratta i certificati intermedi (non autofirmati) nell'elenco dei certificati CA attendibili come attendibili.
  • ca <string> | <string[]> | <Buffer> | <Buffer[]> Sovrascrivi facoltativamente i certificati CA attendibili. Il valore predefinito è quello di fidarsi delle CA note curate da Mozilla. Le CA di Mozilla vengono completamente sostituite quando le CA sono specificate esplicitamente usando questa opzione. Il valore può essere una stringa o un Buffer, o una Array di stringhe e/o Buffer. Qualsiasi stringa o Buffer può contenere più CA PEM concatenati insieme. Il certificato del peer deve essere concatenabile a una CA attendibile dal server affinché la connessione venga autenticata. Quando si utilizzano certificati che non sono concatenabili a una CA nota, la CA del certificato deve essere specificata esplicitamente come attendibile o la connessione non riuscirà ad autenticarsi. Se il peer utilizza un certificato che non corrisponde o non è concatenabile a una delle CA predefinite, utilizzare l'opzione ca per fornire un certificato CA a cui il certificato del peer può corrispondere o concatenarsi. Per i certificati autofirmati, il certificato è la sua stessa CA e deve essere fornito. Per i certificati codificati PEM, i tipi supportati sono "TRUSTED CERTIFICATE", "X509 CERTIFICATE" e "CERTIFICATE". Vedi anche tls.rootCertificates.
  • cert <string> | <string[]> | <Buffer> | <Buffer[]> Catene di certificati in formato PEM. Una catena di certificati deve essere fornita per ogni chiave privata. Ogni catena di certificati deve essere composta dal certificato in formato PEM per una chiave privata fornita, seguita dai certificati intermedi in formato PEM (se presenti), in ordine, e non includere la CA radice (la CA radice deve essere pre-nota al peer, vedere ca). Quando si forniscono più catene di certificati, non è necessario che siano nello stesso ordine delle loro chiavi private in key. Se i certificati intermedi non vengono forniti, il peer non sarà in grado di convalidare il certificato e la handshake fallirà.
  • sigalgs <string> Elenco separato da due punti di algoritmi di firma supportati. L'elenco può contenere algoritmi di digest (SHA256, MD5 ecc.), algoritmi di chiave pubblica (RSA-PSS, ECDSA ecc.), combinazione di entrambi (es. 'RSA+SHA384') o nomi di schemi TLS v1.3 (es. rsa_pss_pss_sha512). Vedere le pagine man di OpenSSL per maggiori informazioni.
  • ciphers <string> Specifica della suite di cifratura, sostituendo quella predefinita. Per ulteriori informazioni, vedere Modifica della suite di cifratura TLS predefinita. Le cifre consentite possono essere ottenute tramite tls.getCiphers(). I nomi delle cifre devono essere in maiuscolo affinché OpenSSL li accetti.
  • clientCertEngine <string> Nome di un motore OpenSSL che può fornire il certificato client. Deprecato.
  • crl <string> | <string[]> | <Buffer> | <Buffer[]> CRL (Certificate Revocation Lists) in formato PEM.
  • dhparam <string> | <Buffer> 'auto' o parametri Diffie-Hellman personalizzati, necessari per la non-ECDHE perfect forward secrecy. Se omesso o non valido, i parametri vengono silenziosamente scartati e le cifre DHE non saranno disponibili. La ECDHE-based perfect forward secrecy sarà comunque disponibile.
  • ecdhCurve <string> Una stringa che descrive una curva nominata o un elenco di NID o nomi di curve separati da due punti, ad esempio P-521:P-384:P-256, da utilizzare per l'accordo chiave ECDH. Impostato su auto per selezionare automaticamente la curva. Utilizzare crypto.getCurves() per ottenere un elenco di nomi di curve disponibili. Nelle versioni recenti, openssl ecparam -list_curves mostrerà anche il nome e la descrizione di ogni curva ellittica disponibile. Predefinito: tls.DEFAULT_ECDH_CURVE.
  • honorCipherOrder <boolean> Tenta di utilizzare le preferenze della suite di cifratura del server invece di quelle del client. Quando true, fa sì che SSL_OP_CIPHER_SERVER_PREFERENCE venga impostato in secureOptions, vedere Opzioni OpenSSL per ulteriori informazioni.
  • key <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> Chiavi private in formato PEM. PEM consente l'opzione di chiavi private crittografate. Le chiavi crittografate verranno decrittografate con options.passphrase. È possibile fornire più chiavi che utilizzano algoritmi diversi come una matrice di stringhe o buffer di chiavi non crittografate, oppure una matrice di oggetti nel formato {pem: \<string|buffer\>[, passphrase: \<string\>]}. La forma dell'oggetto può verificarsi solo in una matrice. object.passphrase è facoltativo. Le chiavi crittografate verranno decrittografate con object.passphrase se fornito, o con options.passphrase se non lo è.
  • privateKeyEngine <string> Nome di un motore OpenSSL da cui ottenere la chiave privata. Dovrebbe essere utilizzato insieme a privateKeyIdentifier. Deprecato.
  • privateKeyIdentifier <string> Identificatore di una chiave privata gestita da un motore OpenSSL. Dovrebbe essere utilizzato insieme a privateKeyEngine. Non dovrebbe essere impostato insieme a key, perché entrambe le opzioni definiscono una chiave privata in modi diversi. Deprecato.
  • maxVersion <string> Imposta facoltativamente la versione TLS massima da consentire. Uno tra 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' o 'TLSv1'. Non può essere specificato insieme all'opzione secureProtocol; utilizzare l'uno o l'altro. Predefinito: tls.DEFAULT_MAX_VERSION.
  • minVersion <string> Imposta facoltativamente la versione TLS minima da consentire. Uno tra 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' o 'TLSv1'. Non può essere specificato insieme all'opzione secureProtocol; utilizzare l'uno o l'altro. Evitare di impostare valori inferiori a TLSv1.2, ma potrebbe essere necessario per l'interoperabilità. Le versioni precedenti a TLSv1.2 potrebbero richiedere il downgrade del Livello di sicurezza OpenSSL. Predefinito: tls.DEFAULT_MIN_VERSION.
  • passphrase <string> Passphrase condivisa utilizzata per una singola chiave privata e/o un PFX.
  • pfx <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> Chiave privata e catena di certificati codificati PFX o PKCS12. pfx è un'alternativa alla fornitura di key e cert individualmente. PFX è di solito crittografato, se lo è, passphrase verrà utilizzato per decrittografarlo. È possibile fornire più PFX come una matrice di buffer PFX non crittografati, oppure una matrice di oggetti nel formato {buf: \<string|buffer\>[, passphrase: \<string\>]}. La forma dell'oggetto può verificarsi solo in una matrice. object.passphrase è facoltativo. I PFX crittografati verranno decrittografati con object.passphrase se fornito, o con options.passphrase se non lo è.
  • secureOptions <number> Influisce facoltativamente sul comportamento del protocollo OpenSSL, che di solito non è necessario. Questo dovrebbe essere usato con cautela, se non del tutto! Il valore è una maschera di bit numerica delle opzioni SSL_OP_* da Opzioni OpenSSL.
  • secureProtocol <string> Meccanismo legacy per selezionare la versione del protocollo TLS da utilizzare, non supporta il controllo indipendente della versione minima e massima e non supporta la limitazione del protocollo a TLSv1.3. Utilizzare invece minVersion e maxVersion. I possibili valori sono elencati come SSL_METHODS, utilizzare i nomi delle funzioni come stringhe. Ad esempio, utilizzare 'TLSv1_1_method' per forzare la versione TLS 1.1, o 'TLS_method' per consentire qualsiasi versione del protocollo TLS fino a TLSv1.3. Non è consigliabile utilizzare versioni TLS inferiori a 1.2, ma potrebbe essere necessario per l'interoperabilità. Predefinito: nessuno, vedere minVersion.
  • sessionIdContext <string> Identificatore opaco utilizzato dai server per garantire che lo stato della sessione non venga condiviso tra le applicazioni. Non utilizzato dai client.
  • ticketKeys: <Buffer> 48 byte di dati pseudocasuali crittograficamente forti. Vedere Ripristino della sessione per ulteriori informazioni.
  • sessionTimeout <number> Il numero di secondi dopo il quale una sessione TLS creata dal server non sarà più ripristinabile. Vedere Ripristino della sessione per ulteriori informazioni. Predefinito: 300.

tls.createServer() imposta il valore predefinito dell'opzione honorCipherOrder su true, altre API che creano contesti sicuri lo lasciano impostato.

tls.createServer() utilizza un valore hash SHA1 troncato a 128 bit generato da process.argv come valore predefinito dell'opzione sessionIdContext, altre API che creano contesti sicuri non hanno alcun valore predefinito.

Il metodo tls.createSecureContext() crea un oggetto SecureContext. Può essere utilizzato come argomento per diverse API tls, come server.addContext(), ma non ha metodi pubblici. Il costruttore tls.Server e il metodo tls.createServer() non supportano l'opzione secureContext.

Una chiave è necessaria per le cifre che utilizzano certificati. È possibile utilizzare key o pfx per fornirla.

Se l'opzione ca non è fornita, Node.js utilizzerà per impostazione predefinita l'elenco di CA pubblicamente attendibili di Mozilla.

I parametri DHE personalizzati sono sconsigliati a favore della nuova opzione dhparam: 'auto'. Quando impostato su 'auto', verranno selezionati automaticamente parametri DHE noti di forza sufficiente. Altrimenti, se necessario, è possibile utilizzare openssl dhparam per creare parametri personalizzati. La lunghezza della chiave deve essere maggiore o uguale a 1024 bit oppure verrà generato un errore. Sebbene siano consentiti 1024 bit, utilizzare 2048 bit o superiori per una maggiore sicurezza.

tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])

[Cronologia]

Versione	Modifiche
v5.0.0	Ora sono supportate le opzioni ALPN.
v0.11.3	Obsoleto da: v0.11.3
v0.3.2	Aggiunto in: v0.3.2

[Stabile: 0 - Obsoleto]

Stabile: 0 Stabilità: 0 - Obsoleto: Utilizzare tls.TLSSocket invece.

• context <Oggetto> Un oggetto contesto sicuro come restituito da tls.createSecureContext()
• isServer <booleano> true per specificare che questa connessione TLS dovrebbe essere aperta come server.
• requestCert <booleano> true per specificare se un server dovrebbe richiedere un certificato da un client in connessione. Si applica solo quando isServer è true.
• rejectUnauthorized <booleano> Se non false, un server rifiuta automaticamente i client con certificati non validi. Si applica solo quando isServer è true.
• options
  • enableTrace: Vedi tls.createServer()
  • secureContext: Un oggetto contesto TLS da tls.createSecureContext()
  • isServer: Se true il socket TLS verrà istanziato in modalità server. Predefinito: false.
  • server <net.Server> Un'istanza net.Server
  • requestCert: Vedi tls.createServer()
  • rejectUnauthorized: Vedi tls.createServer()
  • ALPNProtocols: Vedi tls.createServer()
  • SNICallback: Vedi tls.createServer()
  • session <Buffer> Un'istanza Buffer contenente una sessione TLS.
  • requestOCSP <booleano> Se true, specifica che l'estensione di richiesta di stato OCSP verrà aggiunta al client hello e un evento 'OCSPResponse' verrà emesso sul socket prima di stabilire una comunicazione sicura.

Crea un nuovo oggetto coppia sicura con due stream, uno dei quali legge e scrive i dati crittografati e l'altro legge e scrive i dati in chiaro. In generale, lo stream crittografato viene collegato a/da uno stream di dati crittografati in arrivo e quello in chiaro viene utilizzato come sostituzione dello stream crittografato iniziale.

tls.createSecurePair() restituisce un oggetto tls.SecurePair con le proprietà dello stream cleartext e encrypted.

L'utilizzo di cleartext ha la stessa API di tls.TLSSocket.

Il metodo tls.createSecurePair() è ora deprecato a favore di tls.TLSSocket(). Ad esempio, il codice:

pair = tls.createSecurePair(/* ... */)
pair.encrypted.pipe(socket)
socket.pipe(pair.encrypted)

può essere sostituito da:

secureSocket = tls.TLSSocket(socket, options)

dove secureSocket ha la stessa API di pair.cleartext.

tls.createServer([options][, secureConnectionListener])

[Cronologia]

Versione	Modifiche
v22.4.0, v20.16.0	L'opzione clientCertEngine dipende dal supporto del motore personalizzato in OpenSSL, che è deprecato in OpenSSL 3.
v19.0.0	Se ALPNProtocols è impostato, le connessioni in arrivo che inviano un'estensione ALPN senza protocolli supportati vengono terminate con un avviso fatale no_application_protocol.
v20.4.0, v18.19.0	Il parametro options ora può includere ALPNCallback.
v12.3.0	Il parametro options ora supporta le opzioni net.createServer().
v9.3.0	Il parametro options ora può includere clientCertEngine.
v8.0.0	L'opzione ALPNProtocols può ora essere un TypedArray o DataView.
v5.0.0	Ora sono supportate le opzioni ALPN.
v0.3.2	Aggiunto in: v0.3.2

• options <Oggetto>

  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Una matrice di stringhe, Buffer, TypedArray o DataView, o un singolo Buffer, TypedArray o DataView contenente i protocolli ALPN supportati. I Buffer dovrebbero avere il formato [len][name][len][name]... es. 0x05hello0x05world, dove il primo byte è la lunghezza del successivo nome del protocollo. Passare una matrice è generalmente molto più semplice, es. ['hello', 'world']. (I protocolli devono essere ordinati in base alla loro priorità.)
  • ALPNCallback: <Funzione> Se impostato, questo verrà chiamato quando un client apre una connessione usando l'estensione ALPN. Un argomento verrà passato alla callback: un oggetto contenente i campi servername e protocols, rispettivamente contenenti il nome del server dall'estensione SNI (se presente) e una matrice di stringhe con i nomi dei protocolli ALPN. La callback deve restituire una delle stringhe elencate in protocols, che verrà restituita al client come protocollo ALPN selezionato, oppure undefined, per rifiutare la connessione con un avviso fatale. Se viene restituita una stringa che non corrisponde a uno dei protocolli ALPN del client, verrà generato un errore. Questa opzione non può essere utilizzata con l'opzione ALPNProtocols, e l'impostazione di entrambe le opzioni genererà un errore.
  • clientCertEngine <stringa> Nome di un motore OpenSSL che può fornire il certificato client. Deprecato.
  • enableTrace <booleano> Se true, tls.TLSSocket.enableTrace() verrà chiamato sulle nuove connessioni. Il tracing può essere abilitato dopo che la connessione sicura è stata stabilita, ma questa opzione deve essere utilizzata per tracciare l'impostazione della connessione sicura. Default: false.
  • handshakeTimeout <numero> Interrompe la connessione se la handshake SSL/TLS non termina nel numero di millisecondi specificato. Un 'tlsClientError' viene emesso sull'oggetto tls.Server ogni volta che una handshake si interrompe. Default: 120000 (120 secondi).
  • rejectUnauthorized <booleano> Se non false il server rifiuterà qualsiasi connessione che non sia autorizzata con l'elenco delle CA fornite. Questa opzione ha effetto solo se requestCert è true. Default: true.
  • requestCert <booleano> Se true il server richiederà un certificato dai client che si connettono e tenterà di verificare tale certificato. Default: false.
  • sessionTimeout <numero> Il numero di secondi dopo il quale una sessione TLS creata dal server non sarà più ripristinabile. Vedi Ripristino della sessione per maggiori informazioni. Default: 300.
  • SNICallback(servername, callback) <Funzione> Una funzione che verrà chiamata se il client supporta l'estensione SNI TLS. Due argomenti verranno passati quando viene chiamata: servername e callback. callback è una callback error-first che accetta due argomenti opzionali: error e ctx. ctx, se fornito, è un'istanza SecureContext. tls.createSecureContext() può essere utilizzato per ottenere un SecureContext appropriato. Se callback viene chiamato con un argomento ctx falso, verrà utilizzato il contesto sicuro predefinito del server. Se SNICallback non è stato fornito, verrà utilizzata la callback predefinita con API di alto livello (vedi sotto).
  • ticketKeys: <Buffer> 48 byte di dati pseudocasuali crittograficamente forti. Vedi Ripristino della sessione per maggiori informazioni.
  • pskCallback <Funzione> Per la negoziazione TLS-PSK, vedi Chiavi pre-condivisi.
  • pskIdentityHint <stringa> suggerimento opzionale da inviare a un client per aiutare nella selezione dell'identità durante la negoziazione TLS-PSK. Verrà ignorato in TLS 1.3. In caso di errore nell'impostazione di pskIdentityHint, verrà emesso 'tlsClientError' con il codice 'ERR_TLS_PSK_SET_IDENTITY_HINT_FAILED'.
  • ...: Qualsiasi opzione tls.createSecureContext() può essere fornita. Per i server, le opzioni di identità (pfx, key/cert, o pskCallback) sono generalmente richieste.
  • ...: Qualsiasi opzione net.createServer() può essere fornita.

• secureConnectionListener <Funzione>

• Restituisce: <tls.Server>

Crea un nuovo tls.Server. Il secureConnectionListener, se fornito, è automaticamente impostato come listener per l'evento 'secureConnection'.

L'opzione ticketKeys è automaticamente condivisa tra i worker del modulo node:cluster.

L'esempio seguente illustra un semplice server echo:

ESM

import { createServer } from 'node:tls'
import { readFileSync } from 'node:fs'

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),

  // Questo è necessario solo se si utilizza l'autenticazione del certificato client.
  requestCert: true,

  // Questo è necessario solo se il client utilizza un certificato autofirmato.
  ca: [readFileSync('client-cert.pem')],
}

const server = createServer(options, socket => {
  console.log('server connesso', socket.authorized ? 'autorizzato' : 'non autorizzato')
  socket.write('benvenuto!\n')
  socket.setEncoding('utf8')
  socket.pipe(socket)
})
server.listen(8000, () => {
  console.log('server associato')
})

CJS

const { createServer } = require('node:tls')
const { readFileSync } = require('node:fs')

const options = {
  key: readFileSync('server-key.pem'),
  cert: readFileSync('server-cert.pem'),

  // Questo è necessario solo se si utilizza l'autenticazione del certificato client.
  requestCert: true,

  // Questo è necessario solo se il client utilizza un certificato autofirmato.
  ca: [readFileSync('client-cert.pem')],
}

const server = createServer(options, socket => {
  console.log('server connesso', socket.authorized ? 'autorizzato' : 'non autorizzato')
  socket.write('benvenuto!\n')
  socket.setEncoding('utf8')
  socket.pipe(socket)
})
server.listen(8000, () => {
  console.log('server associato')
})

Per generare il certificato e la chiave per questo esempio, eseguire:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout server-key.pem -out server-cert.pem

Quindi, per generare il certificato client-cert.pem per questo esempio, eseguire:

openssl pkcs12 -certpbe AES-256-CBC -export -out client-cert.pem \
  -inkey server-key.pem -in server-cert.pem

Il server può essere testato connettendosi ad esso usando il client di esempio da tls.connect().

tls.getCiphers()

Aggiunto in: v0.10.2

• Restituisce: <string[]>

Restituisce una matrice con i nomi delle cipher TLS supportate. I nomi sono in minuscolo per motivi storici, ma devono essere convertiti in maiuscolo per essere utilizzati nell'opzione ciphers di tls.createSecureContext().

Non tutte le cipher supportate sono abilitate per impostazione predefinita. Vedi Modifica della suite di cipher TLS predefinita.

I nomi delle cipher che iniziano con 'tls_' sono per TLSv1.3, tutti gli altri sono per TLSv1.2 e versioni precedenti.

console.log(tls.getCiphers()) // ['aes128-gcm-sha256', 'aes128-sha', ...]

tls.rootCertificates

Aggiunto in: v12.3.0

• <string[]>

Una matrice immutabile di stringhe che rappresentano i certificati radice (in formato PEM) dall'archivio CA Mozilla incluso nella versione corrente di Node.js.

L'archivio CA incluso, fornito da Node.js, è un'istantanea dell'archivio CA Mozilla che è fissata al momento del rilascio. È identico su tutte le piattaforme supportate.

tls.DEFAULT_ECDH_CURVE

[Cronologia]

Versione	Modifiche
v10.0.0	Valore predefinito modificato in 'auto'.
v0.11.13	Aggiunto in: v0.11.13

Il nome della curva predefinita da utilizzare per l'accordo chiave ECDH in un server tls. Il valore predefinito è 'auto'. Vedi tls.createSecureContext() per ulteriori informazioni.

tls.DEFAULT_MAX_VERSION

Aggiunto in: v11.4.0

• <string> Il valore predefinito dell'opzione maxVersion di tls.createSecureContext(). Può essere assegnata una qualsiasi delle versioni del protocollo TLS supportate, 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' o 'TLSv1'. Predefinito: 'TLSv1.3', a meno che non venga modificato utilizzando le opzioni della riga di comando. Usando --tls-max-v1.2 si imposta il valore predefinito su 'TLSv1.2'. Usando --tls-max-v1.3 si imposta il valore predefinito su 'TLSv1.3'. Se vengono fornite più opzioni, viene utilizzato il massimo più alto.

tls.DEFAULT_MIN_VERSION

Aggiunto in: v11.4.0

• <string> Il valore predefinito dell'opzione minVersion di tls.createSecureContext(). Può essere assegnata una qualsiasi delle versioni del protocollo TLS supportate, 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' o 'TLSv1'. Le versioni precedenti a TLSv1.2 potrebbero richiedere il downgrade del Livello di sicurezza OpenSSL. Predefinito: 'TLSv1.2', a meno che non venga modificato usando le opzioni della riga di comando. Usando --tls-min-v1.0 si imposta il valore predefinito su 'TLSv1'. Usando --tls-min-v1.1 si imposta il valore predefinito su 'TLSv1.1'. Usando --tls-min-v1.3 si imposta il valore predefinito su 'TLSv1.3'. Se vengono fornite più opzioni, viene utilizzato il minimo più basso.

tls.DEFAULT_CIPHERS

Aggiunto in: v19.8.0, v18.16.0

• <string> Il valore predefinito dell'opzione ciphers di tls.createSecureContext(). Può essere assegnata una qualsiasi delle cipher OpenSSL supportate. Di default corrisponde al contenuto di crypto.constants.defaultCoreCipherList, a meno che non venga modificato usando le opzioni della riga di comando con --tls-default-ciphers.