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. È possibile accedere al modulo utilizzando:

ESM

import tls from 'node:tls';

CJS

const tls = require('node:tls');

Determinare se il supporto crittografico non è disponibile

È possibile che Node.js sia stato compilato senza includere il supporto per il modulo node:crypto. In tali casi, tentare di import da tls o chiamare require('node:tls') comporterà la generazione di un errore.

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

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

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

Quando si utilizza ESM, se c'è la possibilità che il codice possa essere eseguito su una build di Node.js in cui il supporto crittografico non è abilitato, valuta la possibilità di utilizzare la funzione import() anziché la parola chiave lessicale import:

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

Concetti di TLS/SSL

TLS/SSL è un insieme di protocolli che si basano su un'infrastruttura a chiave pubblica (PKI) per abilitare la 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'uso 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 firmate digitalmente da un'autorità di certificazione o dal proprietario della chiave privata (tali certificati sono denominati "auto-firmati"). Il primo passo per ottenere un certificato è 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 auto-firmato.

La creazione di un certificato auto-firmato 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 unico file, ad esempio cat ca1-cert.pem ca2-cert.pem \> ca-cert.pem

Perfect forward secrecy

Il termine forward secrecy o perfect forward secrecy descrive una caratteristica dei metodi di key-agreement (cioè di key-exchange). In altre parole, le chiavi del server e del client vengono utilizzate per negoziare nuove chiavi temporanee utilizzate specificamente e solo per la sessione di comunicazione corrente. In pratica, questo significa che anche se la chiave privata del server venisse compromessa, la comunicazione può essere decrittografata dagli intercettatori solo se l'attaccante riesce a ottenere la coppia di chiavi generata appositamente per la sessione.

La perfect forward secrecy si ottiene generando casualmente una coppia di chiavi per il key-agreement ad ogni handshake TLS/SSL (al contrario dell'utilizzo della stessa chiave per tutte le sessioni). I metodi che implementano questa tecnica sono chiamati "effimeri".

Attualmente, due metodi sono comunemente usati per ottenere la perfect forward secrecy (nota il carattere "E" aggiunto alle abbreviazioni tradizionali):

• ECDHE: Una versione effimera del protocollo di key-agreement Elliptic Curve Diffie-Hellman.
• DHE: Una versione effimera del protocollo di key-agreement Diffie-Hellman.

La perfect forward secrecy che utilizza ECDHE è abilitata di default. 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 di default ma può essere abilitato insieme a ECDHE impostando l'opzione dhparam su 'auto'. Anche i parametri DHE personalizzati sono supportati, ma sconsigliati a favore di parametri ben noti selezionati automaticamente.

La perfect forward secrecy era opzionale fino a TLSv1.2. A partire da TLSv1.3, (EC)DHE è sempre utilizzato (ad eccezione delle connessioni solo PSK).

ALPN e SNI

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

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

Chiavi pre-condivise

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

TLS-PSK è una buona scelta solo dove 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 usi di TLS. L'implementazione TLS-PSK in OpenSSL ha visto molte falle di sicurezza negli ultimi anni, soprattutto perché è utilizzata solo da una minoranza di applicazioni. Si prega di considerare tutte le soluzioni alternative prima di passare alle cifrature PSK. Durante la generazione di PSK, è di fondamentale importanza utilizzare una sufficiente entropia, come discusso in RFC 4086. Derivare un segreto condiviso da una password o da altre fonti a bassa entropia non è sicuro.

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

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

L'implementazione attuale non supporta i callback PSK asincroni 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 cifratura 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.
• Returns: <Object> nella forma { psk: \<Buffer|TypedArray|DataView\>, identity: \<string\> } o null.

Quindi sul server:

• socket: <tls.TLSSocket> l'istanza del socket del server, equivalente a this.
• identity: <string> parametro di identità inviato dal client.
• Returns: <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, il callback deve fornire alcuni dati casuali come psk per far fallire la connessione con decrypt_error prima che la negoziazione sia terminata.

Mitigazione degli attacchi di rinegoziazione iniziati dal client

Il protocollo TLS consente ai client di rinegoziare alcuni aspetti della sessione TLS. Sfortunatamente, la rinegoziazione della sessione richiede una quantità sproporzionata di risorse lato server, rendendola un potenziale vettore per attacchi 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 questa soglia viene superata. I limiti sono configurabili:

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

I limiti di rinegoziazione predefiniti non devono essere modificati senza una piena 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. Quando si riconnette, i client inviano l'ID del loro stato di sessione salvato e, se anche il server ha lo stato per quell'ID, può accettare di utilizzarlo. Altrimenti, il server creerà una nuova sessione. Vedi RFC 2246 per maggiori informazioni, pagina 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 gestori 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 load balancer o worker del cluster, i server devono utilizzare una cache di sessione condivisa (come Redis) nei loro gestori di sessione.

Ticket di sessione

I server crittografano l'intero stato della sessione e lo inviano al client come "ticket". Quando ci si ricollega, 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. Per ulteriori informazioni, consultare RFC 5077.

La ripresa tramite 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 come 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, tenere presente che il server può inviare più ticket, il che comporta più eventi 'session', vedere 'session' per ulteriori informazioni.

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

È possibile ottenere le chiavi del ticket chiamando server.getTicketKeys() su un'istanza del server e quindi 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 del 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 utilizzavano ticket crittografati con esse possono essere decrittografate. Non devono essere archiviate 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, il che fa sì che il server crei nuove sessioni. Il timeout può essere configurato con l'opzione sessionTimeout di tls.createServer().

Per tutti i meccanismi, quando la ripresa non riesce, i server creeranno nuove sessioni. Poiché il mancato ripristino della sessione non causa errori di connessione TLS/HTTPS, è facile non notare prestazioni TLS inutilmente scadenti. La CLI di 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 cifrari TLS abilitati e disabilitati. Questo elenco di cifrari predefinito può essere configurato durante la costruzione 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 interamente utilizzando l'opzione della riga di comando --tls-cipher-list (direttamente o tramite la variabile d'ambiente NODE_OPTIONS). Ad esempio, quanto segue 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 cifrari 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 in fase di compilazione e il 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 mettersi in ascolto su qualsiasi socket, non influirà sui socket già aperti. Per esempio:

