Awesome Open Source
Awesome Open Source

@nodertc/dtls

stability-experimental Build Status npm node license downloads Gitter chat

Secure UDP communications using Datagram Transport Layer Security protocol version 1.2 in pure js. Follow RFC6347, RFC7627.

asciicast

Support

Buy Me A Coffee

Features

  • no native dependecies!
  • modern secure ciphers (by default)
  • in-out fragmentation / in-out retransmission
  • merge outgoing handshakes

Usage

npm i @nodertc/dtls
const dtls = require('@nodertc/dtls');

const socket = dtls.connect({
  type: 'udp4',
  remotePort: 4444,
  remoteAddress: '127.0.0.1',
});

socket.on('error', err => {
  console.error(err);
});

socket.on('data', data => {
  console.log('got message "%s"', data.toString('ascii'));
  socket.close();
});

socket.once('connect', () => {
  socket.write('Hello from Node.js!');
});

Suppored ciphers:

  • TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 (nodejs v11.2+ only)
  • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (nodejs v11.2+ only)
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_128_GCM_SHA256
  • TLS_RSA_WITH_AES_256_GCM_SHA384
  • TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 (nodejs v11.2+ only)
  • TLS_PSK_WITH_AES_128_GCM_SHA256
  • TLS_PSK_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_PSK_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256

API

  • dtls.connect(options: Options [, callback: function]) : Socket

Creates an esteblished connection to remote dtls server. A connect() function also accept all options for unicast.createSocket() or dgram.createSocket(). If options.socket is provided, these options will be ignored.

The callback function, if specified, will be added as a listener for the 'connect' event.

  • options.socket

A duplex stream in a common case. It is also unicast or dgram socket instance. Used if you want a low level control of your connection.

  • options.extendedMasterSecret: bool, [default=true]

This option enable the use Extended Master Secret extension. Enabled by default.

  • options.checkServerIdentity: function(certificate): bool

Optional certificate verify function.

  • options.certificate: Buffer

PEM-encoded client certificate, optional. Supports RSASSA-PKCS1-v1_5 and ECDSA certificates.

  • options.certificatePrivateKey: Buffer

PEM-encoded private key for client certificate.

  • options.maxHandshakeRetransmissions: number

The number of retransmissions during on handshake stage.

  • options.alpn: string | string[]

The list of the supported ALPN protocols.

  • options.pskIdentity: String|Buffer

Identity string for PSK key exchange, see RFC4279.

  • options.pskSecret: String|Buffer

Secret data for the identity string of PSK key exchange.

  • options.ignorePSKIdentityHint: boolean, default=true

Both clients and servers may have pre-shared keys with several different parties. The client indicates which key to use by including a "PSK identity" (see options.pskIdentity above) in the ClientKeyExchange message. To help the client in selecting which identity to use, the server can provide a "PSK identity hint" in the ServerKeyExchange message.

  • options.cipherSuites: number[]|string[]

List of supported by client cipher suites. Default cipher suites:

  • TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 (in nodejs v11+ only)
  • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (in nodejs v11+ only)
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

See above a full list of supported cipher suites.

  • class Socket

A Socket is also a duplex stream, so it can be both readable and writable, and it is also a EventEmitter.

  • Socket.setMTU(mtu: number): void

Set MTU (minimal transfer unit) for this socket, 1420 bytes maximal.

  • Socket.getMTU(): number

Return MTU (minimal transfer unit) for this socket, 1200 bytes by default.

  • Socket.setTimeout(timeout: number[, callback: function()])

Sets the socket to timeout after timeout milliseconds of inactivity on the socket. By default dtls.Socket do not have a timeout.

The optional callback parameter will be added as a one-time listener for the 'timeout' event.

  • Socket.close(): void

Close socket, stop listening for socket. Do not emit data events anymore.

  • Socket.alpnProtocol: string

Get a string that contains the selected ALPN protocol.

  • Event: connect

The 'connect' event is emitted after the handshaking process for a new connection has successfully completed.

  • Event: timeout

Emitted if the socket times out from inactivity. This is only to notify that the socket has been idle.

  • dtls.constants: Object
    • cipherSuites: Object A full list supported cipher suites. See above for detailes.

How to debug?

Start dtls server:

docker run -it --name dtlsd --rm -e "GNUTLS_DEBUG_LEVEL=2" -e "PRIORITY=NORMAL:+AEAD:+ECDHE-RSA:+VERS-DTLS1.2" -e "KEYFILE=key-rsa.pem" -e "CERTFILE=cert-rsa.pem" -p 4444:4444/udp nodertc/dtls-server:1

Start default client:

npm start

License

MIT, 2018 - 2019 © Dmitriy Tsvettsikh


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,556,467
Nodejs (54,863
Node (13,130
Js (9,615
Security (8,739
Crypto (2,354
Webrtc (1,936
Udp (1,124
Tls (952
Aes (702
Rsa (612
Sha256 (378
Safety (205
Ecdsa (148
Related Projects