Simple end-to-end encrypted, secure channels using Noise Protocol Framework and libsodium secretstream
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Comments in basic examples Oct 28, 2018
tests Check for destroyed after "handoff" Nov 14, 2018
.travis.yml Add travis Oct 11, 2018
LICENSE Init Oct 9, 2018
README.md Add link to examples Oct 28, 2018
index.js Clean _transport completely Nov 14, 2018
package.json 1.0.0 Nov 14, 2018

README.md

noise-peer

Build Status

Simple end-to-end encrypted, secure channels using Noise Protocol Framework and libsodium secretstream

Usage

Below is an example of a secure UPPERCASE echo server.

Server:

var peer = require('noise-peer')
var through = require('through2')
var pump = require('pump')
var net = require('net')

var server = net.createServer(function (rawStream) {
  var sec = peer(rawStream, false)

  pump(sec, through(function (buf, _, cb) {
    cb(null, buf.toString().toUpperCase())
  }), sec)
})

server.listen(5000)

Client:

var peer = require('noise-peer')
var pump = require('pump')
var net = require('net')

var rawStream = net.connect(5000)

var sec = peer(rawStream, true)

pump(sec, process.stdout)
sec.end('beep boop\n')

More examples are available in examples

API

var {publicKey, secretKey} = peer.keygen()

Generate a new key pair for use with noiseOpts. See the Handshake Pattern examples

var secureStream = peer(rawStream, isInitiator, [noiseOpts])

Create a new peer, performing handshaking transparently. Note that all messages are chunked to ~64kb size due to a 2 byte length header. By default the Noise NN pattern is used, which simply creates a forward secret channel. This does not authenticate either party. See below for other handshake pattern exapmles.

secureStream.initiator

Boolean indicating whether the stream is a client/initiator or a server/responder, as given by the isInitiator constructor argument.

secureStream.rawStream

Access to the rawStream passed in the constructor

secureStream.end([chunk][, encoding][, callback])

Special mention, as this also sends a FINISH message to the other party, which signals that the stream is to end and no more messages are to be expected. This is important to know that an active adversary did not truncate the stream.

secureStream.setTimeout(timeout[, callback])

Call setTimeout on the underlying rawStream if supported. This function will be undefined if not supported

secureStream.on('timeout')

Bubble timeout event from the underlying rawStream if supported. You should call either .end() (which sends a FINISH message to the other peer) or .destroy() the stream manually (like eg. net specifies).

secureStream.on('handshake', {remoteStaticKey, remoteEphemeralKey})

Emitted when the handshaking has succeeded. remoteStaticKey may be null if you're using a pattern which does not use or receive a remote static key. Both will be Buffers, but be cleared immediately after the handshake event.

Handshake Pattern examples

To have mutual authentication use the XX pattern, add a static keypair and provide a onstatickey function on both sides:

var opts = {
  pattern: 'XX',
  staticKeyPair: peer.keygen(),
  onstatickey: function (remoteKey, done) {
    if (remoteKey.equals(someSavedKey)) return done()

    return done(new Error('Unauthorized key'))
  }
}

To have have client authentication but use a preshared server public key use the XK pattern, add a static keypair on both sides, a remote static key on the client and provide a onstatickey function on the server:

var serverKeys = peer.keygen()

var clientOpts = {
  pattern: 'XK',
  staticKeyPair: peer.keygen(),
  remoteStaticKey: serverKeys.publicKey
}

var serverOpts = {
  pattern: 'XK',
  staticKeyPair: serverKeys,
  onstatickey: function (remoteKey, done) {
    if (remoteKey.equals(someSavedClientKey)) return done()

    return done(new Error('Unauthorized key'))
  }
}

Install

npm install noise-peer

License

ISC