Vidalia  0.2.21
TorControl.h
Go to the documentation of this file.
1 /*
2 ** This file is part of Vidalia, and is subject to the license terms in the
3 ** LICENSE file, found in the top level directory of this distribution. If
4 ** you did not receive the LICENSE file with this file, you may obtain it
5 ** from the Vidalia source package distributed by the Vidalia Project at
6 ** http://www.torproject.org/projects/vidalia.html. No part of Vidalia,
7 ** including this file, may be copied, modified, propagated, or distributed
8 ** except according to the terms described in the LICENSE file.
9 */
10 
11 /*
12 ** \file TorControl.h
13 ** \brief Object for interacting with the Tor process and control interface
14 */
15 
16 #ifndef _TORCONTROL_H
17 #define _TORCONTROL_H
18 
19 #include "tcglobal.h"
20 #include "ControlConnection.h"
21 #include "TorProcess.h"
22 #include "TorEvents.h"
23 #include "TorSignal.h"
24 #include "RouterDescriptor.h"
25 #include "RouterStatus.h"
26 #include "BootstrapStatus.h"
27 #include "Circuit.h"
28 #include "Stream.h"
29 #include "AddressMap.h"
30 #include "ControlMethod.h"
31 
32 #if defined(Q_OS_WIN32)
33 #include "TorService.h"
34 #endif
35 
36 #include <QObject>
37 #include <QHash>
38 #include <QList>
39 #include <QStringList>
40 #include <QVariantMap>
41 
43 
44 /** DescriptorAnnotations stores a map of annotation keys to (possibly empty)
45  * annotation values. */
46 typedef QHash<QString,QString> DescriptorAnnotations;
47 
48 
49 class TorControl : public QObject
50 {
51  Q_OBJECT
52 
53 public:
54  /** Default constructor */
56  /** Default destructor */
57  ~TorControl();
58 
59  /** Start the Tor process */
60  void start(const QString &tor, const QStringList &args);
61  /** Stop the Tor process */
62  bool stop(QString *errmsg = 0);
63  /** Detect if the Tor process is running */
64  bool isRunning();
65  /** Detects if the Tor process is running under Vidalia. */
66  bool isVidaliaRunningTor();
67  /** Stops reading log messages from the Tor process's stdout. This has no
68  * effect if isVidaliaRunningTor() is false. */
69  void closeTorStdout();
70 
71  /** Connect to Tor's control socket */
72  void connect(const QHostAddress &address, quint16 port);
73  void connect(const QString &path);
74  /** Disconnect from Tor's control socket */
75  void disconnect();
76  /** Check if we're connected to Tor's control socket */
77  bool isConnected();
78  /** Sends an authentication cookie to Tor. */
79  bool authenticate(const QByteArray cookie, QString *errmsg = 0);
80  /** Sends an authentication password to Tor. */
81  bool authenticate(const QString &password = QString(), QString *errmsg = 0);
82 
83  /** Sends a PROTOCOLINFO command to Tor and parses the response. */
84  ProtocolInfo protocolInfo(QString *errmsg = 0);
85 
86  /** Returns the Tor software's current bootstrap phase and status. */
87  BootstrapStatus bootstrapStatus(QString *errmsg = 0);
88 
89  /** Returns true if Tor either has an open circuit or (on Tor >=
90  * 0.2.0.1-alpha) has previously decided it's able to establish a circuit. */
91  bool isCircuitEstablished();
92 
93  /** Sends a GETINFO message to Tor based on the given keys */
94  bool getInfo(QHash<QString,QString> &map, QString *errmsg = 0);
95  /** Sends a GETINFO message for a single info value to Tor */
96  bool getInfo(QString key, QString &val, QString *errmsg = 0);
97 
98  /** Sends a GETINFO message to Tor using the given list of <b>keys</b> and
99  * returns a QVariantMap containing the specified keys and their values as
100  * returned by Tor. Returns a default constructed QVariantMap on failure. */
101  QVariantMap getInfo(const QStringList &keys, QString *errmsg = 0);
102  /** Sends a GETINFO message to Tor with a single <b>key</b> and returns a
103  * QVariant containing the value returned by Tor. Returns a default
104  * constructed QVariant on failure. */
105  QVariant getInfo(const QString &key, QString *errmsg = 0);
106 
107  /** Sends a signal to Tor */
108  bool signal(TorSignal::Signal sig, QString *errmsg = 0);
109 
110  /** Returns an address on which Tor is listening for application
111  * requests. If none are available, a null QHostAddress is returned. */
112  QHostAddress getSocksAddress(QString *errmsg = 0);
113  /** Returns a (possibly empty) list of all currently configured
114  * SocksListenAddress entries. */
115  QStringList getSocksAddressList(QString *errmsg = 0);
116  /** Returns a valid SOCKS port for Tor, or 0 if Tor is not accepting
117  * application requests. */
118  quint16 getSocksPort(QString *errmsg = 0);
119  /** Returns a list of all currently configured SOCKS ports. If Tor is not
120  * accepting any application connections, an empty list will be returned. */
121  QList<quint16> getSocksPortList(QString *errmsg = 0);
122 
123  /** Returns Tor's version as a string. */
124  QString getTorVersionString();
125  /** Returns Tor's version as a numeric value. */
126  quint32 getTorVersion();
127 
128  /** Sets an event and its handler. If add is true, then the event is added,
129  * otherwise it is removed. If set is true, then the given event will be
130  * registered with Tor. */
131  bool setEvent(TorEvents::Event e, bool add = true, bool set = true,
132  QString *errmsg = 0);
133  /** Register events of interest with Tor */
134  bool setEvents(QString *errmsg = 0);
135 
136  /** Sets each configuration key in <b>map</b> to the value associated with its key. */
137  bool setConf(QHash<QString,QString> map, QString *errmsg = 0);
138  /** Sets a single configuration key to the given value. */
139  bool setConf(QString key, QString value, QString *errmsg = 0);
140  /** Sets a single configuration string that is formatted <key=escaped value>. */
141  bool setConf(QString keyAndValue, QString *errmsg = 0);
142  /** Gets values for a set of configuration keys, each of which has a single
143  * value. */
144  bool getConf(QHash<QString,QString> &map, QString *errmsg = 0);
145  /** Gets a set of configuration keyvalues and stores them in <b>map</b>. */
146  bool getConf(QHash<QString,QStringList> &map, QString *errmsg = 0);
147  /** Gets a single configuration value for <b>key</b>. */
148  bool getConf(QString key, QString &value, QString *errmsg = 0);
149  /** Gets a list of configuration values for <b>key</b>. */
150  bool getConf(QString key, QStringList &value, QString *errmsg = 0);
151 
152  /** Sends a GETCONF message to Tor using the given list of <b>keys</b> and
153  * returns a QVariantMap containing the specified keys and their values as
154  * returned by Tor. Returns a default constructed QVariantMap on failure. */
155  QVariantMap getConf(const QStringList &keys, QString *errmsg = 0);
156  /** Sends a GETCONF message to Tor with a single <b>key</b> and returns a
157  * QVariant containing the value returned by Tor. Returns a default
158  * constructed QVariant on failure. */
159  QVariant getConf(const QString &key, QString *errmsg = 0);
160  /** Sends a GETCONF message to Tor with the single key and returns a QString
161  * containing the value returned by Tor */
162  QString getHiddenServiceConf(const QString &key, QString *errmsg = 0);
163 
164  /** Asks Tor to save the current configuration to its torrc */
165  bool saveConf(QString *errmsg = 0);
166  /** Tells Tor to reset the given configuration keys back to defaults. */
167  bool resetConf(QStringList keys, QString *errmsg = 0);
168  /** Tells Tor to reset a configuration key back to its default value. */
169  bool resetConf(QString key, QString *errmsg = 0);
170 
171  /** Returns true if UseMicrodescriptors is enabled */
172  bool useMicrodescriptors(QString *errmsg = 0);
173  /** Returns an unparsed router descriptor for the router whose fingerprint
174  * matches <b>id</b>. The returned text can later be parsed by the
175  * RouterDescriptor class. If <b>id</b> is invalid, then an empty
176  * QStringList is returned. */
177  QStringList getRouterDescriptorText(const QString &id, QString *errmsg = 0);
178  /** Returns the descriptor for the router whose fingerprint matches
179  * <b>id</b>. If <b>id</b> is invalid or the router's descriptor cannot be
180  * parsed, then an invalid RouterDescriptor is returned. */
181  RouterDescriptor getRouterDescriptor(const QString &id, QString *errmsg = 0);
182  /** Returns the status of the router whose fingerprint matches <b>id</b>. If
183  * <b>id</b> is invalid or the router's status cannot be parsed, then an
184  * invalid RouterStatus is returned. */
185  RouterStatus getRouterStatus(const QString &id, QString *errmsg = 0);
186  /** Returns a RouterStatus object for every known router in the network. If
187  * the network status document cannot be parsed, then an empty NetworkStatus
188  * is returned. */
189  NetworkStatus getNetworkStatus(QString *errmsg = 0);
190  /** Returns the annotations for the router whose fingerprint matches
191  * <b>id</b>. If <b>id</b> is invalid or the router's descriptor cannot be
192  * parsed, then an empty DescriptorAnnotations is returned and
193  * <b>errmsg</b> is set if it's not NULL. (Tor >= 0.2.0.13-alpha only) */
195  QString *errmsg = 0);
196 
197  /** Gets a list of current circuits. */
198  CircuitList getCircuits(QString *errmsg = 0);
199  /** Gets a list of current streams. */
200  StreamList getStreams(QString *errmsg = 0);
201 
202  /** Gets a list of address mappings of the type specified by <b>type</b>
203  * (defaults to <i>AddressMapAll</i>. */
206  QString *errmsg = 0);
207 
208  /** Gets the ISO-3166 two-letter country code for <b>ip</b> from Tor.
209  * Returns a default-constructed QString on failure or if a country code
210  * is not known for <b>ip</b>. On failure, <b>errmsg</b> will be set if
211  * it's not NULL. */
212  QString ipToCountry(const QHostAddress &ip, QString *errmsg = 0);
213 
214  /** Takes ownership of the tor process it's communicating to */
215  bool takeOwnership(QString *errmsg);
216 
217 public slots:
218  /** Closes the circuit specified by <b>circId</b>. If <b>ifUnused</b> is
219  * true, then the circuit will not be closed unless it is unused. */
220  bool closeCircuit(const CircuitId &circId, bool ifUnused = false,
221  QString *errmsg = 0);
222  /** Closes the stream specified by <b>streamId</b>. */
223  bool closeStream(const StreamId &streamId, QString *errmsg = 0);
224 
225 signals:
226  /** Emitted when the Tor process has started */
227  void started();
228  /** Emitted when the Tor process fails to start. */
229  void startFailed(QString errmsg);
230  /** Emitted when the Tor process has stopped */
231  void stopped(int exitCode, QProcess::ExitStatus exitStatus);
232  /** Emitted when the Tor process has stopped. */
233  void stopped();
234  /** Emitted when the controller has connected to Tor */
235  void connected();
236  /** Emitted when the controller failed to connect to Tor. */
237  void connectFailed(QString errmsg);
238  /** Emitted when the controller has disconnected from Tor */
239  void disconnected();
240  /** Emitted when the control socket is connected and authenticated. */
241  void authenticated();
242  /** Emitted when Tor rejects our authentication attempt. */
243  void authenticationFailed(QString errmsg);
244 
245  /** Emitted when Tor writes the message <b>msg</b> to the control port
246  * with message severity <b>level</b>.
247  */
248  void logMessage(tc::Severity level, const QString &msg);
249 
250  /** Emitted when Tor sends a bandwidth usage update (roughly once every
251  * second). <b>bytesReceived</b> is the number of bytes read by Tor over
252  * the previous second and <b>bytesWritten</b> is the number of bytes
253  * sent over the same interval.
254  */
255  void bandwidthUpdate(quint64 bytesReceived, quint64 bytesSent);
256 
257  /** Emitted when the stream status of <b>stream</b> has changed.
258  */
259  void streamStatusChanged(const Stream &stream);
260 
261  /** Emitted when the circuit status of <b>circuit</b> has changed.
262  */
263  void circuitStatusChanged(const Circuit &circuit);
264 
265  /** Emitted when Tor has mapped the address <b>from</b> to the address
266  * <b>to</b>. <b>expires</b> indicates the time at which when the address
267  * mapping will no longer be considered valid.
268  */
269  void addressMapped(const QString &from, const QString &to,
270  const QDateTime &expires);
271 
272  /** Emitted when Tor has received one or more new router descriptors.
273  * <b>ids</b> contains a list of digests of the new descriptors.
274  */
275  void newDescriptors(const QStringList &ids);
276 
277  /** Indicates Tor has been able to successfully establish one or more
278  * circuits.
279  */
280  void circuitEstablished();
281 
282  /** Indicates that Tor has decided the user's Tor software <b>version</b>
283  * is no longer recommended for some <b>reason</b>. <b>recommended</b> is
284  * a list of Tor software versions that are considered current.
285  */
287  const QString &version,
288  const QStringList &recommended);
289 
290  /** Emitted during Tor's startup process to indicate how far in its
291  * bootstrapping process it has progressed. <b>status</b> may indicate
292  * the current bootstrapping stage or an error during bootstrapping.
293  */
294  void bootstrapStatusChanged(const BootstrapStatus &status);
295 
296  /** Emitted when the user attempts to establish a connection to some
297  * destination on port <b>port</b>, which is a port known to use
298  * plaintext connections (as determined by Tor's WarnPlaintextPorts and
299  * RejectPlaintextPorts torrc options). <b>rejected</b> indicates whether
300  * Tor rejected the connection or permitted it to connect anyway.
301  */
302  void dangerousPort(quint16 port, bool rejected);
303 
304  /** Emitted when Tor detects a problem with a SOCKS connection from the
305  * user, such as a bad hostname, dangerous SOCKS protocol type, or a bad
306  * hostname. <b>type</b> indicates the type of error encountered and
307  * <b>destination</b> (if non-empty) specifies the attempted connection
308  * destination address or hostname.
309  */
310  void socksError(tc::SocksError type, const QString &destination);
311 
312  /** Emitted when Tor decides the client's external IP address has changed
313  * to <b>ip</b>. If <b>hostname</b> is non-empty, Tor obtained the new
314  * value for <b>ip</b> by resolving <b>hostname</b>.
315  */
316  void externalAddressChanged(const QHostAddress &ip, const QString &hostname);
317 
318  /** Indicates that Tor has determined the client's clock is potentially
319  * skewed by <b>skew</b> seconds relative to <b>source</b>.
320  */
321  void clockSkewed(int skew, const QString &source);
322 
323  /** Emitted when Tor has encountered an internal bug. <b>reason</b> is
324  * Tor's description of the bug.
325  */
326  void bug(const QString &reason);
327 
328  /** Emitted when Tor determines that the user's DNS provider is providing
329  * an address for non-existent domains when it should really be saying
330  * "NXDOMAIN".
331  */
332  void dnsHijacked();
333 
334  /** Emitted when Tor determines that the user's DNS provider is providing
335  * a hijacked address even for well-known websites.
336  */
337  void dnsUseless();
338 
339  /** Indicates Tor has started testing the reachability of its OR port
340  * using the IP address <b>ip</b> and port <b>port</b>.
341  */
342  void checkingOrPortReachability(const QHostAddress &ip, quint16 port);
343 
344  /** Tor has completed testing the reachability of its OR port using
345  * the IP address <b>ip</b> and port <b>port</b>. If the user's OR port
346  * was reachable, <b>reachable</b> will be set to true.
347  */
348  void orPortReachabilityFinished(const QHostAddress &ip, quint16 port,
349  bool reachable);
350 
351  /** Indicates Tor has started testing the reachability of its directory
352  * port using the IP address <b>ip</b> and port <b>port</b>.
353  */
354  void checkingDirPortReachability(const QHostAddress &ip, quint16 port);
355 
356  /** Tor has completed testing the reachability of its directory port using
357  * the IP address <b>ip</b> and port <b>port</b>. If the user's directory
358  * port was reachable, <b>reachable</b> will be set to true.
359  */
360  void dirPortReachabilityFinished(const QHostAddress &ip, quint16 port,
361  bool reachable);
362 
363  /** Emitted when the directory authority with IP address <b>ip</b> and
364  * port <b>port</b> rejected the user's server descriptor. <b>reason</b>
365  * describes why the descriptor was rejected (e.g., malformed, skewed
366  * clock, etc.).
367  */
368  void serverDescriptorRejected(const QHostAddress &ip, quint16 port,
369  const QString &reason);
370 
371  /** Emitted when the directory authority with IP address <b>ip</b> and
372  * port <b>port</b> accepted the user's server descriptor.
373  */
374  void serverDescriptorAccepted(const QHostAddress &ip, quint16 port);
375 
376  /** Emitted when at least one directory authority has accepted the user's
377  * server descriptor.
378  */
380 
381 private:
382  /** Instantiates a connection used to talk to Tor's control port */
384  /** Manages and monitors the Tor process */
386  /** Keep track of which events we're interested in */
388  TorEvents::Events _events;
389  /** The version of Tor we're currently talking to. */
390  QString _torVersion;
392 #if defined(Q_OS_WIN32)
393  /** Manages the Tor service, if supported and enabled */
394  TorService* _torService;
395 #endif
396 
397  /** Send a message to Tor and read the response */
398  bool send(ControlCommand cmd, ControlReply &reply, QString *errmsg = 0);
399  /** Send a message to Tor and discard the response */
400  bool send(ControlCommand cmd, QString *errmsg = 0);
401  /** Tells Tor the controller wants to enable <b>feature</b> via the
402  * USEFEATURE control command. Returns true if the given feature was
403  * successfully enabled. */
404  bool useFeature(const QString &feature, QString *errmsg = 0);
405 
406 /* The slots below simply relay signals from the appropriate member objects */
407 private slots:
408  void onStopped(int exitCode, QProcess::ExitStatus exitStatus);
409  void getBootstrapPhase();
410  void onDisconnected();
411  void onLogStdout(const QString &severity, const QString &message);
412  void onAuthenticated();
413 };
414 
415 #endif
416