ssltunnel - npm Package Compare versions

Comparing version 0.0.4 to 0.0.5

bin/run_ssltunnel.js

 var ssltunnel = require('./../lib/ssltunnel');
 
 var argv = require('optimist')
+    
     .usage('Usage $0')
-    .demand('c')
-    .alias('c', 'client_port')
-    .describe('c', 'The client port number')
-    .default('h','localhost')
-    .alias('h', 'client_host')
-    .describe('h', 'The client hostname')
-    .demand('s')
-    .alias('s', 'server_port')
-    .describe('s', 'The server port number')
+
     .demand('r')
     .alias('r', 'role')
-    .describe('r', 'The role of the tunnel component, either "client" or "server"')
-    .demand('server_public_cert')
-    .describe('server_public_cert', 'Server public certificate file')
-    .describe('server_public_cert', 'Server private certificate file')
-    .demand('client_public_cert')
-    .describe('client_public_cert', 'Client public certificate file')
-    .describe('client_public_cert', 'Client private certificate file')
+    .describe('r', 'The role of the tunnel component, either \'client\' or \'server\'')
+
+    .demand('p')
+    .alias('p', 'port')
+    .describe('p', 'The port of ssltunnel\'s server')
+
+    .default('h','localhost')
+    .alias('h', 'host')
+    .describe('h', 'The hostname of ssltunnel\'s server')
+
+    .describe('local_port', 'The local port ssltunnel\'s client will listen on')
+    .describe('remote_port', 'The port on the remote machine ssltunnel\'s server will connect to')    
+    .default('remote_host','localhost')
+    .describe('remote_host', 'The hostname of the remote machine ssltunnel\'s server will connect to')    
+    
+    .demand('srv_pub_cert')
+    .describe('srv_pub_cert', 'Public certificate file for ssltunnel\'s server')
+    
+    .describe('srv_prv_cert', 'Private certificate file for ssltunnel\'s server')
+
+    .demand('clt_pub_cert')
+    .describe('clt_pub_cert', 'Public certificate for ssltunnel\'s client')
+    
+    .describe('clt_prv_cert', 'Private certificate for ssltunnel\'s client')
+
     .check(function(argv) {
@@ -31,3 +42,3 @@
 
-        if (argv.role === 'client' && !argv.client_private_cert)
+        if (argv.role === 'client' && (!argv.clt_prv_cert || !argv.local_port))
         {
@@ -38,3 +49,3 @@ // if this is a client component it must have client private key
 
-        if (argv.role === 'server' && !argv.server_private_cert)
+        if (argv.role === 'server' && (!argv.srv_prv_cert || !argv.remote_port))
         {
@@ -52,17 +63,24 @@ // if this is a server component it must have server private key
 var options = {     
-        'client_private_cert' : argv.client_private_cert,
-        'client_public_cert' : argv.client_public_cert,
-        'server_public_cert' : argv.server_public_cert,
-        'client_port' : argv.c,
-        'server_port' : argv.s
+        'client_public_cert' : argv.clt_pub_cert,
+        'server_public_cert' : argv.srv_pub_cert,
     };
 
 if (argv.role === 'client') {
-    options.client_private_cert = argv.client_private_cert;
+
+    options.client_private_cert = argv.clt_prv_cert;
+    options.client_port = argv.port;
+    options.client_host = argv.host;
+    options.server_port = argv.local_port;
+
     ssltunnel.createClient(options);
 }
 else {
-    options.server_private_cert = argv.server_private_cert;
+
+    options.server_private_cert = argv.srv_prv_cert;
+    options.client_port = argv.remote_port;
+    options.client_host = argv.remote_host;
+    options.server_port = argv.port;
+
     ssltunnel.createServer(options);
 }
 

lib/ssltunnel.js

@@ -78,3 +78,3 @@ var tls = require('tls');
         {
-            serviceSocket = clientPackage.connect(clientPort);          
+            serviceSocket = clientPackage.connect(clientPort, clientHost);          
         }
@@ -97,3 +97,12 @@
 
+    
+    if (isClient) {
+        console.log('Running \'client\' role. Listening on %d, encrypting and forwarding to ssltunnel\'s server on %s:%d.', 
+            options.server_port, options.client_host, options.client_port);
+    } else {
+        console.log('Running \'server\' role. Listening on %d, decrypting and forwarding to real server machine on %s:%d.', 
+            options.server_port, options.client_host, options.client_port);
+    }
+
 }
 

package.json

@@ -5,3 +5,3 @@ {
   "description": "TCP over SSL / TLS tunnel",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "homepage": "https://github.com/dimastopel/ssltunnel",
@@ -8,0 +8,0 @@ "repository": {

README.md

@@ -0,8 +1,25 @@
+## What is ssltunnel?
+
 This is a lightweight TCP over SSL / TLS tunnel running over node. If you need to add confidentiality (privacy), integrity, and authenticity to your TCP stream this is the tool for you.
 
-In order to run this module you will need to download and install nodejs (don't worry, it is small): http://nodejs.org/#download
+## Installation
 
-Additionaly, you will need to create client and server SSL certificates. The easiest way to do so is to use openssl [http://www.openssl.org/]. The steps are the same for both client and server certificates. Note that you have test certificates to play with under the testcerts folder. 
+Please follow the following steps to get it up and running:
 
+1. [Download and install latest node](http://nodejs.org/#download) (don't worry, it is small) (don't worry, it is small)
+2. Enter CMD and run: ```npm install ssltunnel```
+3. The ssltunnel package now resides under ```./node_modules/ssltunnel```
 
+## Creating certificates 
+
+ssltunnel uses client and server certificates for creating proper TLS connection. While server certificate is enough to assure confidentiality and integrity, client certificate is required for assuring authenticity.
+
+Test certificates are provided in the ```testcerts``` folder. You can start playing with sltunnel using them. 
+
+> Please do not use test certificates for production.
+
+You can easily create your certificates using [openssl](http://www.openssl.org/). Each certificate is represented by a key pair. 
+The steps are the same for both client and server certificates. See some example of certificate generation below.
+
+```
 	dimast@DIMAST-LAPTOP /d/src/mygithub/temp
@@ -39,19 +56,95 @@ $ openssl genrsa -out private.pem 2048
 	private.pem  public.pem
+```
 
+> PLEASE KEEP YOUR PRIVATE KEYS SECURE
 
-Now you have the key pair for you certificate. You can use it for either client or server component. Please create another pair for the remaining component. PLEASE KEEP YOU PRIVATE KEYS SECURE. 
+## Running the ssltunnel
 
-Now you can run the tunnel. Suppose you have your client component called my_client and server component called my_server. my_server is listening on port 8080. 
+Imagine you have a client-server application. The server is running on ```my_host:8080```. You can route the traffic via ssl tunnel by 
+creating both ssltunnel's server and client:
 
-So you run the ssltunnel's client component on the client machine to listen on port 8080. Let's choose port 54443 for our ssltunnel server.
+```
+d:\src\mygithub\ssltunnel\bin>ssltunnel.cmd -r server \
+-p 54443 \
+-h my_ssltunnel_server_host \
+--remote_port 8080 \
+--remote_host my_host \
+--srv_pub_cert ..\testcerts\local_public.pem \
+--clt_pub_cert ..\testcerts\cc_public_test.pem \
+--srv_prv_cert ..\testcerts\local_private.pem 
 
-	> cd bin
-	> ssltunnel.cmd -r client -c 54443 -s 8080 --server_public_cert ../testcerts/local_public.pem --client_public_cert ../testcerts/cc_public_test.pem --client_private_cert ../testcerts/cc_private_test.pem
+Running 'server' role. Listening on 54443, decrypting and forwarding to real server machine on my_host:8080.
+```
 
-And you run ssltunnel's server component on the server on port 54443, and configure it to work against my_server on port 8080:
-	
-	> cd bin
-	> ssltunnel.cmd -r server -s 54443 -c 8080 --server_public_cert ../testcerts/local_public.pem --client_public_cert ../testcerts/cc_public_test.pem --server_private_cert ../testcerts/local_private.pem
+```
+d:\src\mygithub\ssltunnel\bin>ssltunnel.cmd -r client \
+-p 54443 \
+-h my_ssltunnel_server_host \
+--local_port 54080 \
+--srv_pub_cert ..\testcerts\local_public.pem \
+--clt_pub_cert ..\testcerts\cc_public_test.pem \
+--clt_prv_cert ..\testcerts\cc_private_test.pem
 
-That's it. You can connect with your client to localhost:8080 and ssltunnel will take care on forwarding it to the real server, securely.
+Running 'client' role. Listening on 54080, encrypting and forwarding to ssltunnel's server on my_ssltunnel_server_host:54443.
+```
 
+Now, just point you client to the machine where ssltunnel's client is running (localhost?) port 54808, and ssltunnel will 
+take care of forwarding the data to the server securely.
+
+This is the list of all arguments ssltunnel supports:
+
+```
+d:\src\mygithub\ssltunnel\bin>ssltunnel.cmd
+Usage node d:\src\mygithub\ssltunnel\bin\run_ssltunnel.js
+
+Options:
+  -r, --role      The role of the tunnel component, either 'client' or 'server'          [required]
+  -p, --port      The port of ssltunnel's server                                         [required]
+  -h, --host      The hostname of ssltunnel's server                                     [default: "localhost"]
+  --local_port    The local port ssltunnel's client will listen on
+  --remote_port   The port on the remote machine ssltunnel's server will connect to
+  --remote_host   The hostname of the remote machine ssltunnel's server will connect to  [default: "localhost"]
+  --srv_pub_cert  Public certificate file for ssltunnel's server                         [required]
+  --srv_prv_cert  Private certificate file for ssltunnel's server
+  --clt_pub_cert  Public certificate for ssltunnel's client                              [required]
+  --clt_prv_cert  Private certificate for ssltunnel's client
+```
+
+## API
+
+You can use the library in your node project. The are two exported methods:
+
+```
+var ssltunnel = require('ssltunnel');
+ssltunnel.createServer(options)
+ssltunnel.createClient(options)
+```
+
+The options are basically property bag with data similar to what arguments contain. Feel free to see usage example in ```bin/run_ssltunnel.js```
+
+Please see detailed list below:
+
+* options.client_port:
+For createServer() this is a remote machine port.
+For createClient() this is a ssltunnel's server port.
+
+* options.client_host: 
+For createServer() this is a remote machine host.
+For createClient() this is a ssltunnel's server host.
+
+* options.server_port:
+For createServer() this is a listening port for ssltunnel's server.
+For createClient() this is a listening port for ssltunnel's client.
+
+* options.server_public_cert: Server public certificate. 
+
+* options.server_private_cert:
+Server private certificate. Not needed for createClient().
+
+* options.client_public_cert:
+Client  public certificate. 
+
+* options.client_private_cert:
+Client private certificate. Not needed for createServer().
+
+## Enjoy!

No alert changes

Improved metrics

Total package byte prevSize

17118

increased by28.89%

Lines of code

143

increased by8.33%

Number of lines in readme file

150

increased by163.16%

No dependency changes