// Rimuovi i cifrari CBC obsoleti e i cifrari basati sullo scambio di chiavi RSA poiché 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 singolo client o server utilizzando l'opzione ciphers da tls.createSecureContext(), che è disponibile anche in tls.createServer(), tls.connect() e quando si creano nuovi tls.TLSSocket.

L'elenco dei cifrari può contenere un mix di nomi di suite di cifratura TLSv1.3, quelli che iniziano con 'TLS_', e specifiche per le suite di cifratura TLSv1.2 e inferiori. I cifrari TLSv1.2 supportano un formato di specifica legacy, consultare la documentazione di OpenSSL formato dell'elenco dei cifrari per i dettagli, ma tali specifiche non si applicano ai cifrari TLSv1.3. Le suite TLSv1.3 possono essere abilitate solo includendo il loro nome completo nell'elenco dei cifrari. Non possono, ad esempio, essere abilitati o disabilitati 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 sarà sempre scelto rispetto a TLSv1.2 se l'handshake indica che è supportato e se sono abilitate suite di cifratura TLSv1.3.

La suite di cifratura predefinita inclusa in Node.js è stata accuratamente selezionata per riflettere le migliori pratiche di sicurezza attuali e la mitigazione del rischio. 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 i cifrari GCM per l'impostazione di crittografia moderna di Chrome e preferisce anche i cifrari ECDHE e DHE per la perfetta segretezza in avanti, offrendo al contempo una certa compatibilità con le versioni precedenti.

I vecchi client che si basano su cifrari RC4 o DES non sicuri e deprecati (come Internet Explorer 6) non possono completare il processo di handshake con la configurazione predefinita. Se questi client devono essere supportati, i consigli TLS possono offrire una suite di cifratura compatibile. Per maggiori dettagli sul formato, vedere la documentazione di OpenSSL formato dell'elenco dei cifrari.

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'

I primi tre sono abilitati per impostazione predefinita. Le due suite basate su CCM sono supportate da TLSv1.3 perché potrebbero essere più performanti su sistemi vincolati, 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 accettabile di sicurezza per le operazioni crittografiche. I livelli di sicurezza di OpenSSL vanno da 0 a 5, e ogni livello impone requisiti di sicurezza più severi. Il livello di sicurezza predefinito è 1, che è generalmente adatto per la 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 a 0 durante l'utilizzo dell'elenco di cifrari OpenSSL predefinito, potresti usare:

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 a 0, consentendo l'uso di funzionalità legacy pur sfruttando le cifrature OpenSSL predefinite.

Utilizzo

Puoi anche impostare il livello di sicurezza e le cifrature dalla riga di comando usando --tls-cipher-list=DEFAULT@SECLEVEL=X come descritto in Modifica della suite di cifratura TLS predefinita. Tuttavia, è generalmente sconsigliato utilizzare l'opzione della riga di comando per impostare le cifrature ed è preferibile configurare le cifrature per singoli contesti all'interno del codice dell'applicazione, poiché questo approccio fornisce un controllo più preciso e riduce il rischio di ridurre a livello globale il livello di sicurezza.

Codici di errore del certificato X509

Molteplici funzioni possono fallire a causa di errori del certificato che vengono segnalati da OpenSSL. In tal caso, la funzione fornisce un <Error> 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 nella firma del certificato.
• 'CRL_SIGNATURE_FAILURE': Errore nella 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

Aggiunta in: v0.3.4

Deprecata da: v0.11.3

[Stabile: 0 - Deprecata]

Stabile: 0 Stabilità: 0 - Deprecata: 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

Aggiunta in: v0.3.4

Deprecata da: v0.11.3

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

Classe: tls.SecurePair

Aggiunta in: v0.3.2

Deprecata da: v0.11.3

[Stabile: 0 - Deprecata]

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

Restituito da tls.createSecurePair().

Evento: 'secure'

Aggiunta in: v0.3.2

Deprecata 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 deve essere ispezionato per confermare se il certificato utilizzato è correttamente autorizzato.

Classe: tls.Server

Aggiunta in: v0.3.2

• Estende: <net.Server>

Accetta connessioni crittografate utilizzando TLS o SSL.

Evento: 'connection'

Aggiunta in: v0.3.2

• socket <stream.Duplex>

