node-dtls - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #llm #golang #android #machine-learning #linux #nodejs #windows #cli #security #mcp

node-dtls

(★ 59)

JavaScript DTLS implementation for Node.js

File Explorer

Download Latest Version (.zip)

- client.js
- send_throughput.js
- server.js
- throughput.js
- DtlsCertificate.js
- DtlsChangeCipherSpec.js
- DtlsClientHello.js
- DtlsClientKeyExchange_rsa.js
- DtlsExtension.js
- DtlsFinished.js
- DtlsHandshake.js
- DtlsHelloVerifyRequest.js
- DtlsPlaintext.js
- DtlsPreMasterSecret.js
- DtlsProtocolVersion.js
- DtlsRandom.js
- DtlsServerHello.js
- DtlsServerHelloDone.js
- DtlsServerKeyExchange.js
- index.js
- Packet.js
- PacketSpec.js
- - certificate.pem
- .jshintrc
- Buffer.js
- ClientHandshakeHandler.js
- HandshakeBuilder.js
- openssl.js
- Packets.js
- PacketSpec.js
- prf.js
- SecurityParameterContainer.js
- SecurityParameters.js
- SequenceNumber.js
.editorconfig
.gitignore
.jshintrc
.travis.yml
BufferBuilder.js
BufferReader.js
Certificate.js
certificateUtilities.js
CipherInfo.js
ClientHandshakeHandler.js
dtls.js
DtlsRecordLayer.js
DtlsServer.js
DtlsSocket.js
HandshakeBuilder.js
index.js
KeyContext.js
LICENSE
package.json
prf.js
README.md
SecurityParameterContainer.js
SecurityParameters.js
SequenceNumber.js
ServerHandshakeHandler.js

# Installation Guide

1. Get the code

git clone https://github.com/Rantanen/node-dtls

Downloads the entire project code from GitHub to your computer.

cd node-dtls

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm install

Downloads and installs the libraries listed in package.json.

npm start

Starts the development/run server.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# See [nodertc/dtls](https://github.com/nodertc/dtls) for a maintained implementation

----

## node-dtls
#### DTLS implementation in JavaScript (Work in progress)

