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
42class ProtocolInfo;
43
44/** DescriptorAnnotations stores a map of annotation keys to (possibly empty)
45 * annotation values. */
46typedef QHash<QString,QString> DescriptorAnnotations;
47
48
49class TorControl : public QObject
50{
51 Q_OBJECT
52
53public:
54 /** Default constructor */
56 /** Default destructor */
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. */
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. */
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
215public 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
223signals:
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 */
238 /** Emitted when the control socket is connected and 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 */
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 */
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 */
331
332 /** Emitted when Tor determines that the user's DNS provider is providing
333 * a hijacked address even for well-known websites.
334 */
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
379private:
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 */
405private 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
QList< Circuit > CircuitList
Definition: Circuit.h:81
QString CircuitId
Definition: Circuit.h:24
QList< RouterStatus > NetworkStatus
Definition: RouterStatus.h:97
QString StreamId
Definition: Stream.h:28
QList< Stream > StreamList
Definition: Stream.h:97
QHash< QString, QString > DescriptorAnnotations
Definition: TorControl.h:42
stop errmsg QVariant
@ AddressMapAll
Definition: AddressMap.h:33
Definition: Stream.h:32
void dnsUseless()
bool saveConf(QString *errmsg=0)
Definition: TorControl.cpp:914
void externalAddressChanged(const QHostAddress &ip, const QString &hostname)
void onAuthenticated()
Definition: TorControl.cpp:333
void getBootstrapPhase()
Definition: TorControl.cpp:217
BootstrapStatus bootstrapStatus(QString *errmsg=0)
Definition: TorControl.cpp:403
RouterStatus getRouterStatus(const QString &id, QString *errmsg=0)
Definition: TorControl.cpp:971
void circuitEstablished()
bool authenticate(const QByteArray cookie, QString *errmsg=0)
Definition: TorControl.cpp:298
void checkingDirPortReachability(const QHostAddress &ip, quint16 port)
bool isCircuitEstablished()
Definition: TorControl.cpp:424
bool takeOwnership(QString *errmsg)
bool send(ControlCommand cmd, ControlReply &reply, QString *errmsg=0)
Definition: TorControl.cpp:272
QHostAddress getSocksAddress(QString *errmsg=0)
Definition: TorControl.cpp:571
bool setEvents(QString *errmsg=0)
Definition: TorControl.cpp:707
void newDescriptors(const QStringList &ids)
bool signal(TorSignal::Signal sig, QString *errmsg=0)
Definition: TorControl.cpp:555
void stopped()
void connected()
bool isVidaliaRunningTor()
Definition: TorControl.cpp:163
AddressMap getAddressMap(AddressMap::AddressMapType type=AddressMap::AddressMapAll, QString *errmsg=0)
NetworkStatus getNetworkStatus(QString *errmsg=0)
Definition: TorControl.cpp:981
void addressMapped(const QString &from, const QString &to, const QDateTime &expires)
void start(const QString &tor, const QStringList &args)
Definition: TorControl.cpp:110
QStringList getRouterDescriptorText(const QString &id, QString *errmsg=0)
Definition: TorControl.cpp:953
void authenticated()
void connect(const QHostAddress &address, quint16 port)
Definition: TorControl.cpp:195
void dangerousTorVersion(tc::TorVersionStatus reason, const QString &version, const QStringList &recommended)
void connectFailed(QString errmsg)
bool isConnected()
Definition: TorControl.cpp:262
void circuitStatusChanged(const Circuit &circuit)
void disconnect()
Definition: TorControl.cpp:210
TorProcess * _torProcess
Definition: TorControl.h:383
ControlMethod::Method _method
Definition: TorControl.h:389
QString getHiddenServiceConf(const QString &key, QString *errmsg=0)
Definition: TorControl.cpp:899
void startFailed(QString errmsg)
bool closeCircuit(const CircuitId &circId, bool ifUnused=false, QString *errmsg=0)
void socksError(tc::SocksError type, const QString &destination)
bool getInfo(QHash< QString, QString > &map, QString *errmsg=0)
Definition: TorControl.cpp:450
void checkingOrPortReachability(const QHostAddress &ip, quint16 port)
void bandwidthUpdate(quint64 bytesReceived, quint64 bytesSent)
void authenticationFailed(QString errmsg)
TorControl(ControlMethod::Method method=ControlMethod::Port)
Definition: TorControl.cpp:28
QList< quint16 > getSocksPortList(QString *errmsg=0)
Definition: TorControl.cpp:620
void onStopped(int exitCode, QProcess::ExitStatus exitStatus)
Definition: TorControl.cpp:151
DescriptorAnnotations getDescriptorAnnotations(const QString &id, QString *errmsg=0)
void logMessage(tc::Severity level, const QString &msg)
void stopped(int exitCode, QProcess::ExitStatus exitStatus)
void dangerousPort(quint16 port, bool rejected)
QString _torVersion
Definition: TorControl.h:388
void bootstrapStatusChanged(const BootstrapStatus &status)
void bug(const QString &reason)
void streamStatusChanged(const Stream &stream)
bool closeStream(const StreamId &streamId, QString *errmsg=0)
CircuitList getCircuits(QString *errmsg=0)
bool setEvent(TorEvents::Event e, bool add=true, bool set=true, QString *errmsg=0)
Definition: TorControl.cpp:697
void started()
void serverDescriptorAccepted()
bool resetConf(QStringList keys, QString *errmsg=0)
Definition: TorControl.cpp:929
bool isRunning()
Definition: TorControl.cpp:170
void dnsHijacked()
void disconnected()
bool useFeature(const QString &feature, QString *errmsg=0)
Definition: TorControl.cpp:396
quint16 getSocksPort(QString *errmsg=0)
Definition: TorControl.cpp:608
ControlConnection * _controlConn
Definition: TorControl.h:381
bool setConf(QHash< QString, QString > map, QString *errmsg=0)
Definition: TorControl.cpp:722
quint32 getTorVersion()
Definition: TorControl.cpp:667
bool getConf(QHash< QString, QString > &map, QString *errmsg=0)
Definition: TorControl.cpp:766
void clockSkewed(int skew, const QString &source)
RouterDescriptor getRouterDescriptor(const QString &id, QString *errmsg=0)
Definition: TorControl.cpp:962
void onDisconnected()
Definition: TorControl.cpp:245
void orPortReachabilityFinished(const QHostAddress &ip, quint16 port, bool reachable)
StreamList getStreams(QString *errmsg=0)
void onLogStdout(const QString &severity, const QString &message)
Definition: TorControl.cpp:187
bool stop(QString *errmsg=0)
Definition: TorControl.cpp:131
QString ipToCountry(const QHostAddress &ip, QString *errmsg=0)
TorEvents * _eventHandler
Definition: TorControl.h:385
ProtocolInfo protocolInfo(QString *errmsg=0)
Definition: TorControl.cpp:350
void serverDescriptorRejected(const QHostAddress &ip, quint16 port, const QString &reason)
QString getTorVersionString()
Definition: TorControl.cpp:659
TorEvents::Events _events
Definition: TorControl.h:386
void dirPortReachabilityFinished(const QHostAddress &ip, quint16 port, bool reachable)
QStringList getSocksAddressList(QString *errmsg=0)
Definition: TorControl.cpp:596
void serverDescriptorAccepted(const QHostAddress &ip, quint16 port)
void closeTorStdout()
Definition: TorControl.cpp:179
TorVersionStatus
Definition: tcglobal.h:86
SocksError
Definition: tcglobal.h:79
Severity
Definition: tcglobal.h:69