Questo evento viene emesso quando viene stabilito un nuovo flusso TCP, prima che inizi l'handshake TLS. socket è tipicamente un oggetto di tipo net.Socket ma non riceverà eventi a differenza del socket creato 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 SSLKEYLOGFILE di NSS.
• 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 (in genere prima che l'handshake sia completo, ma non necessariamente). Questo materiale di chiave può essere memorizzato per il debug, poiché consente di decrittografare il traffico TLS catturato. Potrebbe essere emesso più volte per ogni socket.

Un tipico caso d'uso è quello di aggiungere le righe ricevute a un file di testo comune, che viene successivamente utilizzato da 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 solo le chiavi 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 alla creazione di una nuova sessione TLS. Questo può essere utilizzato per memorizzare le sessioni in una memoria esterna. I dati devono essere forniti alla callback 'resumeSession'.

La callback del listener riceve tre argomenti quando viene chiamata:

• 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 possano essere inviati o ricevuti tramite la connessione sicura.

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

Evento: 'OCSPRequest'

Aggiunto in: v0.11.13

L'evento 'OCSPRequest' viene emesso quando il client invia una richiesta di stato del certificato. La callback del listener riceve tre argomenti quando viene chiamata:

• 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 primari e dell'emittente. Questi possono essere utilizzati per ottenere l'ID del certificato OCSP e l'URL dell'endpoint OCSP.

In alternativa, può essere chiamato callback(null, null), indicando che non c'era alcuna risposta OCSP.

La chiamata a callback(err) comporterà una chiamata a socket.destroy(err).

Il flusso tipico di una richiesta OCSP è il seguente:

L'issuer può essere null se il certificato è autofirmato o se l'emittente non è nell'elenco dei certificati radice. (Un emittente può essere fornito tramite l'opzione ca quando si stabilisce la connessione TLS.)

L'ascolto di questo evento avrà effetto solo sulle connessioni stabilite dopo l'aggiunta del listener 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 sessione TLS precedente. La funzione di callback dell'ascoltatore viene passata con 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 ripristinata: callback([err[, sessionData]])
  • err <Error>
  • sessionData <Buffer>

L'ascoltatore dell'evento dovrebbe eseguire una ricerca in uno spazio di archiviazione esterno dei sessionData salvati dal gestore dell'evento 'newSession' usando il sessionId specificato. Se trovato, chiama callback(null, sessionData) per riprendere la sessione. Se non trovato, la sessione non può essere ripresa. callback() deve essere chiamata senza sessionData in modo che l'handshake possa continuare e una nuova sessione possa essere creata. È possibile chiamare callback(err) per terminare la connessione in entrata e distruggere il socket.

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

Quanto segue 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 con successo. La funzione di callback dell'ascoltatore viene passata con un singolo argomento quando viene chiamata:

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

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

La proprietà tlsSocket.alpnProtocol è una stringa che contiene il protocollo ALPN selezionato. Quando ALPN non ha un 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 contenente 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. Il callback del listener riceve due argomenti quando viene chiamato:

• 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.) oppure un oggetto di 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 all'hostname fornito (o al carattere jolly).

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

server.address()

Aggiunto in: v0.6.0

• Restituisce: <Object>

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

server.close([callback])

Aggiunto in: v0.3.2

• callback <Function> Un callback del listener che verrà registrato 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.

Vedere Ripresa della sessione per maggiori informazioni.

server.listen()

Avvia il server in ascolto di connessioni crittografate. Questo metodo è identico a server.listen() da net.Server.

server.setSecureContext(options)

Aggiunto in: v11.0.0

