类: tls.TLSSocket

This is a wrapped version of [net.Socket][] that does transparent encryption of written data and all required TLS negotiation.

This instance implements the duplex [Stream][] interface. It has all the common stream methods and events.

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

new tls.TLSSocket(socket[, options])

Construct a new TLSSocket object from an existing TCP socket.

socket is an instance of [net.Socket][]

options is an optional object that might contain following properties:

  • secureContext: An optional TLS context object from [tls.createSecureContext()][]

  • isServer: If true the TLS socket will be instantiated in server-mode. Default: false

  • server: An optional [net.Server][] instance

  • requestCert: Optional, see [tls.createSecurePair()][]

  • rejectUnauthorized: Optional, see [tls.createSecurePair()][]

  • NPNProtocols: Optional, see [tls.createServer()][]

  • ALPNProtocols: Optional, see [tls.createServer()][]

  • SNICallback: Optional, see [tls.createServer()][]

  • session: Optional, a Buffer instance, containing a TLS session

  • requestOCSP: Optional, if true the OCSP status request extension will be added to the client hello and an 'OCSPResponse' event will be emitted on the socket before establishing a secure communication

Event: 'OCSPResponse'

function (response) { }

This event will be emitted if the requestOCSP option was set. response is a Buffer containing the server's OCSP response.

Traditionally, the response is a signed object from the server's CA that contains information about server's certificate revocation status.

Event: 'secureConnect'

This event is emitted after the handshaking process for a new connection has successfully completed. The listener will be called regardless of whether or not the server's certificate has been authorized. It is the user's responsibility to test tlsSocket.authorized to see if the server certificate was signed by one of the specified CAs. If tlsSocket.authorized === false then the error can be found in tlsSocket.authorizationError. Also, if either ALPN or NPN was used tlsSocket.alpnProtocol or tlsSocket.npnProtocol can be checked for the negotiated protocol.

tlsSocket.address()

Returns the bound address, the address family name, and port of the underlying socket as reported by the operating system. Returns an object with three properties, e.g., { port: 12346, family: 'IPv4', address: '127.0.0.1' }

tlsSocket.authorized

A boolean that is true if the peer certificate was signed by one of the specified CAs, otherwise false.

tlsSocket.authorizationError

The reason why the peer's certificate has not been verified. This property becomes available only when tlsSocket.authorized === false.

tlsSocket.encrypted

Static boolean value, always true. May be used to distinguish TLS sockets from regular ones.

tlsSocket.getCipher()

Returns an object representing the cipher name and the SSL/TLS protocol version that first defined the cipher.

Example: { name: 'AES256-SHA', version: 'TLSv1/SSLv3' }

See SSL_CIPHER_get_name() and SSL_CIPHER_get_version() in https://www.openssl.org/docs/manmaster/ssl/SSL_CIPHER_get_name.html for more information.

tlsSocket.getEphemeralKeyInfo()

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, it returns null if called on a server socket. The supported types are 'DH' and 'ECDH'. The name property is only available in 'ECDH'.

Example:

{ type: 'ECDH', name: 'prime256v1', size: 256 }

tlsSocket.getPeerCertificate([ detailed ])

Returns an object representing the peer's certificate. The returned object has some properties corresponding to the fields of the certificate. If the detailed argument is true the full chain with the issuer property will be returned, if false only the top certificate without the issuer property.

Example:

{ subject:
   { C: 'UK',
     ST: 'Acknack Ltd',
     L: 'Rhys Jones',
     O: 'node.js',
     OU: 'Test TLS Certificate',
     CN: 'localhost' },
  issuerInfo:
   { C: 'UK',
     ST: 'Acknack Ltd',
     L: 'Rhys Jones',
     O: 'node.js',
     OU: 'Test TLS Certificate',
     CN: 'localhost' },
  issuer:
   { ... another certificate ... },
  raw: < RAW DER buffer >,
  valid_from: 'Nov 11 09:52:22 2009 GMT',
  valid_to: 'Nov  6 09:52:22 2029 GMT',
  fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF',
  serialNumber: 'B9B0D332A1AA5635' }

If the peer does not provide a certificate, it returns null or an empty object.

tlsSocket.getProtocol()

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

Examples:

'SSLv3'
'TLSv1'
'TLSv1.1'
'TLSv1.2'
'unknown'

See https://www.openssl.org/docs/manmaster/ssl/SSL_get_version.html for more information.

tlsSocket.getSession()

Returns the ASN.1 encoded TLS session or undefined if none was negotiated. Could be used to speed up handshake establishment when reconnecting to the server.

tlsSocket.getTLSTicket()

NOTE: Works only with client TLS sockets. Useful only for debugging, for session reuse provide session option to [tls.connect()][].

Returns the TLS session ticket or undefined if none was negotiated.

tlsSocket.localAddress

The string representation of the local IP address.

tlsSocket.localPort

The numeric representation of the local port.

tlsSocket.remoteAddress

The string representation of the remote IP address. For example, '74.125.127.100' or '2001:4860:a005::68'.

tlsSocket.remoteFamily

The string representation of the remote IP family. 'IPv4' or 'IPv6'.

tlsSocket.remotePort

The numeric representation of the remote port. For example, 443.

tlsSocket.renegotiate(options, callback)

Initiate TLS renegotiation process. The options object may contain the following fields: rejectUnauthorized, requestCert. (See [tls.createServer ()][] for details.) callback(err) will be executed with null as err, once the renegotiation is successfully completed.

NOTE: Can be used to request peer's certificate after the secure connection has been established.

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

tlsSocket.setMaxSendFragment(size)

Set maximum TLS fragment size (default and maximum value is: 16384, minimum is: 512). Returns true on success, 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.