node-simple-socket


Wrapper for Node.js sockets that makes it easy to send data compressed and crypted (RSA) / AES).

 

How does it work?

Sockets are wrapped by a class that exchanges data between two endpoints by encrypting and compressing it.

You do not need to setup anything for the encryption and compression ... you only need to start a server and connect with a client by using the new class(es)!

The new "sockets" make a handshake and share a (strong) random password, which is used for the "live" communication, with the help of RSA in the background.
This is done at the time, you start to send and receive data.

Install

``bash
npm install node-simple-socket --save
`

Usage

$3

`javascript
var simpleSocketModule = require('node-simple-socket');
`

The TypeScript way:

`typescript
import * as simpleSocketModule from 'node-simple-socket';
`

$3

`javascript
// listening for new connections
// on port 5979
simpleSocketModule.listen(5979, function(err, serverToClientSocket) {
// callback for new connections

if (err) {
// an error occurred while creating
// the client connection
}
else {
// work with new connection
// in wrapped 'serverToClientSocket'
}
}).then(function(server) {
// the server is now listening
}, function(err) {
// could not listening on port
});
`

$3

`javascript
// connect to a server (socket)
// that listens on port 5979
simpleSocketModule.connect(5979, 'server.example.com').then(function(clientToServerSocket) {
// connection established

// work with wrapped socket
// in 'clientToServerSocket'
}, function(err) {
// could not connect
});
`

$3

#### Raw data

Send:

`javascript
var dataToSend = new Buffer('Hello, TM!', 'utf8');

senderSocket.write(dataToSend).then(function(sendData) {
// data has been send
}, function(err) {
// could not send data
});
`

Receive:

`javascript
recipientSocket.read().then(function(receivedData) {
// data has been arrived
}, function(err) {
// could not receive data
});
`

#### Strings

Send:

`javascript
senderSocket.write('Hello, MK!').then(function(sendData) {
// string has been send
}, function(err) {
// could not send string
});
`

Receive:

`javascript
recipientSocket.readString().then(function(str) {
// str === "Hello, MK!"
}, function(err) {
// could not receive string
});
`

#### JSON objects

Send:

`javascript
var myObject = {
TM: 5979,
MK: '23979',
PZSUX: true
};

senderSocket.writeJSON(myObject).then(function(sendData) {
// object has been send
}, function (err) {
// could not send object
});
`

Receive:

`javascript
recipientSocket.readJSON().then(function(obj) {
// obj.TM === 5979
// obj.MK === '23979'
// obj.PZSUX === true
}, function(err) {
// could not receive object
});
`

#### Files

Send:

`javascript
senderSocket.writeFile('./fileToSend.txt').then(function(numberOfBytesSend) {
// file has been send
}, function (err) {
// could not send file
});
`

Receive:

`javascript
recipientSocket.readFile('./whereToWriteReceivedFileTo.txt').then(function(numberOfBytesLoaded) {
// file has been received
}, function (err) {
// could not receive file
});
`

#### Streams

Send:

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

fs.open('./fileToSend.txt', 'r', function(err, fd) {
if (err)
// could not open stream
}
else {
senderSocket.writeStream(fd).then(function(numberOfBytesSend) {
// stream has been send
}, function (err) {
// could not send stream
});
}
});
`

Receive:

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

fs.open('./whereToWriteReceivedFileTo.txt', 'w', function(err, fd) {
if (err) {
// could not open stream
}
else {
recipientSocket.readStream(fd).then(function(numberOfBytesLoaded) {
// stream has been received
}, function (e) {
// could not receive stream
});
}
});
`

#### Mixed (files <=> stream)

##### File => Stream

Send:

`javascript
senderSocket.writeFile('./fileToSend.txt').then(function(numberOfBytesSend) {
// file has been send
}, function (err) {
// could not send file
});
`

Receive:

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

fs.open('./whereToWriteReceivedFileTo.txt', 'w', function(err, fd) {
if (err) {
// could not open stream
}
else {
recipientSocket.readStream(fd).then(function(numberOfBytesLoaded) {
// stream has been received
}, function (e) {
// could not receive stream
});
}
});
`

##### Stream => File

Send:

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