• options <Object> Un oggetto contenente una qualsiasi delle proprietà possibili dagli argomenti options di tls.createSecureContext() (ad 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 connessioni future al server. Le connessioni al server esistenti o attualmente in sospeso utilizzeranno le chiavi precedenti.

Vedere Ripresa della sessione per maggiori informazioni.

Classe: tls.TLSSocket

Aggiunto in: v0.11.4

• Estende: <net.Socket>

Esegue la crittografia trasparente dei dati scritti e tutta la negoziazione TLS richiesta.

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

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

new tls.TLSSocket(socket[, options])

[Cronologia]

Versione	Modifiche
v12.2.0	L'opzione enableTrace è ora supportata.
v5.0.0	Le opzioni ALPN sono ora supportate.
v0.11.4	Aggiunto 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 generico dello stream Duplex 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 un server o un client. Se true il socket TLS verrà istanziato come un server. Predefinito: false.
  • server <net.Server> Un'istanza di net.Server.
  • requestCert: Indica se autenticare il peer remoto richiedendo un certificato. I client richiedono sempre un certificato del 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 di Buffer contenente una sessione TLS.
  • requestOCSP <boolean> Se true, specifica che l'estensione della richiesta di stato OCSP verrà aggiunta all'hello del client e un evento 'OCSPResponse' verrà emesso sul socket prima di stabilire una comunicazione sicura.
  • 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().
  • ...: Opzioni di tls.createSecureContext() che vengono utilizzate se l'opzione secureContext è mancante. 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 della chiave viene generato o ricevuto dal socket. Questo materiale di chiave può essere memorizzato per il debug, poiché consente di decrittografare il traffico TLS catturato. Può essere emesso più volte, prima o dopo il completamento dell'handshake.

Un tipico caso d'uso è 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 funzione di callback del listener viene passata con un singolo argomento quando viene chiamata:

• response <Buffer> La risposta OCSP del server

In genere, la response è un oggetto firmato digitalmente dalla CA 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 con successo. La funzione di callback del listener verrà chiamata indipendentemente dal fatto che il certificato del server sia stato autorizzato o meno. È responsabilità del client controllare 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 un <tls.TLSSocket> viene creato utilizzando il costruttore new tls.TLSSocket().

Evento: 'session'

Aggiunto in: v11.10.0

• session <Buffer>

L'evento 'session' viene emesso su un tls.TLSSocket client quando una nuova sessione o un nuovo ticket TLS è disponibile. Questo può avvenire o meno prima che l'handshake sia completo, a seconda della versione del protocollo TLS negoziata. L'evento non viene emesso sul server, o se una nuova sessione non è stata creata, ad esempio, quando la connessione è stata ripresa. Per alcune versioni del protocollo TLS, l'evento può 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.

Vedere Ripresa della sessione per ulteriori informazioni.

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

tlsSocket.once('session', (session) => {
  // La sessione può essere utilizzata immediatamente o in seguito.
  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'address vincolato, il nome della family dell'indirizzo 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à è impostata solo quando tlsSocket.authorized === false.

tlsSocket.authorized

Aggiunto in: v0.11.4

• <boolean>

Questa proprietà è true se il certificato del 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 chiamato, i tentativi di rinegoziazione attiveranno un evento 'error' sul TLSSocket.

tlsSocket.enableTrace()

Aggiunto in: v12.2.0

Quando abilitato, le informazioni sulla traccia dei pacchetti TLS vengono scritte su stderr. Questo può essere usato 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 ci si dovrebbe fare affidamento.

tlsSocket.encrypted

Aggiunto in: v0.11.4

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

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

Aggiunto in: v13.10.0, v12.17.0

• length <number> numero di byte da recuperare dal materiale di cifratura
• label <string> un'etichetta specifica dell'applicazione, in genere sarà un valore dal Registro delle etichette Exporter IANA.
• context <Buffer> Fornire opzionalmente un contesto.
• Restituisce: <Buffer> i byte richiesti del materiale di cifratura

Il materiale di cifratura viene utilizzato per le validazioni 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');

/*
 Example return value of 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>
*/

Vedere 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 c'è 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 della cifratura IETF come standardName.
v12.0.0	Restituisce la versione minima della cifratura, invece di una stringa fissa ('TLSv1/SSLv3').
v0.11.4	Aggiunto in: v0.11.4

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

Restituisce un oggetto contenente informazioni sulla suite di cifratura negoziata.

Ad esempio, un protocollo TLSv1.2 con cifratura 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 effimere in 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 che è stato inviato al socket come parte di un handshake SSL/TLS, o undefined se nessun messaggio Finished è stato ancora inviato.

Poiché i messaggi Finished sono digest di 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_finished in OpenSSL e può essere utilizzato per implementare il binding del canale tls-unique da RFC 5929.

tlsSocket.getPeerCertificate([detailed])

Aggiunto in: v0.11.4

• detailed <boolean> Includi l'intera catena di certificati se true, altrimenti includi 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 la proprietà "ca".
v17.2.0, v16.14.0	Aggiunta fingerprint512.
v11.4.0	Supporto per le informazioni sulla chiave pubblica Elliptic Curve.

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

• ca <boolean> true se è una Certificate Authority (CA), false altrimenti.
• raw <Buffer> I dati del certificato X.509 codificati in DER.
• subject <Object> Il soggetto del certificato, descritto in termini di Country (C), StateOrProvince (ST), Locality (L), Organization (O), OrganizationalUnit (OU) e CommonName (CN). Il CommonName è in genere 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 di serie del certificato, come una stringa esadecimale. Esempio: 'B9B0D332A1AA5635'.
• fingerprint <string> Il digest SHA-1 del certificato codificato in DER. Viene restituito come una stringa esadecimale separata da :. Esempio: '2A:7A:C2:DD:...'.
• fingerprint256 <string> Il digest SHA-256 del certificato codificato in DER. Viene restituito come una stringa esadecimale separata da :. Esempio: '2A:7A:C2:DD:...'.
• fingerprint512 <string> Il digest SHA-512 del certificato codificato in DER. Viene restituito come una stringa esadecimale separata da :. Esempio: '2A:7A:C2:DD:...'.
• ext_key_usage <Array> (Facoltativo) L'utilizzo esteso della chiave, un insieme di OID.
• subjectaltname <string> (Facoltativo) Una stringa contenente nomi concatenati per il soggetto, un'alternativa ai nomi subject.
• infoAccess <Array> (Facoltativo) Un array che descrive AuthorityInfoAccess, utilizzato con OCSP.
• issuerCertificate <Object> (Facoltativo) L'oggetto certificato dell'emittente. Per i certificati autofirmati, questo potrebbe essere un riferimento circolare.

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

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

• bits <number> La dimensione in bit 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, possono essere definite le seguenti proprietà:

• pubkey <Buffer> La chiave pubblica.
• bits <number> La dimensione della chiave in bit. Esempio: 256.
• asn1Curve <string> (Facoltativo) Il nome ASN.1 dell'OID della curva ellittica. Le curve ben 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> (Facoltativo) Il nome NIST per la curva ellittica, se ne ha uno (non a tutte le curve ben 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: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
  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 che è previsto o è stato effettivamente ricevuto dal socket come parte di un handshake SSL/TLS, oppure undefined se finora non c'è alcun messaggio Finished.

Poiché i messaggi Finished sono message digest 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 channel binding tls-unique da RFC 5929.

tlsSocket.getPeerX509Certificate()

Aggiunto in: v15.9.0

• Restituisce: <X509Certificate>

Restituisce il certificato peer come oggetto <X509Certificate>.

Se non esiste un certificato peer o 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 del server o i socket client disconnessi.

Le versioni del protocollo sono:

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

Vedi 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 non è stata negoziata alcuna sessione. 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.

Vedi Ripresa 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 nell'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 Ripresa della sessione per maggiori informazioni.

tlsSocket.getX509Certificate()

Aggiunto in: v15.9.0

• Restituisce: <X509Certificate>

Restituisce il certificato locale come un oggetto <X509Certificate>.

Se non è presente alcun certificato locale o 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 Ripresa della 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. Ad esempio, '74.125.127.100' o '2001:4860:a005::68'.

tlsSocket.remoteFamily

Aggiunto in: v0.11.4

• <stringa>

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

tlsSocket.remotePort

Aggiunto in: v0.11.4

• <numero intero>

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

tlsSocket.renegotiate(options, callback)

[Cronologia]

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

• options <Oggetto>

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

• callback <Funzione> Se renegotiate() ha restituito true, la callback viene allegata una volta all'evento 'secure'. Se renegotiate() ha restituito false, callback verrà chiamata nel tick successivo con un errore, a meno che tlsSocket non sia stato distrutto, nel qual caso callback non verrà chiamata affatto.

• Restituisce: <booleano> 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 è fallita) o null.

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

Quando è in esecuzione come server, il socket verrà distrutto con un errore dopo il timeout di 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 <Object> | <tls.SecureContext> Un oggetto contenente almeno le proprietà key e cert dalle options di tls.createSecureContext(), oppure 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 è utile principalmente se desideri selezionare un certificato server dalla ALPNCallback di un server TLS.

tlsSocket.setMaxSendFragment(size)

Aggiunto in: v0.11.11

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

Il metodo tlsSocket.setMaxSendFragment() imposta la dimensione massima del frammento TLS. Restituisce true se l'impostazione del limite è andata a buon fine; false altrimenti.

Dimensioni di frammento più piccole diminuiscono la latenza di buffering sul client: frammenti più grandi vengono memorizzati nel buffer dal livello TLS fino a quando l'intero frammento non viene ricevuto e la sua integrità verificata; frammenti di grandi dimensioni possono estendersi su più roundtrip e la loro elaborazione può essere ritardata a causa della perdita o del riordinamento dei pacchetti. Tuttavia, frammenti più piccoli aggiungono byte di framing TLS extra e overhead della CPU, il che potrebbe ridurre la velocità effettiva 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 <string> Il nome host o l'indirizzo IP per verificare il certificato.
• cert <Object> Un oggetto certificato che rappresenta il certificato del peer.
• Restituisce: <Error> | <undefined>

Verifica che il certificato cert sia stato rilasciato a hostname.

Restituisce l'oggetto <Error>, popolandolo con reason, host e cert in caso di errore. In caso di successo, restituisce <undefined>.

Questa funzione è destinata ad essere utilizzata in combinazione con l'opzione checkServerIdentity che può essere passata a tls.connect() e come tale opera su un oggetto certificato. Per altri scopi, valuta 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ò ovviamente chiamare tls.checkServerIdentity() per aumentare i controlli eseguiti con una verifica aggiuntiva.

Questa funzione viene chiamata solo se il certificato ha superato tutti gli altri controlli, come ad esempio l'emissione da parte di una CA 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 (vedi CVE-2021-44531). Le applicazioni che desiderano accettare nomi alternativi del soggetto uniformResourceIdentifier possono utilizzare una funzione options.checkServerIdentity personalizzata che implementa il comportamento desiderato.

tls.connect(options[, callback])

[Cronologia]

Versione	Modifiche
v15.1.0, v14.18.0	Aggiunta l'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	Supporta l'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ò essere ora un TypedArray o 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 <Object>

  • enableTrace: Vedere tls.createServer()
  • host <string> Host a cui il client deve connettersi. Predefinito: 'localhost'.
  • port <number> Porta a cui il client deve connettersi.
  • path <string> 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 anziché creare un nuovo socket. In genere, questa è un'istanza di net.Socket, ma è consentito qualsiasi stream Duplex. Se questa opzione è specificata, path, host e port vengono ignorati, ad eccezione della convalida del certificato. Di solito, un socket è già connesso quando viene passato a tls.connect(), ma può essere connesso in seguito. La connessione/disconnessione/distruzione del socket è responsabilità dell'utente; la chiamata a tls.connect() non farà sì che net.connect() venga chiamato.
  • allowHalfOpen <boolean> 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. Vedere l'opzione allowHalfOpen di net.Socket per i dettagli. Predefinito: false.
  • rejectUnauthorized <boolean> Se non false, il certificato del server viene verificato rispetto all'elenco di CA fornite. Viene emesso un evento 'error' se la verifica fallisce; err.code contiene il codice di errore OpenSSL. Predefinito: true.
  • pskCallback <Function> Per la negoziazione TLS-PSK, vedere Chiavi pre-condivise.
  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Un array 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 nome del protocollo successivo. Passare un array è di solito molto più semplice, ad es. ['http/1.1', 'http/1.0']. I protocolli precedenti nell'elenco hanno una preferenza maggiore rispetto a quelli successivi.
  • servername: <string> Nome del server per l'estensione TLS SNI (Server Name Indication). È il nome dell'host a cui ci si connette e deve essere un nome host e non un indirizzo IP. Può essere utilizzato da un server multi-homed per scegliere il certificato corretto da presentare al client, vedere l'opzione SNICallback per tls.createServer().
  • checkServerIdentity(servername, cert) <Function> Una funzione di callback da utilizzare (invece della funzione integrata tls.checkServerIdentity()) quando si controlla il nome host del server (o il servername fornito quando impostato esplicitamente) rispetto al certificato. Questo dovrebbe restituire un <Error> se la verifica fallisce. Il metodo dovrebbe restituire undefined se il servername e il cert sono verificati.
  • session <Buffer> Un'istanza Buffer contenente la sessione TLS.
  • minDHSize <number> 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 interrotta e viene generato un errore. Predefinito: 1024.
  • highWaterMark: <number> Coerente con il parametro highWaterMark dello stream leggibile. Predefinito: 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 <Object> Se l'opzione socket è mancante, i dati in entrata vengono archiviati in un singolo buffer e passati al callback fornito quando i dati arrivano sul socket, altrimenti l'opzione viene ignorata. Vedere 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 <Function>

• 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 indurre alcuni server a restituire un certificato errato o a rifiutare del tutto la connessione. Per abilitare SNI, impostare l'opzione servername in aggiunta a host.

Quanto segue illustra un client per l'esempio di echo server da tls.createServer():

ESM

// Presuppone un echo server 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 connected',
              socket.authorized ? 'authorized' : 'unauthorized');
  stdin.pipe(socket);
  stdin.resume();
});
socket.setEncoding('utf8');
socket.on('data', (data) => {
  console.log(data);
});
socket.on('end', () => {
  console.log('server ends connection');
});

