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()).
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
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.
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
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
authorizedon the server only when you usedrequestCert. Otherwise it is meaningless there. - Do not trust
subjecttext blindly. For identity checks use the verified fingerprint, or thesubjectaltnamelist. - 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 readalpnProtocolto 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), buttls.connect({ socket })is the usual way. - Same stream rules. Backpressure,
end()versusdestroy()and half-close work as innet.Socket.