2018-09-19 15:22:17 +00:00
<!DOCTYPE html>
< html lang = "en" >
< head >
< meta charset = "utf-8" >
< title > TorProcess.js - Documentation< / title >
< script src = "scripts/prettify/prettify.js" > < / script >
< script src = "scripts/prettify/lang-css.js" > < / script >
<!-- [if lt IE 9]>
< script src = "//html5shiv.googlecode.com/svn/trunk/html5.js" > < / script >
<![endif]-->
< link type = "text/css" rel = "stylesheet" href = "styles/prettify.css" >
< link type = "text/css" rel = "stylesheet" href = "styles/jsdoc.css" >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
< / head >
< body >
< input type = "checkbox" id = "nav-trigger" class = "nav-trigger" / >
< label for = "nav-trigger" class = "navicon-button x" >
< div class = "navicon" > < / div >
< / label >
< label for = "nav-trigger" class = "overlay" > < / label >
< nav >
< h2 > < a href = "index.html" > Home< / a > < / h2 > < h3 > Classes< / h3 > < ul > < li > < a href = "ControlServer.html" > ControlServer< / a > < ul class = 'methods' > < li data-type = 'method' > < a href = "ControlServer.html#.instance_info" > instance_info< / a > < / li > < li data-type = 'method' > < a href = "ControlServer.html#close" > close< / a > < / li > < li data-type = 'method' > < a href = "ControlServer.html#createDNSServer" > createDNSServer< / a > < / li > < li data-type = 'method' > < a href = "ControlServer.html#createHTTPServer" > createHTTPServer< / a > < / li > < li data-type = 'method' > < a href = "ControlServer.html#createSOCKSServer" > createSOCKSServer< / a > < / li > < li data-type = 'method' > < a href = "ControlServer.html#createTorPool" > createTorPool< / a > < / li > < li data-type = 'method' > < a href = "ControlServer.html#listen" > listen< / a > < / li > < li data-type = 'method' > < a href = "ControlServer.html#listenTcp" > listenTcp< / a > < / li > < li data-type = 'method' > < a href = "ControlServer.html#listenWs" > listenWs< / a > < / li > < / ul > < / li > < li > < a href = "DNSServer.html" > DNSServer< / a > < ul class = 'methods' > < li data-type = 'method' > < a href = "DNSServer.html#listen" > listen< / a > < / li > < / ul > < / li > < li > < a href = "HTTPServer.html" > HTTPServer< / a > < ul class = 'methods' > < li data-type = 'method' > < a href = "HTTPServer.html#listen" > listen< / a > < / li > < / ul > < / li > < li > < a href = "SOCKSServer.html" > SOCKSServer< / a > < ul class = 'methods' > < li data-type = 'method' > < a href = "SOCKSServer.html#listen" > listen< / a > < / li > < / ul > < / li > < li > < a href = "TorPool.html" > TorPool< / a > < ul class = 'methods' > < li data-type = 'method' > < a href = "TorPool.html#add" > add< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#add_instance_to_group" > add_instance_to_group< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#add_instance_to_group_at" > add_instance_to_group_at< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#add_instance_to_group_by_name" > add_instance_to_group_by_name< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#create" > create< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#create_instance" > create_instance< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#exit" > exit< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#get_config_at" > get_config_at< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#get_config_by_name" > get_config_by_name< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#instance_at" > instance_at< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#instance_by_name" > instance_by_name< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#instances_by_group" > instances_by_group< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#new_identites" > new_identites< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#new_identites_by_group" > new_identites_by_group< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#new_identity_at" > new_identity_at< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#new_identity_by_name" > new_identity_by_name< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#next" > next< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#next_by_group" > next_by_group< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#remove" > remove< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#remove_at" > remove_at< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#remove_by_name" > remove_by_name< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#remove_instance_from_group" > remove_instance_from_group< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#remove_instance_from_group_at" > remove_instance_from_group_at< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#remove_instance_from_group_by_name" > remove_instance_from_group_by_name< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#set_config_all" > set_config_all< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#set_config_at" > set_config_at< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#set_config_by_group" > set_config_by_group< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#set_config_by_name" > set_config_by_name< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#signal_all" > signal_all< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#signal_at" > signal_at< / a > < / li > < li data-type = 'method' > < a href = "TorPool.html#signal_by_group" > signal_by_group< / a > < /li
< / nav >
< div id = "main" >
< h1 class = "page-title" > TorProcess.js< / h1 >
< section >
< article >
< pre class = "prettyprint source linenums" > < code > const spawn = require('child_process').spawn;
const fs = require('fs');
const crypto = require('crypto');
const { connect } = require('net');
const os = require('os');
const Promise = require('bluebird');
const _ = require('lodash');
const { EventEmitter } = require('eventemitter3');
const shell = require('shelljs');
const getPort = require('get-port');
const del = require('del');
const temp = require('temp');
2019-11-22 04:13:31 +00:00
const { TorController } = require('@deadcanaries/granax');
2018-09-19 15:22:17 +00:00
const nanoid = require("nanoid");
const winston = require('winston');
Promise.promisifyAll(temp);
Promise.promisifyAll(fs);
temp.track();
/**
* @typedef {Object} InstanceDefinition
* @property {string} [Name] - Name of the instance.
* @property {string[]|string} [Group=[]] - Groups the instance belongs to.
* @property {Object} [Config={}] - Configuration that will be passed to Tor. See {@link https://bit.ly/2QrmI3o|Tor Documentation} for all possible options.
* @property {Number} [Weight] - Weight of the instance for "weighted" load balancing.
*/
/**
* Class that represents an individual Tor process.
*
* @extends EventEmitter
*/
class TorProcess extends EventEmitter {
/**
* Creates an instance of `TorProcess`
*
* @param {string} tor_path - Path to the Tor executable.
* @param {InstanceDefinition} [definition] - Object containing various options for the instance. See {@link InstanceDefinition} for more info.
* @param {Object} [granax_options] - Object containing options that will be passed to granax.
* @param {Logger} [logger] - A winston logger. If not provided no logging will occur.
*/
constructor(tor_path, definition, granax_options, logger) {
super();
this.logger = logger || require('./winston_silent_logger');
definition = definition || {};
definition.Group = definition.Group ? [].concat(definition.Group) : [];
definition.Config = definition.Config || {};
this._definition = definition;
/**
* Path to the Tor executable.
*
* @type {string}
* @public
*/
this.tor_path = tor_path;
/**
* Object containing options that will be passed to granax.
*
* @type {Object}
* @public
*/
this.granax_options = granax_options;
/**
* The password that will be set for the control protocol.
*
* @type {string}
* @public
*/
this.control_password = crypto.randomBytes(128).toString('base64');
this._id = nanoid(12);
this.tor_config.DataDirectory = this.tor_config.DataDirectory || temp.mkdirSync();
}
/**
* Kills the Tor process.
*
* @async
* @returns {Promise}
*/
async exit() {
let p = new Promise((resolve, reject) => {
this.once('process_exit', (code) => {
resolve();
});
});
this.process.kill('SIGINT');
await p;
}
/**
* The unique identifier assigned to each instance.
*
* @readonly
* @type {string}
*/
get id() { return this._id; }
/**
* Groups the instance are currently in.
*
* @readonly
* @type {string[]}
*/
get instance_group() {
return (this.definition & & this.definition.Group);
}
/**
* Either the "Name" property of the definition or the {@link TorProcess#id} property.
*
* @readonly
* @type {string}
*/
get instance_name() {
return (this.definition & & this.definition.Name) || this.id;
}
/**
* The definition used to create the instance.
*
* @readonly
* @type {string}
*/
get definition() { return this._definition; }
/**
* The configuration passed to Tor. The same value as `definition.Config`.
*
* @readonly
* @type {Object}
*/
get tor_config() { return this.definition.Config; }
/**
* Port Tor is bound to for DNS traffic.
*
* @readonly
* @type {number}
*/
get dns_port() {
return this._ports.dns_port;
}
/**
* Port Tor is bound to for SOCKS5 traffic.
*
* @readonly
* @type {number}
*/
get socks_port() {
return this._ports.socks_port;
}
/**
* Port Tor is bound to for API access.
*
* @readonly
* @type {number}
*/
get control_port() {
return this._ports.control_port;
}
/**
* Instance of granax.TorController connected to the Tor process.
*
* @readonly
* @type {TorController}
*/
get controller() {
return this._controller;
}
/**
* Property identifiyng whether Tor has started.
*
* @readonly
* @type {boolean}
*/
get ready() { return this._ready; }
/* Passthrough to granax */
/**
* Requests a new identity via the control protocol.
*
* @async
*/
async new_identity() {
this.logger.info(`[tor-${this.instance_name}]: requested a new identity`);
await this.controller.cleanCircuitsAsync();
}
/**
* Retrieves a configuration value from the instance via the control protocol.
*
* @async
* @throws Will throw an error if not connected to the control protocol.
* @param {string} keyword - The name of the configuration property to retrieve.
*
* @returns {Promise< string[]>}
*/
async get_config(keyword) {
if (!this.controller)
throw new Error(`Controller is not connected`);
return await this.controller.getConfigAsync(keyword);
}
/**
* Sets a configuration value for the instance via the control protocol.
*
* @async
* @throws Will throw an error if not connected to the control protocol.
* @param {string} keyword - The name of the configuration property to retrieve.
* @param {any} value - Value to set the property to.
*
* @returns {Promise}
*/
async set_config(keyword, value) {
if (!this.controller) {
return new Error(`Controller is not connected`);
}
return await this.controller.setConfigAsync(keyword, value);
}
/**
* Sends a signal via the control tnterface.
*
* @async
* @throws Will throw an error if not connected to the control protocol.
* @param {string} signal - The signal to send.
*
* @returns {Promise}
*/
async signal(signal) {
if (!this.controller) {
throw new Error(`Controller is not connected`);
}
return await this.controller.signal(signal);
}
/**
* Creates the Tor process based on the configuration provided. Promise is resolved when the process has been started.
*
* @async
*
* @returns {Promise< ChildProcess>} - The process that has been created.
*/
async create() {
this._ports = {};
let dnsPort = this._ports.dns_port = await getPort();
let socksPort = this._ports.socks_port = await getPort();
let controlPort = this._ports.control_port = await getPort();
Object.freeze(this._ports);
let options = {
DNSPort: `127.0.0.1:${dnsPort}`,
SocksPort: `127.0.0.1:${socksPort}`,
ControlPort: `127.0.0.1:${controlPort}`,
HashedControlPassword: shell.exec(`${this.tor_path} --quiet --hash-password "${this.control_password}"`, { async: false, silent: true }).stdout.trim()
};
let config = _.extend(_.cloneDeep(this.tor_config), options);
let text = Object.keys(config).map((key) => `${key} ${config[key]}`).join(os.EOL);
let configFile = await temp.openAsync('tor-router');
let configPath = configFile.path;
await fs.writeFileAsync(configPath, text);
let tor = spawn(this.tor_path, ['-f', configPath], {
stdio: ['ignore', 'pipe', 'pipe'],
detached: false
});
tor.on('close', (async (code) => {
if (this.definition & & !this.definition.Name) {
await del(this.tor_config.DataDirectory, { force: true });
}
/**
* An event that fires when the process has closed.
*
* @event TorProcess#process_exit
* @type {number}
* @param {number} code - The exit code from the process.
*/
this.emit('process_exit', code);
}));
tor.stderr.on('data', (data) => {
let error_message = Buffer.from(data).toString('utf8');
this.emit('error', new Error(error_message));
});
this.once('ready', () => {
this._ready = true;
this.logger.info(`[tor-${this.instance_name}]: tor is ready`);
});
this.on('control_listen', (async () => {
try {
let socket = connect(this.control_port);
socket.on('error', ((error) => {
this.logger.error(`[tor-${this.instance_name}]: ${error.stack}`);
this.emit('error', error);
}));
this._controller = new TorController(socket, _.extend({ authOnConnect: false }, this.granax_options));
Promise.promisifyAll(this._controller);
this.controller.on('ready', () => {
this.logger.debug(`[tor-${this.instance_name}]: connected via the tor control protocol`);
this.controller.authenticate(`"${this.control_password}"`, (err) => {
if (err) {
this.logger.error(`[tor-${this.instance_name}]: ${err.stack}`);
this.emit('error', err);
} else {
this.logger.debug(`[tor-${this.instance_name}]: authenticated with tor instance via the control protocol`);
/**
* Is true when the connected via the control protcol
* @type {boolean}
*/
this.control_port_connected = true;
/**
* An event that fires when a connection has been established to the control protocol.
*
* @event TorProcess#controller_ready
*/
this.emit('controller_ready');
}
});
});
} catch (error) {
this.logger.error(`[tor-${this.instance_name}]: ${err.stack}`);
this.emit('error', err);
}
}));
tor.stdout.on('data', (data) => {
let text = Buffer.from(data).toString('utf8');
let msg = text.indexOf('] ') !== -1 ? text.split('] ').pop() : null;
if (text.indexOf('Bootstrapped 100%: Done') !== -1){
this.bootstrapped = true;
/**
* An event that fires when the Tor process is fully bootstrapped (and ready for traffic).
*
* @event TorProcess#ready
*/
this.emit('ready');
}
if (text.indexOf('Opening Control listener on') !== -1) {
this.control_port_listening = true;
/**
* An event that fires when the Tor process has started listening for control interface traffic.
*
* @event TorProcess#control_listen
*/
this.emit('control_listen');
}
if (text.indexOf('Opening Socks listener on') !== -1) {
this.socks_port_listening = true;
/**
* An event that fires when the Tor process has started listening for SOCKS5 traffic.
*
* @event TorProcess#socks_listen
*/
this.emit('socks_listen');
}
if (text.indexOf('Opening DNS listener on') !== -1) {
this.dns_port_listening = true;
/**
* An event that fires when the Tor process has started listening for DNS traffic.
*
* @event TorProcess#dns_listen
*/
this.emit('dns_listen');
}
if (text.indexOf('[err]') !== -1) {
/**
* An event that fires when the Tor process has written an error to stdout, stderr or when an error occurs connecting via the control protocol.
*
* @event TorProcess#error
* @type {Error}
* @returns {Error}
*/
this.emit('error', new Error(msg));
this.logger.error(`[tor-${this.instance_name}]: ${msg}`);
}
else if (text.indexOf('[notice]') !== -1) {
this.logger.debug(`[tor-${this.instance_name}]: ${msg}`);
}
else if (text.indexOf('[warn]') !== -1) {
this.logger.warn(`[tor-${this.instance_name}]: ${msg}`);
}
});
this.process = tor;
return tor;
}
};
/**
* Module that contains the {@link TorProcess} class.
* @module tor-router/TorProcess
* @see TorProcess
*/
module.exports = TorProcess;< / code > < / pre >
< / article >
< / section >
< / div >
< br class = "clear" >
< footer >
2018-09-25 16:53:29 +00:00
Documentation generated by < a href = "https://github.com/jsdoc3/jsdoc" > JSDoc 3.5.5< / a > on Tue Sep 25 2018 12:53:23 GMT-0400 (Eastern Daylight Time) using the < a href = "https://github.com/clenemt/docdash" > docdash< / a > theme.
2018-09-19 15:22:17 +00:00
< / footer >
< script > prettyPrint ( ) ; < / script >
< script src = "scripts/linenumber.js" > < / script >
< / body >
< / html >