TLSSocket - tls - Node

class TLSSocket

extends net.Socket

Usage in Deno

import { TLSSocket } from "node:tls";

Performs transparent encryption of written data and all required TLS negotiation.

Instances of tls.TLSSocket implement the duplex Stream interface.

Methods that return TLS connection metadata (e.g.TLSSocket.getPeerCertificate) will only return data while the connection is open.

Constructors

new



TLSSocket(socket: net.Socket | stream.Duplex,
options?: TLSSocketOptions,
)

Construct a new tls.TLSSocket object from an existing TCP socket.

Properties



alpnProtocol: string
 | false
 | null

String containing the selected ALPN protocol. Before a handshake has completed, this value is always null. When a handshake is completed but not ALPN protocol was selected, tlsSocket.alpnProtocol equals false.



authorizationError: Error

Returns the reason why the peer's certificate was not been verified. This property is set only when tlsSocket.authorized === false.



authorized: boolean

This property is true if the peer certificate was signed by one of the CAs specified when creating the tls.TLSSocket instance, otherwise false.



encrypted: true

Always returns true. This may be used to distinguish TLS sockets from regularnet.Socket instances.

Methods



addListener(event: string,
listener: (...args: any[]) => void,
): this



addListener(event: "OCSPResponse",
listener: (response: Buffer) => void,
): this



addListener(event: "secureConnect",
listener: () => void,
): this



addListener(event: "session",
listener: (session: Buffer) => void,
): this



addListener(event: "keylog",
listener: (line: Buffer) => void,
): this



disableRenegotiation(): void

Disables TLS renegotiation for this TLSSocket instance. Once called, attempts to renegotiate will trigger an 'error' event on the TLSSocket.



emit(event: string | symbol,
...args: any[],
): boolean



emit(event: "OCSPResponse",
response: Buffer,
): boolean



emit(event: "secureConnect"): boolean



emit(event: "session",
session: Buffer,
): boolean



emit(event: "keylog",
line: Buffer,
): boolean



enableTrace(): void

When enabled, TLS packet trace information is written to stderr. This can be used to debug TLS connection problems.

The format of the output is identical to the output ofopenssl s_client -trace or openssl s_server -trace. While it is produced by OpenSSL's SSL_trace() function, the format is undocumented, can change without notice, and should not be relied on.



exportKeyingMaterial(length: number,
label: string,
context: Buffer,
): Buffer

Keying material is used for validations to prevent different kind of attacks in network protocols, for example in the specifications of IEEE 802.1X.

Example

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>

See the OpenSSL SSL_export_keying_material documentation for more information.



getCertificate(): PeerCertificate
 | object
 | null

Returns an object representing the local certificate. The returned object has some properties corresponding to the fields of the certificate.

See TLSSocket.getPeerCertificate for an example of the certificate structure.

If there is no local certificate, an empty object will be returned. If the socket has been destroyed, null will be returned.



getCipher(): CipherNameAndProtocol

Returns an object containing information on the negotiated cipher suite.

For example, a TLSv1.2 protocol with AES256-SHA cipher:

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

See SSL_CIPHER_get_name for more information.



getEphemeralKeyInfo(): EphemeralKeyInfo
 | object
 | null

Returns an object representing the type, name, and size of parameter of an ephemeral key exchange in perfect forward secrecy on a client connection. It returns an empty object when the key exchange is not ephemeral. As this is only supported on a client socket; null is returned if called on a server socket. The supported types are 'DH' and 'ECDH'. The name property is available only when type is 'ECDH'.

For example: { type: 'ECDH', name: 'prime256v1', size: 256 }.



getFinished(): Buffer | undefined

As the Finished messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can be used for external authentication procedures when the authentication provided by SSL/TLS is not desired or is not enough.

Corresponds to the SSL_get_finished routine in OpenSSL and may be used to implement the tls-unique channel binding from RFC 5929.



getPeerCertificate(detailed: true): DetailedPeerCertificate

Returns an object representing the peer's certificate. If the peer does not provide a certificate, an empty object will be returned. If the socket has been destroyed, null will be returned.

If the full certificate chain was requested, each certificate will include anissuerCertificate property containing an object representing its issuer's certificate.



getPeerCertificate(detailed?: false): PeerCertificate