CJS

// Presuppone un echo server 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 connected',
              socket.authorized ? 'authorized' : 'unauthorized');
  process.stdin.pipe(socket);
  process.stdin.resume();
});
socket.setEncoding('utf8');
socket.on('data', (data) => {
  console.log(data);
});
socket.on('end', () => {
  console.log('server ends connection');
});

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>

Uguale a tls.connect() tranne per il fatto 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>

Uguale a tls.connect() tranne per il fatto 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	L'opzione allowPartialTrustChain è stata aggiunta.
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 ora può essere impostata su 'auto' per abilitare DHE con parametri appropriati e ben noti.
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 il 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 usati 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 ora può includere clientCertEngine.
v9.0.0	L'opzione ecdhCurve ora può essere più nomi di curve separate da ':' o 'auto'.
v7.3.0	Se l'opzione key è un array, le singole voci non necessitano più di una proprietà passphrase. Le voci di Array possono anche essere solo string o Buffer.
v5.2.0	L'opzione ca ora può essere una singola stringa contenente più certificati CA.
v0.11.13	Aggiunto in: v0.11.13

• options <Object>
  • allowPartialTrustChain <boolean> Considera i certificati intermedi (non auto-firmati) nell'elenco dei certificati CA di fiducia come attendibili.
  • ca <string> | <string[]> | <Buffer> | <Buffer[]> Sovrascrive facoltativamente i certificati CA attendibili. Il valore predefinito è considerare attendibili le CA note curate da Mozilla. Le CA di Mozilla vengono completamente sostituite quando le CA vengono esplicitamente specificate utilizzando questa opzione. Il valore può essere una stringa o un Buffer, o un Array di stringhe e/o Buffer. Qualsiasi stringa o Buffer può contenere più CA PEM concatenate 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 esplicitamente specificata come attendibile oppure la connessione non verrà autenticata. Se il peer utilizza un certificato che non corrisponde o non si concatena 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 auto-firmati, il certificato è la sua stessa CA e deve essere fornito. Per i certificati con codifica 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. Dovrebbe essere fornita una catena di certificati per ogni chiave privata. Ogni catena di certificati dovrebbe essere costituita dal certificato formattato PEM per una key privata fornita, seguito dai certificati intermedi formattati PEM (se presenti), in ordine, e non includere la CA root (la CA root deve essere nota in precedenza al peer, vedere ca). Quando si forniscono più catene di certificati, non devono essere 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 l'handshake fallirà.
  • sigalgs <string> Elenco separato da due punti degli 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 (ad es. 'RSA+SHA384') o nomi di schemi TLS v1.3 (ad es. rsa_pss_pss_sha512). Consulta le pagine man di OpenSSL per ulteriori informazioni.
  • ciphers <string> Specifica della suite di cifratura, che sostituisce quella predefinita. Per ulteriori informazioni, vedi Modificare la suite di cifratura TLS predefinita. I cifrari consentiti possono essere ottenuti tramite tls.getCiphers(). I nomi dei cifrari 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 List) formattati in PEM.
  • dhparam <string> | <Buffer> 'auto' o parametri Diffie-Hellman personalizzati, richiesti per la perfect forward secrecy non ECDHE. Se omessi o non validi, i parametri vengono scartati silenziosamente e i cifrari DHE non saranno disponibili. La perfect forward secrecy basata su ECDHE sarà comunque disponibile.
  • ecdhCurve <string> Una stringa che descrive una curva con nome o un elenco separato da due punti di NID o nomi di curve, ad esempio P-521:P-384:P-256, da utilizzare per l'accordo di chiave ECDH. Imposta su auto per selezionare automaticamente la curva. Utilizza crypto.getCurves() per ottenere un elenco di nomi di curve disponibili. Nelle versioni recenti, openssl ecparam -list_curves visualizzerà 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, vedi Opzioni OpenSSL per maggiori informazioni.
  • key <string> | <string[]> | <Buffer> | <Buffer[]> | <Object[]> Chiavi private in formato PEM. PEM consente l'opzione di crittografare le chiavi private. Le chiavi crittografate verranno decrittografate con options.passphrase. È possibile fornire più chiavi utilizzando algoritmi diversi come un array di stringhe o buffer di chiavi non crittografate, oppure un array di oggetti nella forma {pem: \<string|buffer\>[, passphrase: \<string\>]}. La forma dell'oggetto può verificarsi solo in un array. object.passphrase è facoltativo. Le chiavi crittografate verranno decrittografate con object.passphrase se fornito, o options.passphrase se non lo è.
  • privateKeyEngine <string> Nome di un motore OpenSSL da cui ottenere la chiave privata. Dovrebbe essere usato insieme a privateKeyIdentifier. Deprecato.
  • privateKeyIdentifier <string> Identificatore di una chiave privata gestita da un motore OpenSSL. Dovrebbe essere usato 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 consentita. Uno tra 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' o 'TLSv1'. Non può essere specificato insieme all'opzione secureProtocol; utilizzare uno o l'altro. Predefinito: tls.DEFAULT_MAX_VERSION.
  • minVersion <string> Imposta facoltativamente la versione TLS minima consentita. Uno tra 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' o 'TLSv1'. Non può essere specificato insieme all'opzione secureProtocol; utilizzare uno o l'altro. Evita di impostare su un valore inferiore 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 con codifica PFX o PKCS12. pfx è un'alternativa alla fornitura di key e cert individualmente. PFX è solitamente crittografato, se lo è, passphrase verrà utilizzato per decrittografarlo. È possibile fornire più PFX come un array di buffer PFX non crittografati, oppure un array di oggetti nella forma {buf: \<string|buffer\>[, passphrase: \<string\>]}. La forma dell'oggetto può verificarsi solo in un array. object.passphrase è facoltativo. Il PFX crittografato verrà decrittografato con object.passphrase se fornito, o options.passphrase se non lo è.
  • secureOptions <number> Influisce facoltativamente sul comportamento del protocollo OpenSSL, il che di solito non è necessario. Questo dovrebbe essere usato con attenzione, se non del tutto! Il valore è una maschera di bit numerica delle opzioni SSL_OP_* di 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. Utilizza invece minVersion e maxVersion. I valori possibili sono elencati come SSL_METHODS, utilizza i nomi delle funzioni come stringhe. Ad esempio, utilizza '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, vedi minVersion.
  • sessionIdContext <string> Identificatore opaco utilizzato dai server per garantire che lo stato della sessione non sia condiviso tra le applicazioni. Inutilizzato dai client.
  • ticketKeys: <Buffer> 48 byte di dati pseudocasuali crittograficamente robusti. Vedi Ripresa della sessione per maggiori informazioni.
  • sessionTimeout <number> Il numero di secondi dopo i quali una sessione TLS creata dal server non sarà più ripristinabile. Vedi Ripresa della sessione per maggiori informazioni. Predefinito: 300.

