Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns

The Node.js tls.TLSSocket class

Reference for tls.TLSSocket in Node.js: authorized, getPeerCertificate(), getProtocol(), getCipher(), ALPN, SNI, session reuse and the events of an encrypted socket.

tls.TLSSocket is a net.Socket that encrypts everything passing through it. You get one from tls.connect() on the client side, and from the 'secureConnection' event of a tls.createServer() server. Reading, writing, end(), timeouts and events all work as for a plain socket; the extra members describe the secure channel.

The useful ones answer three questions: "who is on the other end?" (authorized, getPeerCertificate()), "what did we agree on?" (getProtocol(), getCipher(), alpnProtocol, servername), and "can we reconnect cheaply?" (getSession(), isSessionReused()).

NODE
import tls from 'node:tls';

const socket = tls.connect({ host: 'example.com', port: 443 });
socket.on('secureConnect', () => {
  console.log(socket.getProtocol(), socket.authorized);
});

Try it

Node.js Inspecting the secure channel

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Session resumption

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
class tls.TLSSocket extends net.Socket
new tls.TLSSocket(socket: net.Socket, options?: object)
Member Description
authorized true if the peer's certificate was verified against the trusted CAs.
authorizationError Reason string or code when authorized is false, otherwise null.
encrypted Always true; lets code tell TLSSocket from Socket.
getPeerCertificate(detailed?) The peer's certificate as an object (subject, issuer, subjectaltname, valid_from, valid_to, bits, fingerprint256, raw). detailed: true includes the issuer chain. Returns an empty object if there is no certificate.
getPeerX509Certificate(), getX509Certificate() The same certificates as X509Certificate objects.
getProtocol() 'TLSv1.3', 'TLSv1.2', ... or null before the handshake.
getCipher() { name, standardName, version } of the negotiated cipher suite.
getEphemeralKeyInfo() Key exchange details for forward secrecy.
alpnProtocol The protocol selected by ALPN, false if none was agreed, null before the handshake.
servername The SNI name the client asked for (server side).
getSession(), isSessionReused() Resume support. With TLS 1.3, listen for 'session' instead of calling getSession() early.
renegotiate(options, cb) Starts renegotiation (TLS 1.2 only).
setMaxSendFragment(size) Sets the record size, between 512 and 16384 bytes.
exportKeyingMaterial(length, label, context?) Derives key material bound to the session (RFC 5705).
disableRenegotiation() Rejects renegotiation requests.

Events: 'secureConnect' (client handshake done), 'session', 'keylog' (NSS key log lines for tools like Wireshark), 'OCSPResponse', plus every net.Socket event.

Errors and edge cases: methods such as getPeerCertificate() return an empty object, not undefined, when the peer sent nothing. A server that did not ask for a client certificate sees an empty object for the client.

Usage notes

  • Check authorized on the server only when you used requestCert. Otherwise it is meaningless there.
  • Do not trust subject text blindly. For identity checks use the verified fingerprint, or the subjectaltname list.
  • TLS 1.3 tickets arrive late. getSession() right after 'secureConnect' can return a session that cannot resume; use the 'session' event.
  • ALPN is how HTTP/2 is negotiated. Offer ['h2', 'http/1.1'] and read alpnProtocol to see what the server chose.
  • Logging keys for debugging. The 'keylog' event emits secrets; never enable it in production.
  • Wrapping an existing socket. new tls.TLSSocket(socket) upgrades a plain connection (as with STARTTLS), but tls.connect({ socket }) is the usual way.
  • Same stream rules. Backpressure, end() versus destroy() and half-close work as in net.Socket.