getPeerCertificate(detailed?: boolean): PeerCertificate | DetailedPeerCertificate



getPeerFinished(): Buffer | undefined

Corresponds to the SSL_get_peer_finished routine in OpenSSL and may be used to implement the tls-unique channel binding from RFC 5929.



getPeerX509Certificate(): X509Certificate | undefined

Returns the peer certificate as an X509Certificate object.

If there is no peer certificate, or the socket has been destroyed,undefined will be returned.



getProtocol(): string | null

Returns a string containing the negotiated SSL/TLS protocol version of the current connection. The value 'unknown' will be returned for connected sockets that have not completed the handshaking process. The value null will be returned for server sockets or disconnected client sockets.

Protocol versions are:

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

See the OpenSSL SSL_get_version documentation for more information.



getSession(): Buffer | undefined

Returns the TLS session data or undefined if no session was negotiated. On the client, the data can be provided to the session option of connect to resume the connection. On the server, it may be useful for debugging.

See Session Resumption for more information.

Note: getSession() works only for TLSv1.2 and below. For TLSv1.3, applications must use the 'session' event (it also works for TLSv1.2 and below).



getSharedSigalgs(): string[]

See SSL_get_shared_sigalgs for more information.



getTLSTicket(): Buffer | undefined

For a client, returns the TLS session ticket if one is available, orundefined. For a server, always returns undefined.

It may be useful for debugging.

See Session Resumption for more information.



getX509Certificate(): X509Certificate | undefined

Returns the local certificate as an X509Certificate object.

If there is no local certificate, or the socket has been destroyed,undefined will be returned.



isSessionReused(): boolean

See Session Resumption for more information.



on(event: string,
listener: (...args: any[]) => void,
): this



on(event: "OCSPResponse",
listener: (response: Buffer) => void,
): this



on(event: "secureConnect",
listener: () => void,
): this



on(event: "session",
listener: (session: Buffer) => void,
): this



on(event: "keylog",
listener: (line: Buffer) => void,
): this



once(event: string,
listener: (...args: any[]) => void,
): this



once(event: "OCSPResponse",
listener: (response: Buffer) => void,
): this



once(event: "secureConnect",
listener: () => void,
): this



once(event: "session",
listener: (session: Buffer) => void,
): this



once(event: "keylog",
listener: (line: Buffer) => void,
): this



prependListener(event: string,
listener: (...args: any[]) => void,
): this



prependListener(event: "OCSPResponse",
listener: (response: Buffer) => void,
): this



prependListener(event: "secureConnect",
listener: () => void,
): this



prependListener(event: "session",
listener: (session: Buffer) => void,
): this



prependListener(event: "keylog",
listener: (line: Buffer) => void,
): this



prependOnceListener(event: string,
listener: (...args: any[]) => void,
): this



prependOnceListener(event: "OCSPResponse",
listener: (response: Buffer) => void,
): this



prependOnceListener(event: "secureConnect",
listener: () => void,
): this



prependOnceListener(event: "session",
listener: (session: Buffer) => void,
): this



prependOnceListener(event: "keylog",
listener: (line: Buffer) => void,
): this



renegotiate(options: { rejectUnauthorized?: boolean | undefined; requestCert?: boolean | undefined;  },
callback: (err: Error | null) => void,
): undefined | boolean

The tlsSocket.renegotiate() method initiates a TLS renegotiation process. Upon completion, the callback function will be passed a single argument that is either an Error (if the request failed) or null.

This method can be used to request a peer's certificate after the secure connection has been established.

When running as the server, the socket will be destroyed with an error after handshakeTimeout timeout.

For TLSv1.3, renegotiation cannot be initiated, it is not supported by the protocol.



setMaxSendFragment(size: number): boolean

The tlsSocket.setMaxSendFragment() method sets the maximum TLS fragment size. Returns true if setting the limit succeeded; false otherwise.

Smaller fragment sizes decrease the buffering latency on the client: larger fragments are buffered by the TLS layer until the entire fragment is received and its integrity is verified; large fragments can span multiple roundtrips and their processing can be delayed due to packet loss or reordering. However, smaller fragments add extra TLS framing bytes and CPU overhead, which may decrease overall server throughput.