tls.createServer() imposta il valore predefinito dell'opzione honorCipherOrder su true, altre API che creano contesti sicuri lo lasciano non 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 un valore predefinito.

Il metodo tls.createSecureContext() crea un oggetto SecureContext. È utilizzabile 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 è richiesta per i cifrari che utilizzano i certificati. È possibile utilizzare key o pfx per fornirla.

Se l'opzione ca non viene 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', i parametri DHE noti di forza sufficiente verranno selezionati automaticamente. In caso contrario, se necessario, è possibile utilizzare openssl dhparam per creare parametri personalizzati. La lunghezza della chiave deve essere maggiore o uguale a 1024 bit, altrimenti verrà generato un errore. Sebbene 1024 bit siano consentiti, utilizzare 2048 bit o più per una maggiore sicurezza.

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

[Cronologia]

Versione	Modifiche
v5.0.0	Le opzioni ALPN sono ora supportate.
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 invece tls.TLSSocket.

• context <Object> Un oggetto di contesto sicuro come restituito da tls.createSecureContext()
• isServer <boolean> true per specificare che questa connessione TLS deve essere aperta come server.
• requestCert <boolean> true per specificare se un server deve richiedere un certificato da un client che si connette. Si applica solo quando isServer è true.
• rejectUnauthorized <boolean> 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 di contesto TLS da tls.createSecureContext()
  • isServer: se true, il socket TLS verrà istanziato in modalità server. Predefinito: false.
  • server <net.Server> Un'istanza di net.Server
  • requestCert: vedi tls.createServer()
  • rejectUnauthorized: vedi tls.createServer()
  • ALPNProtocols: vedi tls.createServer()
  • SNICallback: vedi tls.createServer()
  • session <Buffer> Un'istanza di Buffer contenente una sessione TLS.
  • requestOCSP <boolean> Se true, specifica che l'estensione della 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 dei quali legge e scrive i dati in chiaro. Generalmente, lo stream crittografato viene reindirizzato da/verso uno stream di dati crittografati in entrata e quello in chiaro viene utilizzato in sostituzione dello stream crittografato iniziale.

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

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