[![Travis build](https://travis-ci.org/Rantanen/node-dtls.svg?branch=master)](https://travis-ci.org/Rantanen/node-dtls)
[![Test Coverage](https://codeclimate.com/github/Rantanen/node-dtls/badges/coverage.svg)](https://codeclimate.com/github/Rantanen/node-dtls/coverage)
[![Code Climate](https://codeclimate.com/github/Rantanen/node-dtls/badges/gpa.svg)](https://codeclimate.com/github/Rantanen/node-dtls)

[![No Maintenance Intended](http://unmaintained.tech/badge.svg)](http://unmaintained.tech/)

_This repository contains an unfinished DTLS implementation written in
JavaScript. The implementation was an attempt to give Node.js DTLS support
while waiting for https://github.com/nodejs/node/issues/2398 to get resolved._

_DTLS handshake and packet communication has been implemented. The largest
missing things are re-negotiation, other cipher suites, respecting configuration
options and handling the DTLS alerts._

_The primary goal of the project was to "support" DTLS in the sense that Node.js
could communicate with services that require DTLS. The code should not be
relied on for any actual security._

Datagram Transport Layer Security (DTLS) Protocol implementation for Node.js
written in JavaScript.

While Node.js still lacks support for DTLS protocol, this library attempts to
fix the issue. This is in no way a security implementation as it's main goal is
to allow using protocols that _require_ DTLS. While the library implements the
proper DTLS encryption and validation, there has been no effort to protect it
against well known TLS attacks.

#### Example

##### Server

```javascript
var dtls = require( 'dtls' );
var fs = require( 'fs' );

var pem = fs.readFileSync( 'server.pem' );

var server = dtls.createServer({ type: 'udp4', key: pem, cert: pem });
server.bind( 4433 );

server.on( 'secureConnection', function( socket ) {

console.log( 'New connection from ' +
    [ socket.rinfo.address, socket.rinfo.port ].join(':') );

socket.on( 'message', function( message ) {
    
    // Echo the message back
    socket.send( message );
  });
});
```

##### Client

```javascript
var dtls = require( '../' );

dtls.setLogLevel( dtls.logLevel.FINE );

var client = dtls.connect( 4433, 'example.org', 'udp4', function() {
    client.send( new Buffer( 'foo\n' ) );
});

client.on( 'message', function( msg ) {
    console.log( msg );
});
```

#### Current state

- [x] DTLS 1.2 handshake in server role
- [x] DTLS 1.2 handshake in client role
  - Still some problems when it comes to receiving messages. Not very confident.
- [x] Handle application data
- [x] Proper API to handle sessions/messages outside the node-dtls internals.
- [ ] DTLS 1.0 handshake in server role
  - There shouldn't be _too_ many changes. Main one is propably the PRF hash.
- [ ] Handle renegotiation
- [ ] Robustness
  - [x] Handshake reassembly/buffering/reordering
  - [x] Retransmission
  - [ ] Handle alert-messages
  - [ ] Validate handshake state and expected messages

## API

#### dtls.setLogLevel( level )

- `level` - [logg](https://github.com/dpup/node-logg) log level. For convenience possible log levels are also available in `dtls.logLevel.*`

Sets the global node-dtls logging level.

node-dtls uses /logg/ for logging and tracing various dtls events. This function can be used to alter the amount of information that is logged during the DTLS handshake/session. In future logging will most likely be disabled by default, but for now the default log level (FINE) is quite verbose.

-----

#### dtls.createServer(options[, callback])

- `options` - Server options, see below.
- `callback` - Optional callback registered to the `secureConnect` event.

Creates a `dtls.DtlsServer`.

Mimics the Node.js [tls.createServer](https://nodejs.org/api/tls.html#tls_tls_createserver_options_secureconnectionlistener) function. Although given DTLS is a datagram protocol, the actual network object is created with [dgram.createSocket()](https://nodejs.org/api/dgram.html#dgram_dgram_createsocket_options_callback).

`options` object is a rough combination of the option objects of `tls.createServer()` and `dgram.createSocket()`. DTLS-specific options are parsed by the `dtls.DtlsServer` and the dgram-options are passed directly to `dgram.createSocket()`.

- `type` - _Required._ `dgram` socket type. Passed to `dgram.createSocket()`.
- `key` - _Required._ The server private key in PEM format.
- `cert` - _Required._ The server certificate in PEM format.

##### Example

```javascript
var dtls = require( 'dtls' );
var fs = require( 'fs' );
    
var pem = fs.readFileSync( 'server.pem' );
    
var server = dtls.createServer({ type: 'udp4', cert: pem, key: pem });
server.bind( 4433 );
    
server.on( 'secureConnection', function( socket ) {
  console.log( 'New secure connection: ' +
    [ socket.rinfo.address, socket.rinfo.port ].join( ':' ) );
});
```

The server.pem certificate can be created with

openssl req -x509 -nodes -newkey rsa:2048 -keyout server.pem -out server.pem

-----

#### dtls.connect( port, address, type, callback )

- `port` - Remote port to connect to.
- `address` - Remote address to connect to.
- `type` - Datagram socket type: `udp4` or `udp6`. Ssee [`dgram`](https://nodejs.org/api/dgram.html) for full explanation.
- `callback` - Callback for when the handshake is ready.

Initiates a connection to a remote server and returns the `dtls.DtlsSocket`.

##### Example

```javascript
var dtls = require( 'dtls' );

var client = dtls.connect( 4433, 'example.org', 'udp4', function() {
    client.send( new Buffer( 'foo\n' ) );
});

client.on( 'message', function( msg ) {
    console.log( msg );
});
```

-----

### Class: dtls.DtlsServer

Server accepting DTLS connections. Created with `dtls.createServer`

-----

#### Event: 'secureConnection'

- `socket` - dtls.DtlsSocket

Emitted after the `DtlsSocket` has finished handshaking a connection and is ready for use.

-----

#### server.bind();

- `port` - UDP port to listen to. This is passed over to `socket.bind()` of the underlying `dgram.Socket`

Starts listening to the defined port. Delegated to `dgram.Socket#bind()`

-----
-----

### Class: dtls.DtlsSocket

A single DTLS session between a local and remote endpoints. Acquired through the `server::secureConnection` event.

----

#### Event: 'secureConnect'

Emitted after the `DtlsSocket` has finished handshaking a connection.

This method is emitted after the server sends the `Finished` handshake message. As datagram protocols aren't reliable transports, the handshake might still be in progress if that last handshake message was lost. It is recommended that the client initiates the actual application communication as the client gets confirmation on when the handshake has been completed.

_Note:_ that usually it is impossible to catch this event as it is raised before the user has a reference to the socket. Use `server::secureConnection` event instead.

-----

#### Event: 'message'

- `buffer` - Application data within a [`Buffer`](https://nodejs.org/api/buffer.html#buffer_class_buffer).

Emitted when the socket has received and decrypted application data from the remote endpoint.

##### Example

```javascript
var server = dtls.createServer({
    type: 'udp4',
    key: pem,
    cert: pem
});
server.bind( 4433 );

server.on( 'secureConnection', function( socket ) {
  socket.on( 'message', function( message ) {
    console.log( 'In: ' + message.toString( 'ascii' ) );
  });
});
```

-----

#### socket.send( buffer[, offset][, length][, callback] )

- `buffer` - `Buffer` object to send.
- `offset` - Offset in the buffer where the message starts. Optional.
- `length` - Number of bytes in the message. Optional.
- `calback` - called when the message has been sent. Optional.

Sends application data to the remote endpoint.

##### Example

```javascript
var server = dtls.createServer({
    type: 'udp4',
    key: pem,
    cert: pem
});
server.bind( 4433 );

server.on( 'secureConnection', function( socket ) {
  socket.send( new Buffer( 'Hello!\n', 'ascii' ) );
});
```

-----

## References

[Datagram Transport Layer Security Version 1.2, RFC 6347]
(https://tools.ietf.org/html/rfc6347)

[The Transport Layer Security (TLS) Protocol Version 1.2, RFC 5246]
(https://tools.ietf.org/html/rfc5246)