nodejs-dtls

@mobius-software-ltd/nodejs-dtls

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

Features

• no native dependecies!
• modern secure ciphers - AEAD with ECDHE
• support set / get MTU
• in / out handshake fragmentation
• handshake retransmission
• merge outgoing handshakes

Usage

npm i nodejs-dtls

const dtls = require('nodejs-dtls');
 
const socket = dtls.connect({
  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_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

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.

• 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.

How to debug?

Start openssl dtls server:

npm run openssl-server

or start GnuTLS dtls server (more debug messages):

# tested in Ubuntu 16, use docker if you are Windows / MacOS user. 
npm run gnutls-server

Start default client:

npm start

License

MIT, 2018 © Dmitriy Tsvettsikh