Il metodo tls.createSecurePair() è ora obsoleto 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 entrata 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 ora può essere un TypedArray o DataView.
v5.0.0	Le opzioni ALPN sono ora supportate.
v0.3.2	Aggiunto in: v0.3.2

• options <Object>

  • ALPNProtocols: <string[]> | <Buffer[]> | <TypedArray[]> | <DataView[]> | <Buffer> | <TypedArray> | <DataView> Un array 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]... ad es. 0x05hello0x05world, dove il primo byte è la lunghezza del nome del protocollo successivo. Passare un array è solitamente molto più semplice, ad es. ['hello', 'world']. (I protocolli devono essere ordinati in base alla loro priorità.)
  • ALPNCallback: <Function> Se impostato, questo verrà chiamato quando un client apre una connessione utilizzando l'estensione ALPN. Un argomento verrà passato al callback: un oggetto contenente i campi servername e protocols, rispettivamente contenenti il nome del server dall'estensione SNI (se presente) e un array di stringhe del nome del protocollo ALPN. Il 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 <string> Nome di un motore OpenSSL che può fornire il certificato client. Deprecato.
  • enableTrace <boolean> Se true, tls.TLSSocket.enableTrace() verrà chiamato su nuove connessioni. La tracciatura può essere abilitata dopo che la connessione sicura è stata stabilita, ma questa opzione deve essere utilizzata per tracciare la configurazione della connessione sicura. Predefinito: false.
  • handshakeTimeout <number> Interrompe la connessione se l'handshake SSL/TLS non termina nel numero specificato di millisecondi. Un 'tlsClientError' viene emesso sull'oggetto tls.Server ogni volta che un handshake scade. Predefinito: 120000 (120 secondi).
  • rejectUnauthorized <boolean> Se non false, il server rifiuterà qualsiasi connessione che non sia autorizzata con l'elenco di CA fornite. Questa opzione ha effetto solo se requestCert è true. Predefinito: true.
  • requestCert <boolean> Se true il server richiederà un certificato dai client che si connettono e tenterà di verificare tale certificato. Predefinito: false.
  • sessionTimeout <number> Il numero di secondi dopo il quale una sessione TLS creata dal server non sarà più ripristinabile. Vedi Ripresa della sessione per maggiori informazioni. Predefinito: 300.
  • SNICallback(servername, callback) <Function> Una funzione che verrà chiamata se il client supporta l'estensione SNI TLS. Due argomenti verranno passati quando viene chiamata: servername e callback. callback è un callback con priorità all'errore che accetta due argomenti opzionali: error e ctx. ctx, se fornito, è un'istanza di 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à utilizzato il callback predefinito con l'API di alto livello (vedi sotto).
  • ticketKeys: <Buffer> 48 byte di dati pseudocasuali crittograficamente validi. Vedi Ripresa della sessione per maggiori informazioni.
  • pskCallback <Function> Per la negoziazione TLS-PSK, vedi Chiavi pre-condivise.
  • pskIdentityHint <string> suggerimento opzionale da inviare a un client per aiutare con la 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'.
  • ...: È possibile fornire qualsiasi opzione tls.createSecureContext(). Per i server, le opzioni di identità (pfx, key/cert o pskCallback) sono generalmente richieste.
  • ...: È possibile fornire qualsiasi opzione net.createServer().

