TLSSocket
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.{@link TLSSocket.getPeerCertificate}) will only return data while the connection is open.
Since
v0.11.4
Constructors
Properties
If false then the stream will automatically end the writable side when the readable side ends. Set initially by the allowHalfOpen constructor option, which defaults to true.
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.
Returns the reason why the peer's certificate was not been verified. This property is set only when tlsSocket.authorized === false.
This property is true if the peer certificate was signed by one of the CAs specified when creating the tls.TLSSocket instance, otherwise false.
This property is only present if the family autoselection algorithm is enabled in socket.connect(options) and it is an array of the addresses that have been attempted.
This property shows the number of characters buffered for writing. The buffer may contain strings whose length after encoding is not yet known. So this number is only an approximation of the number of bytes in the buffer.
The amount of bytes sent.
If true, socket.connect(options[, connectListener]) was called and has not yet finished. It will stay true until the socket becomes connected, then it is set to false and the 'connect' event is emitted. Note that the socket.connect(options[, connectListener]) callback is a listener for the 'connect' event.
The string representation of the local IP address the remote client is connecting on. For example, in a server listening on '0.0.0.0', if a client connects on '192.168.1.1', the value of socket.localAddress would be'192.168.1.1'.
The string representation of the local IP family. 'IPv4' or 'IPv6'.
See writable.destroyed for further details.
Returns whether the stream was destroyed or errored before emitting 'end'.
Returns whether 'data' has been emitted.
Getter for the property encoding of a given Readable stream. The encoding property can be set using the {@link setEncoding} method.
Becomes true when 'end' event is emitted.
This property reflects the current state of a Readable stream as described in the Three states section.
Returns the value of highWaterMark passed when creating this Readable.
This property contains the number of bytes (or objects) in the queue ready to be read. The value provides introspection data regarding the status of the highWaterMark.
Getter for the property objectMode of a given Readable stream.
Is true if it is safe to call writable.write(), which means the stream has not been destroyed, errored, or ended.
This property represents the state of the connection as a string.
The string representation of the remote IP address. For example,'74.125.127.100' or '2001:4860:a005::68'. Value may be undefined if the socket is destroyed (for example, if the client disconnected).
The string representation of the remote IP family. 'IPv4' or 'IPv6'. Value may be undefined if the socket is destroyed (for example, if the client disconnected).
The numeric representation of the remote port. For example, 80 or 21. Value may be undefined if the socket is destroyed (for example, if the client disconnected).
Number of times writable.uncork() needs to be called in order to fully uncork the stream.
Is true after writable.end() has been called. This property does not indicate whether the data has been flushed, for this use writable.writableFinished instead.
Is set to true immediately before the 'finish' event is emitted.
Return the value of highWaterMark passed when creating this Writable.
This property contains the number of bytes (or objects) in the queue ready to be written. The value provides introspection data regarding the status of the highWaterMark.
Is true if the stream's buffer has been full and stream will emit 'drain'.
Getter for the property objectMode of a given Writable stream.
Functions
Event emitter The defined events on documents including:
events.EventEmitter
This method returns a new stream with chunks of the underlying stream paired with a counter in the form [index, chunk]. The first index value is 0 and it increases by 1 for each chunk produced.
Initiate a connection on a given socket.
Destroy the stream. Optionally emit an 'error' event, and emit a 'close' event (unless emitClose is set to false). After this call, the readable stream will release any internal resources and subsequent calls to push() will be ignored.
Destroys the socket after all data is written. If the finish event was already emitted the socket is destroyed immediately. If the socket is still writable it implicitly calls socket.end().
Disables TLS renegotiation for this TLSSocket instance. Once called, attempts to renegotiate will trigger an 'error' event on the TLSSocket.
This method returns a new stream with the first limit chunks dropped from the start.
When enabled, TLS packet trace information is written to stderr. This can be used to debug TLS connection problems.
Half-closes the socket. i.e., it sends a FIN packet. It is possible the server will still send some data.
Returns an array listing the events for which the emitter has registered listeners. The values in the array are strings or Symbols.
This method is similar to Array.prototype.every and calls fn on each chunk in the stream to check if all awaited return values are truthy value for fn. Once an fn call on a chunk awaited return value is falsy, the stream is destroyed and the promise is fulfilled with false. If all of the fn calls on the chunks return a truthy value, the promise is fulfilled with true.
Keying material is used for validations to prevent different kind of attacks in network protocols, for example in the specifications of IEEE 802.1X.
This method allows filtering the stream. For each chunk in the stream the fn function will be called and if it returns a truthy value, the chunk will be passed to the result stream. If the fn function returns a promise - that promise will be awaited.
This method is similar to Array.prototype.find and calls fn on each chunk in the stream to find a chunk with a truthy value for fn. Once an fn call's awaited return value is truthy, the stream is destroyed and the promise is fulfilled with value for which fn returned a truthy value. If all of the fn calls on the chunks return a falsy value, the promise is fulfilled with undefined.
This method returns a new stream by applying the given callback to each chunk of the stream and then flattening the result.
This method allows iterating a stream. For each chunk in the stream the fn function will be called. If the fn function returns a promise - that promise will be awaited.
Returns an object representing the local certificate. The returned object has some properties corresponding to the fields of the certificate.
Returns an object containing information on the negotiated cipher suite.
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'.
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.
Returns the current max listener value for the EventEmitter which is either set by emitter.setMaxListeners(n) or defaults to {@link defaultMaxListeners}.
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.
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.
Returns the peer certificate as an X509Certificate object.
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.
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 {@link connect} to resume the connection. On the server, it may be useful for debugging.
See SSL\_get\_shared\_sigalgs for more information.
For a client, returns the TLS session ticket if one is available, orundefined. For a server, always returns undefined.
Returns the local certificate as an X509Certificate object.
See Session Resumption for more information.
The iterator created by this method gives users the option to cancel the destruction of the stream if the for await...of loop is exited by return, break, or throw, or if the iterator should destroy the stream if the stream emitted an error during iteration.
This method allows mapping over the stream. The fn function will be called for every chunk in the stream. If the fn function returns a promise - that promise will be awaited before being passed to the result stream.
The readable.read() method reads data out of the internal buffer and returns it. If no data is available to be read, null is returned. By default, the data is returned as a Buffer object unless an encoding has been specified using the readable.setEncoding() method or the stream is operating in object mode.
This method calls fn on each chunk of the stream in order, passing it the result from the calculation on the previous element. It returns a promise for the final value of the reduction.
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.
Close the TCP connection by sending an RST packet and destroy the stream. If this TCP socket is in connecting status, it will send an RST packet and destroy this TCP socket once it is connected. Otherwise, it will call socket.destroy with an ERR_SOCKET_CLOSED Error. If this is not a TCP socket (for example, a pipe), calling this method will immediately throw an ERR_INVALID_HANDLE_TYPE Error.
The writable.setDefaultEncoding() method sets the default encoding for a Writable stream.
Set the encoding for the socket as a Readable Stream. See readable.setEncoding() for more information.
Enable/disable keep-alive functionality, and optionally set the initial delay before the first keepalive probe is sent on an idle socket.
By default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default that helps finding memory leaks. The emitter.setMaxListeners() method allows the limit to be modified for this specific EventEmitter instance. The value can be set to Infinity (or 0) to indicate an unlimited number of listeners.
The tlsSocket.setMaxSendFragment() method sets the maximum TLS fragment size. Returns true if setting the limit succeeded; false otherwise.
Enable/disable the use of Nagle's algorithm.
Sets the socket to timeout after timeout milliseconds of inactivity on the socket. By default net.Socket do not have a timeout.
This method is similar to Array.prototype.some and calls fn on each chunk in the stream until the awaited return value is true (or any truthy value). Once an fn call on a chunk awaited return value is truthy, the stream is destroyed and the promise is fulfilled with true. If none of the fn calls on the chunks return a truthy value, the promise is fulfilled with false.
This method returns a new stream with the first limit chunks.
This method allows easily obtaining the contents of a stream.
The readable.unpipe() method detaches a Writable stream previously attached using the {@link pipe} method.
Passing chunk as null signals the end of the stream (EOF) and behaves the same as readable.push(null), after which no more data can be written. The EOF signal is put at the end of the buffer and any buffered data will still be flushed.
Prior to Node.js 0.10, streams did not implement the entire node:stream module API as it is currently defined. (See Compatibility for more information.)
Sends data on the socket. The second parameter specifies the encoding in the case of a string. It defaults to UTF8 encoding.
The writable.write() method writes some data to the stream, and calls the supplied callback once the data has been fully handled. If an error occurs, the callback will be called with the error as its first argument. The callback is called asynchronously and before 'error' is emitted.