fs.open('./fileToSend.txt', 'r', function(err, fd) {
if (err)
// could not open stream
}
else {
senderSocket.writeStream(fd).then(function(numberOfBytesSend) {
// stream has been send
}, function (err) {
// could not send stream
});
}
});
`

`javascript
recipientSocket.readFile('./whereToWriteReceivedFileTo.txt').then(function(numberOfBytesLoaded) {
// file has been received
}, function (err) {
// could not receive file
});
`

$3

`javascript
socket.on('close', function() {
// socket closed
});
socket.on('disposed', function() {
// socket has been disposed
});
socket.on('error', function(err) {
// an error occurred
});
socket.on('handshake', function(pwd) {
// socket has made a handshake
});
socket.on('password.generating', function() {
// socket is generating a password for the
// symmetric encryption
});
socket.on('password.generated', function(pwd) {
// password for the symmetric encryption
// has been generated
});
socket.on('rsakey.generating', function(keySize) {
// socket is generting a RSA key pair
});
socket.on('rsakey.generated', function(keyPair) {
// socket has been generted a RSA key pair
});
socket.on('stream.read', function(fdTarget, chunk, bytesWritten, hashOfChunk) {
// received stream / file chunk from remote
});
socket.on('stream.write', function(fdSrc, remainingBytes, chunk, hashOfChunk) {
// send stream / file chunk to remote
});
socket.on('write.after', function(err, uncryptedData, isCompressed, dataLength, cryptedData) {
// socket has (tried to) send data
});
socket.on('write.before', function(uncryptedData, isCompressed, dataLength, cryptedData) {
// socket is being to send data
});
`

$3

#### RSA

A RSA key pair is generated by node-rsa module on the client side.

The default key size for a handshake is 512.

You can change this, by setting the rsaKeySize property:

`javascript
clientSocket.rsaKeySize = 2048; // better, but takes more time
`

#### Custom password generator

While a handshake, (server) sockets generate a random password via randomBytes function of Crypto module, that is exchanged with RSA encryption.

Those passwords have a size of 48 bytes by default.

Passwords are used for the aes-256-ctr algorithm of the crypto module, which encrypts and decrypts all data of the "live" communication.

You can define a custom password generator by setting the passwordGenerator property:

`javascript
serverSocket.passwordGenerator = function() {
// generate a password as
// buffer or string
// that should be encrypted with the
// received RSA public key
// of the connected client
//
// you can return it directly
// or as promise, if you work async
};
`

#### Maximum data (package) size

By default, you cannot send and receive data with more than 16777211 bytes.

You can change this, by setting the maxPackageSize property:

`javascript
socket.maxPackageSize = 597923979;
`

#### Default values

The module provides the following (public) variables that store default settings for properties of SimpleSocket class.

`javascript
// initial value for 'compress' property
// Default: (undefined) / auto
simpleSocketModule.Compress = true;

// initial value for 'cwd' property
// Default: process.cwd()
simpleSocketModule.DefaultCWD = 'E:/test';

// initial value for 'dataTransformer' property
// Default: (undefined)
simpleSocketModule.DefaultDataTransformer = function(ctx) {
// ctx.data => the data to transform
// ctx.direction => the direction, s. https://mkloubert.github.io/node-simple-socket/enums/_index_.datatransformerdirection.html

// return transformed data as buffer
// directly or as Promise
};

// initial value for 'encoding' property
// Default: utf8
simpleSocketModule.DefaultEncoding = 'ascii';

// initial value for 'handshakeTransformer' property
// Default: (undefined)
simpleSocketModule.DefaultHandshakeTransformer = function(ctx) {
// ctx.data => the data to transform
// ctx.direction => the direction, s. https://mkloubert.github.io/node-simple-socket/enums/_index_.datatransformerdirection.html

// return transformed data as buffer
// directly or as Promise
};

// initial value for 'maxPackageSize' property
// Default: 16777211
simpleSocketModule.DefaultMaxPackageSize = 239795979;

// initial value for 'passwordGenerator' property
// Default: (undefined)
simpleSocketModule.DefaultPasswordGenerator = function() {
// return transformed password as buffer
// directly or as Promise
};

// initial value for 'readBufferSize' property
// Default: 8192
simpleSocketModule.DefaultReadBufferSize = 10240;

// initial value for 'rsaKeySize' property
// Default: 512
simpleSocketModule.DefaultRSAKeySize = 4096;
``

Documentation

The full API documentation can be found here.

Migration

$3

* since version 2.0 there is an important protocol update to improve encryption ... communication with older versions (less than 2.0) might not work anymore, when using compression