• secureConnectionListener <Function>

• Restituisce: <tls.Server>

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

Le opzioni ticketKeys sono automaticamente condivise tra i worker del modulo node:cluster.

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

  // This is necessary only if using client certificate authentication.
  requestCert: true,

  // This is necessary only if the client uses a self-signed certificate.
  ca: [ readFileSync('client-cert.pem') ],
};

const server = createServer(options, (socket) => {
  console.log('server connected',
              socket.authorized ? 'authorized' : 'unauthorized');
  socket.write('welcome!\n');
  socket.setEncoding('utf8');
  socket.pipe(socket);
});
server.listen(8000, () => {
  console.log('server bound');
});

CJS

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

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

  // This is necessary only if using client certificate authentication.
  requestCert: true,

  // This is necessary only if the client uses a self-signed certificate.
  ca: [ readFileSync('client-cert.pem') ],
};

const server = createServer(options, (socket) => {
  console.log('server connected',
              socket.authorized ? 'authorized' : 'unauthorized');
  socket.write('welcome!\n');
  socket.setEncoding('utf8');
  socket.pipe(socket);
});
server.listen(8000, () => {
  console.log('server bound');
});

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

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, esegui:

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 utilizzando il client di esempio da tls.connect().

tls.getCiphers()

Aggiunto in: v0.10.2

• Restituisce: <string[]>

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

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

I nomi delle cifrature 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[]>

Un array immutabile di stringhe che rappresenta i certificati radice (in formato PEM) dal Mozilla CA store incluso, fornito dalla versione corrente di Node.js.

Il CA store in bundle, fornito da Node.js, è un'istantanea del Mozilla CA store fissa al momento del rilascio. È identico su tutte le piattaforme supportate.

tls.DEFAULT_ECDH_CURVE

[Cronologia]

Versione	Modifiche
v10.0.0	Il valore predefinito è stato modificato in 'auto'.
v0.11.13	Aggiunto in: v0.11.13

Il nome della curva predefinita da utilizzare per l'accordo di 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 CLI. L'utilizzo di --tls-max-v1.2 imposta il valore predefinito su 'TLSv1.2'. L'utilizzo di --tls-max-v1.3 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 assegnato a una qualsiasi delle versioni del protocollo TLS supportate, 'TLSv1.3', 'TLSv1.2', 'TLSv1.1' o 'TLSv1'. Le versioni precedenti a TLSv1.2 potrebbero richiedere la riduzione del Livello di sicurezza OpenSSL. Predefinito: 'TLSv1.2', a meno che non venga modificato tramite le opzioni della CLI. L'utilizzo di --tls-min-v1.0 imposta il valore predefinito su 'TLSv1'. L'utilizzo di --tls-min-v1.1 imposta il valore predefinito su 'TLSv1.1'. L'utilizzo di --tls-min-v1.3 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 assegnato a una qualsiasi delle cifrature OpenSSL supportate. Il valore predefinito è il contenuto di crypto.constants.defaultCoreCipherList, a meno che non venga modificato tramite le opzioni della CLI utilizzando --tls-default-ciphers.