TLSSocket - node__tls.d.ts - Node

class TLSSocket

extends net.Socket

Usage in Deno

```typescript import { TLSSocket } from "node:node__tls.d.ts"; ```

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 regular`net.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 of`openssl 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 ```js const keyingMaterial = tlsSocket.exportKeyingMaterial( 128, 'client finished'); /* Example return value of keyingMaterial: ``` See the OpenSSL [`SSL_export_keying_material`](https://www.openssl.org/docs/man1.1.1/man3/SSL_export_keying_material.html) 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: ```json { "name": "AES256-SHA", "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA", "version": "SSLv3" } ``` See [SSL\_CIPHER\_get\_name](https://www.openssl.org/docs/man1.1.1/man3/SSL_CIPHER_get_name.html) 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](https://tools.ietf.org/html/rfc5929).



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 an`issuerCertificate` property containing an object representing its issuer's certificate.



getPeerCertificate(detailed?: false): PeerCertificate



getPeerCertificate(detailed?: boolean): PeerCertificate | DetailedPeerCertificate



getPeerFinished(): 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_peer_finished` routine in OpenSSL and may be used to implement the `tls-unique` channel binding from [RFC 5929](https://tools.ietf.org/html/rfc5929).



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`](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html) 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](../.././node__tls.d.ts/~/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](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_shared_sigalgs.html) for more information.



getTLSTicket(): Buffer | undefined

For a client, returns the TLS session ticket if one is available, or`undefined`. 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.