Vidalia  0.3.1
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. */
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 an unparsed router descriptor for the router whose fingerprint
172  * matches <b>id</b>. The returned text can later be parsed by the
173  * RouterDescriptor class. If <b>id</b> is invalid, then an empty
174  * QStringList is returned. */
175  QStringList getRouterDescriptorText(const QString &id, QString *errmsg = 0);
176  /** Returns the descriptor for the router whose fingerprint matches
177  * <b>id</b>. If <b>id</b> is invalid or the router's descriptor cannot be
178  * parsed, then an invalid RouterDescriptor is returned. */
179  RouterDescriptor getRouterDescriptor(const QString &id, QString *errmsg = 0);
180  /** Returns the status of the router whose fingerprint matches <b>id</b>. If
181  * <b>id</b> is invalid or the router's status cannot be parsed, then an
182  * invalid RouterStatus is returned. */
183  RouterStatus getRouterStatus(const QString &id, QString *errmsg = 0);
184  /** Returns a RouterStatus object for every known router in the network. If
185  * the network status document cannot be parsed, then an empty NetworkStatus
186  * is returned. */
187  NetworkStatus getNetworkStatus(QString *errmsg = 0);
188  /** Returns the annotations for the router whose fingerprint matches
189  * <b>id</b>. If <b>id</b> is invalid or the router's descriptor cannot be
190  * parsed, then an empty DescriptorAnnotations is returned and
191  * <b>errmsg</b> is set if it's not NULL. (Tor >= 0.2.0.13-alpha only) */
193  QString *errmsg = 0);
194 
195  /** Gets a list of current circuits. */
196  CircuitList getCircuits(QString *errmsg = 0);
197  /** Gets a list of current streams. */
198  StreamList getStreams(QString *errmsg = 0);
199 
200  /** Gets a list of address mappings of the type specified by <b>type</b>
201  * (defaults to <i>AddressMapAll</i>. */
204  QString *errmsg = 0);
205 
206  /** Gets the ISO-3166 two-letter country code for <b>ip</b> from Tor.
207  * Returns a default-constructed QString on failure or if a country code
208  * is not known for <b>ip</b>. On failure, <b>errmsg</b> will be set if
209  * it's not NULL. */
210  QString ipToCountry(const QHostAddress &ip, QString *errmsg = 0);
211 
212  /** Takes ownership of the tor process it's communicating to */
213  bool takeOwnership(QString *errmsg);
214 
215 public slots:
216  /** Closes the circuit specified by <b>circId</b>. If <b>ifUnused</b> is
217  * true, then the circuit will not be closed unless it is unused. */
218  bool closeCircuit(const CircuitId &circId, bool ifUnused = false,
219  QString *errmsg = 0);
220  /** Closes the stream specified by <b>streamId</b>. */
221  bool closeStream(const StreamId &streamId, QString *errmsg = 0);
222 
223 signals:
224  /** Emitted when the Tor process has started */
225  void started();
226  /** Emitted when the Tor process fails to start. */
227  void startFailed(QString errmsg);
228  /** Emitted when the Tor process has stopped */
229  void stopped(int exitCode, QProcess::ExitStatus exitStatus);
230  /** Emitted when the Tor process has stopped. */
231  void stopped();
232  /** Emitted when the controller has connected to Tor */
233  void connected();
234  /** Emitted when the controller failed to connect to Tor. */
235  void connectFailed(QString errmsg);
236  /** Emitted when the controller has disconnected from Tor */
237  void disconnected();
238  /** Emitted when the control socket is connected and authenticated. */
239  void authenticated();
240  /** Emitted when Tor rejects our authentication attempt. */
241  void authenticationFailed(QString errmsg);
242 
243  /** Emitted when Tor writes the message <b>msg</b> to the control port
244  * with message severity <b>level</b>.
245  */
246  void logMessage(tc::Severity level, const QString &msg);
247 
248  /** Emitted when Tor sends a bandwidth usage update (roughly once every
249  * second). <b>bytesReceived</b> is the number of bytes read by Tor over
250  * the previous second and <b>bytesWritten</b> is the number of bytes
251  * sent over the same interval.
252  */
253  void bandwidthUpdate(quint64 bytesReceived, quint64 bytesSent);
254 
255  /** Emitted when the stream status of <b>stream</b> has changed.
256  */
257  void streamStatusChanged(const Stream &stream);
258 
259  /** Emitted when the circuit status of <b>circuit</b> has changed.
260  */
261  void circuitStatusChanged(const Circuit &circuit);
262 
263  /** Emitted when Tor has mapped the address <b>from</b> to the address
264  * <b>to</b>. <b>expires</b> indicates the time at which when the address
265  * mapping will no longer be considered valid.
266  */
267  void addressMapped(const QString &from, const QString &to,
268  const QDateTime &expires);
269 
270  /** Emitted when Tor has received one or more new router descriptors.
271  * <b>ids</b> contains a list of digests of the new descriptors.
272  */
273  void newDescriptors(const QStringList &ids);
274 
275  /** Indicates Tor has been able to successfully establish one or more
276  * circuits.
277  */
278  void circuitEstablished();
279 
280  /** Indicates that Tor has decided the user's Tor software <b>version</b>
281  * is no longer recommended for some <b>reason</b>. <b>recommended</b> is
282  * a list of Tor software versions that are considered current.
283  */
285  const QString &version,
286  const QStringList &recommended);
287 
288  /** Emitted during Tor's startup process to indicate how far in its
289  * bootstrapping process it has progressed. <b>status</b> may indicate
290  * the current bootstrapping stage or an error during bootstrapping.
291  */
292  void bootstrapStatusChanged(const BootstrapStatus &status);
293 
294  /** Emitted when the user attempts to establish a connection to some
295  * destination on port <b>port</b>, which is a port known to use
296  * plaintext connections (as determined by Tor's WarnPlaintextPorts and
297  * RejectPlaintextPorts torrc options). <b>rejected</b> indicates whether
298  * Tor rejected the connection or permitted it to connect anyway.
299  */
300  void dangerousPort(quint16 port, bool rejected);
301 
302  /** Emitted when Tor detects a problem with a SOCKS connection from the
303  * user, such as a bad hostname, dangerous SOCKS protocol type, or a bad
304  * hostname. <b>type</b> indicates the type of error encountered and
305  * <b>destination</b> (if non-empty) specifies the attempted connection
306  * destination address or hostname.
307  */
308  void socksError(tc::SocksError type, const QString &destination);
309 
310  /** Emitted when Tor decides the client's external IP address has changed
311  * to <b>ip</b>. If <b>hostname</b> is non-empty, Tor obtained the new
312  * value for <b>ip</b> by resolving <b>hostname</b>.
313  */
314  void externalAddressChanged(const QHostAddress &ip, const QString &hostname);
315 
316  /** Indicates that Tor has determined the client's clock is potentially
317  * skewed by <b>skew</b> seconds relative to <b>source</b>.
318  */
319  void clockSkewed(int skew, const QString &source);
320 
321  /** Emitted when Tor has encountered an internal bug. <b>reason</b> is
322  * Tor's description of the bug.
323  */
324  void bug(const QString &reason);
325 
326  /** Emitted when Tor determines that the user's DNS provider is providing
327  * an address for non-existent domains when it should really be saying
328  * "NXDOMAIN".
329  */
330  void dnsHijacked();
331 
332  /** Emitted when Tor determines that the user's DNS provider is providing
333  * a hijacked address even for well-known websites.
334  */
335  void dnsUseless();
336 
337  /** Indicates Tor has started testing the reachability of its OR port
338  * using the IP address <b>ip</b> and port <b>port</b>.
339  */
340  void checkingOrPortReachability(const QHostAddress &ip, quint16 port);
341 
342  /** Tor has completed testing the reachability of its OR port using
343  * the IP address <b>ip</b> and port <b>port</b>. If the user's OR port
344  * was reachable, <b>reachable</b> will be set to true.
345  */
346  void orPortReachabilityFinished(const QHostAddress &ip, quint16 port,
347  bool reachable);
348 
349  /** Indicates Tor has started testing the reachability of its directory
350  * port using the IP address <b>ip</b> and port <b>port</b>.
351  */
352  void checkingDirPortReachability(const QHostAddress &ip, quint16 port);
353 
354  /** Tor has completed testing the reachability of its directory port using
355  * the IP address <b>ip</b> and port <b>port</b>. If the user's directory
356  * port was reachable, <b>reachable</b> will be set to true.
357  */
358  void dirPortReachabilityFinished(const QHostAddress &ip, quint16 port,
359  bool reachable);
360 
361  /** Emitted when the directory authority with IP address <b>ip</b> and
362  * port <b>port</b> rejected the user's server descriptor. <b>reason</b>
363  * describes why the descriptor was rejected (e.g., malformed, skewed
364  * clock, etc.).
365  */
366  void serverDescriptorRejected(const QHostAddress &ip, quint16 port,
367  const QString &reason);
368 
369  /** Emitted when the directory authority with IP address <b>ip</b> and
370  * port <b>port</b> accepted the user's server descriptor.
371  */
372  void serverDescriptorAccepted(const QHostAddress &ip, quint16 port);
373 
374  /** Emitted when at least one directory authority has accepted the user's
375  * server descriptor.
376  */
378 
379 private:
380  /** Instantiates a connection used to talk to Tor's control port */
382  /** Manages and monitors the Tor process */
384  /** Keep track of which events we're interested in */
386  TorEvents::Events _events;
387  /** The version of Tor we're currently talking to. */
388  QString _torVersion;
390 #if defined(Q_OS_WIN32)
391  /** Manages the Tor service, if supported and enabled */
392  TorService* _torService;
393 #endif
394 
395  /** Send a message to Tor and read the response */
396  bool send(ControlCommand cmd, ControlReply &reply, QString *errmsg = 0);
397  /** Send a message to Tor and discard the response */
398  bool send(ControlCommand cmd, QString *errmsg = 0);
399  /** Tells Tor the controller wants to enable <b>feature</b> via the
400  * USEFEATURE control command. Returns true if the given feature was
401  * successfully enabled. */
402  bool useFeature(const QString &feature, QString *errmsg = 0);
403 
404 /* The slots below simply relay signals from the appropriate member objects */
405 private slots:
406  void onStopped(int exitCode, QProcess::ExitStatus exitStatus);
407  void getBootstrapPhase();
408  void onDisconnected();
409  void onLogStdout(const QString &severity, const QString &message);
410  void onAuthenticated();
411 };
412 
413 #endif
414 
void authenticationFailed(QString errmsg)
void checkingDirPortReachability(const QHostAddress &ip, quint16 port)
SocksError
Definition: tcglobal.h:79
TorControl(ControlMethod::Method method=ControlMethod::Port)
Definition: TorControl.cpp:28
void onLogStdout(const QString &severity, const QString &message)
Definition: TorControl.cpp:187
bool signal(TorSignal::Signal sig, QString *errmsg=0)
Definition: TorControl.cpp:555
bool stop(QString *errmsg=0)
Definition: TorControl.cpp:131
bool getConf(QHash< QString, QString > &map, QString *errmsg=0)
Definition: TorControl.cpp:766
ControlMethod::Method _method
Definition: TorControl.h:389
QList< quint16 > getSocksPortList(QString *errmsg=0)
Definition: TorControl.cpp:620
void connected()
bool closeStream(const StreamId &streamId, QString *errmsg=0)
void closeTorStdout()
Definition: TorControl.cpp:179
stop errmsg QVariant
Definition: Stream.h:31
void orPortReachabilityFinished(const QHostAddress &ip, quint16 port, bool reachable)
void disconnect()
Definition: TorControl.cpp:210
void externalAddressChanged(const QHostAddress &ip, const QString &hostname)
void onDisconnected()
Definition: TorControl.cpp:245
StreamList getStreams(QString *errmsg=0)
NetworkStatus getNetworkStatus(QString *errmsg=0)
Definition: TorControl.cpp:981
quint32 getTorVersion()
Definition: TorControl.cpp:667
void dirPortReachabilityFinished(const QHostAddress &ip, quint16 port, bool reachable)
void onAuthenticated()
Definition: TorControl.cpp:333
void disconnected()
bool authenticate(const QByteArray cookie, QString *errmsg=0)
Definition: TorControl.cpp:298
void serverDescriptorAccepted()
QString ipToCountry(const QHostAddress &ip, QString *errmsg=0)
bool setConf(QHash< QString, QString > map, QString *errmsg=0)
Definition: TorControl.cpp:722
quint16 getSocksPort(QString *errmsg=0)
Definition: TorControl.cpp:608
bool setEvent(TorEvents::Event e, bool add=true, bool set=true, QString *errmsg=0)
Definition: TorControl.cpp:697
QHostAddress getSocksAddress(QString *errmsg=0)
Definition: TorControl.cpp:571
void stopped()
bool setEvents(QString *errmsg=0)
Definition: TorControl.cpp:707
bool getInfo(QHash< QString, QString > &map, QString *errmsg=0)
Definition: TorControl.cpp:450
QStringList getRouterDescriptorText(const QString &id, QString *errmsg=0)
Definition: TorControl.cpp:953
void bandwidthUpdate(quint64 bytesReceived, quint64 bytesSent)
void startFailed(QString errmsg)
AddressMap getAddressMap(AddressMap::AddressMapType type=AddressMap::AddressMapAll, QString *errmsg=0)
void dnsUseless()
QList< Stream > StreamList
Definition: Stream.h:97
bool send(ControlCommand cmd, ControlReply &reply, QString *errmsg=0)
Definition: TorControl.cpp:272
TorProcess * _torProcess
Definition: TorControl.h:383
bool closeCircuit(const CircuitId &circId, bool ifUnused=false, QString *errmsg=0)
void logMessage(tc::Severity level, const QString &msg)
DescriptorAnnotations getDescriptorAnnotations(const QString &id, QString *errmsg=0)
void dnsHijacked()
QString StreamId
Definition: Stream.h:28
TorEvents * _eventHandler
Definition: TorControl.h:385
bool isRunning()
Definition: TorControl.cpp:170
void connectFailed(QString errmsg)
RouterDescriptor getRouterDescriptor(const QString &id, QString *errmsg=0)
Definition: TorControl.cpp:962
RouterStatus getRouterStatus(const QString &id, QString *errmsg=0)
Definition: TorControl.cpp:971
void circuitEstablished()
void serverDescriptorRejected(const QHostAddress &ip, quint16 port, const QString &reason)
void dangerousTorVersion(tc::TorVersionStatus reason, const QString &version, const QStringList &recommended)
void started()
QStringList getSocksAddressList(QString *errmsg=0)
Definition: TorControl.cpp:596
void bug(const QString &reason)
void getBootstrapPhase()
Definition: TorControl.cpp:217
bool useFeature(const QString &feature, QString *errmsg=0)
Definition: TorControl.cpp:396
TorVersionStatus
Definition: tcglobal.h:86
void onStopped(int exitCode, QProcess::ExitStatus exitStatus)
Definition: TorControl.cpp:151
TorEvents::Events _events
Definition: TorControl.h:386
QString getTorVersionString()
Definition: TorControl.cpp:659
bool isCircuitEstablished()
Definition: TorControl.cpp:424
bool saveConf(QString *errmsg=0)
Definition: TorControl.cpp:914
ControlConnection * _controlConn
Definition: TorControl.h:381
QString getHiddenServiceConf(const QString &key, QString *errmsg=0)
Definition: TorControl.cpp:899
Severity
Definition: tcglobal.h:69
ProtocolInfo protocolInfo(QString *errmsg=0)
Definition: TorControl.cpp:350
void bootstrapStatusChanged(const BootstrapStatus &status)
QList< Circuit > CircuitList
Definition: Circuit.h:81
void checkingOrPortReachability(const QHostAddress &ip, quint16 port)
bool isConnected()
Definition: TorControl.cpp:262
void circuitStatusChanged(const Circuit &circuit)
bool takeOwnership(QString *errmsg)
bool isVidaliaRunningTor()
Definition: TorControl.cpp:163
CircuitList getCircuits(QString *errmsg=0)
bool resetConf(QStringList keys, QString *errmsg=0)
Definition: TorControl.cpp:929
QHash< QString, QString > DescriptorAnnotations
Definition: TorControl.h:42
void connect(const QHostAddress &address, quint16 port)
Definition: TorControl.cpp:195
QString CircuitId
Definition: Circuit.h:24
BootstrapStatus bootstrapStatus(QString *errmsg=0)
Definition: TorControl.cpp:403
void socksError(tc::SocksError type, const QString &destination)
QString _torVersion
Definition: TorControl.h:388
void streamStatusChanged(const Stream &stream)
void addressMapped(const QString &from, const QString &to, const QDateTime &expires)
QList< RouterStatus > NetworkStatus
Definition: RouterStatus.h:97
void dangerousPort(quint16 port, bool rejected)
void newDescriptors(const QStringList &ids)
void clockSkewed(int skew, const QString &source)
void start(const QString &tor, const QStringList &args)
Definition: TorControl.cpp:110
void authenticated()