beenull/tor-router
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity
tor-router/docs/TorProcess.js.html

495 lines
19 KiB
HTML
Raw Permalink Blame History

<!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><li data-type='method'><a href="TorPool.html#signal_by_name">signal_by_name</a></li></ul></li><li><a href="TorProcess.html">TorProcess</a><ul class='methods'><li data-type='method'><a href="TorProcess.html#create">create</a></li><li data-type='method'><a href="TorProcess.html#exit">exit</a></li><li data-type='method'><a href="TorProcess.html#get_config">get_config</a></li><li data-type='method'><a href="TorProcess.html#new_identity">new_identity</a></li><li data-type='method'><a href="TorProcess.html#set_config">set_config</a></li><li data-type='method'><a href="TorProcess.html#signal">signal</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-tor-router.html">tor-router</a></li><li><a href="module-tor-router_ControlServer.html">tor-router/ControlServer</a></li><li><a href="module-tor-router_default_config.html">tor-router/default_config</a></li><li><a href="module-tor-router_default_ports.html">tor-router/default_ports</a></li><li><a href="module-tor-router_DNSServer.html">tor-router/DNSServer</a></li><li><a href="module-tor-router_HTTPServer.html">tor-router/HTTPServer</a></li><li><a href="module-tor-router_launch.html">tor-router/launch</a></li><li><a href="module-tor-router_nconf_load_env.html">tor-router/nconf_load_env</a></li><li><a href="module-tor-router_SOCKSServer.html">tor-router/SOCKSServer</a></li><li><a href="module-tor-router_TorPool.html">tor-router/TorPool</a></li><li><a href="module-tor-router_TorProcess.html">tor-router/TorProcess</a></li><li><a href="module-tor-router_winston_silent_logger.html">tor-router/winston_silent_logger</a></li></ul><h3>Events</h3><ul><li><a href="DNSServer.html#event:instance-connection">instance-connection</a></li><li><a href="HTTPServer.html#event:instance-connection">instance-connection</a></li><li><a href="SOCKSServer.html#event:instance-connection">instance-connection</a></li><li><a href="TorPool.html#event:instance_created">instance_created</a></li><li><a href="TorProcess.html#event:control_listen">control_listen</a></li><li><a href="TorProcess.html#event:controller_ready">controller_ready</a></li><li><a href="TorProcess.html#event:dns_listen">dns_listen</a></li><li><a href="TorProcess.html#event:error">error</a></li><li><a href="TorProcess.html#event:process_exit">process_exit</a></li><li><a href="TorProcess.html#event:ready">ready</a></li><li><a href="TorProcess.html#event:socks_listen">socks_listen</a></li></ul><h3>Global</h3><ul><li><a href="global.html#assembleHost">assembleHost</a></li><li><a href="global.html#cleanUp">cleanUp</a></li><li><a href="global.html#env_whitelist">env_whitelist</a></li><li><a href="global.html#logger">logger</a></li><li><a href="global.html#main">main</a></li><li><a href="global.html#nconf">nconf</a></li><li><a href="global.html#REALM">REALM</a></li><li><a href="global.html#setup_nconf_env">setup_nconf_env</a></li><li><a href="global.html#TOR_ROUTER_PROXY_AGENT">TOR_ROUTER_PROXY_AGENT</a></li></ul>
</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');
const { TorController } = require('@deadcanaries/granax');
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 &amp;&amp; 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 &amp;&amp; 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&lt;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&lt;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 &amp;&amp; !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>
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.
</footer>
<script>prettyPrint();</script>
<script src="scripts/linenumber.js"></script>
</body>
</html>
Reference in a new issue View git blame Copy permalink