00001 /* 00002 ** This file is part of Vidalia, and is subject to the license terms in the 00003 ** LICENSE file, found in the top level directory of this distribution. If 00004 ** you did not receive the LICENSE file with this file, you may obtain it 00005 ** from the Vidalia source package distributed by the Vidalia Project at 00006 ** http://www.vidalia-project.net/. No part of Vidalia, including this file, 00007 ** may be copied, modified, propagated, or distributed except according to 00008 ** the terms described in the LICENSE file. 00009 */ 00010 00011 /* 00012 ** \file TorControl.h 00013 ** \version $Id: TorControl.h 4060 2009-08-20 03:41:13Z edmanm $ 00014 ** \brief Object for interacting with the Tor process and control interface 00015 */ 00016 00017 #ifndef _TORCONTROL_H 00018 #define _TORCONTROL_H 00019 00020 #include "tcglobal.h" 00021 #include "ControlConnection.h" 00022 #include "TorProcess.h" 00023 #include "TorEvents.h" 00024 #include "TorSignal.h" 00025 #include "RouterDescriptor.h" 00026 #include "RouterStatus.h" 00027 #include "BootstrapStatus.h" 00028 #include "Circuit.h" 00029 #include "Stream.h" 00030 #include "AddressMap.h" 00031 00032 #if defined(Q_OS_WIN32) 00033 #include "TorService.h" 00034 #endif 00035 00036 #include <QObject> 00037 #include <QHash> 00038 #include <QList> 00039 #include <QStringList> 00040 #include <QVariantMap> 00041 00042 class ProtocolInfo; 00043 00044 /** DescriptorAnnotations stores a map of annotation keys to (possibly empty) 00045 * annotation values. */ 00046 typedef QHash<QString,QString> DescriptorAnnotations; 00047 00048 00049 class TorControl : public QObject 00050 { 00051 Q_OBJECT 00052 00053 public: 00054 /** Default constructor */ 00055 TorControl(); 00056 /** Default destructor */ 00057 ~TorControl(); 00058 00059 /** Start the Tor process */ 00060 void start(const QString &tor, const QStringList &args); 00061 /** Stop the Tor process */ 00062 bool stop(QString *errmsg = 0); 00063 /** Detect if the Tor process is running */ 00064 bool isRunning(); 00065 /** Detects if the Tor process is running under Vidalia. */ 00066 bool isVidaliaRunningTor(); 00067 /** Stops reading log messages from the Tor process's stdout. This has no 00068 * effect if isVidaliaRunningTor() is false. */ 00069 void closeTorStdout(); 00070 00071 /** Connect to Tor's control socket */ 00072 void connect(const QHostAddress &address, quint16 port); 00073 /** Disconnect from Tor's control socket */ 00074 void disconnect(); 00075 /** Check if we're connected to Tor's control socket */ 00076 bool isConnected(); 00077 /** Sends an authentication cookie to Tor. */ 00078 bool authenticate(const QByteArray cookie, QString *errmsg = 0); 00079 /** Sends an authentication password to Tor. */ 00080 bool authenticate(const QString &password = QString(), QString *errmsg = 0); 00081 00082 /** Sends a PROTOCOLINFO command to Tor and parses the response. */ 00083 ProtocolInfo protocolInfo(QString *errmsg = 0); 00084 00085 /** Returns the Tor software's current bootstrap phase and status. */ 00086 BootstrapStatus bootstrapStatus(QString *errmsg = 0); 00087 00088 /** Returns true if Tor either has an open circuit or (on Tor >= 00089 * 0.2.0.1-alpha) has previously decided it's able to establish a circuit. */ 00090 bool isCircuitEstablished(); 00091 00092 /** Sends a GETINFO message to Tor based on the given keys */ 00093 bool getInfo(QHash<QString,QString> &map, QString *errmsg = 0); 00094 /** Sends a GETINFO message for a single info value to Tor */ 00095 bool getInfo(QString key, QString &val, QString *errmsg = 0); 00096 00097 /** Sends a GETINFO message to Tor using the given list of <b>keys</b> and 00098 * returns a QVariantMap containing the specified keys and their values as 00099 * returned by Tor. Returns a default constructed QVariantMap on failure. */ 00100 QVariantMap getInfo(const QStringList &keys, QString *errmsg = 0); 00101 /** Sends a GETINFO message to Tor with a single <b>key</b> and returns a 00102 * QVariant containing the value returned by Tor. Returns a default 00103 * constructed QVariant on failure. */ 00104 QVariant getInfo(const QString &key, QString *errmsg = 0); 00105 00106 /** Sends a signal to Tor */ 00107 bool signal(TorSignal::Signal sig, QString *errmsg = 0); 00108 00109 /** Returns an address on which Tor is listening for application 00110 * requests. If none are available, a null QHostAddress is returned. */ 00111 QHostAddress getSocksAddress(QString *errmsg = 0); 00112 /** Returns a (possibly empty) list of all currently configured 00113 * SocksListenAddress entries. */ 00114 QStringList getSocksAddressList(QString *errmsg = 0); 00115 /** Returns a valid SOCKS port for Tor, or 0 if Tor is not accepting 00116 * application requests. */ 00117 quint16 getSocksPort(QString *errmsg = 0); 00118 /** Returns a list of all currently configured SOCKS ports. If Tor is not 00119 * accepting any application connections, an empty list will be returned. */ 00120 QList<quint16> getSocksPortList(QString *errmsg = 0); 00121 00122 /** Returns Tor's version as a string. */ 00123 QString getTorVersionString(); 00124 /** Returns Tor's version as a numeric value. */ 00125 quint32 getTorVersion(); 00126 00127 /** Sets an event and its handler. If add is true, then the event is added, 00128 * otherwise it is removed. If set is true, then the given event will be 00129 * registered with Tor. */ 00130 bool setEvent(TorEvents::Event e, bool add = true, bool set = true, 00131 QString *errmsg = 0); 00132 /** Register events of interest with Tor */ 00133 bool setEvents(QString *errmsg = 0); 00134 00135 /** Sets each configuration key in <b>map</b> to the value associated with its key. */ 00136 bool setConf(QHash<QString,QString> map, QString *errmsg = 0); 00137 /** Sets a single configuration key to the given value. */ 00138 bool setConf(QString key, QString value, QString *errmsg = 0); 00139 /** Sets a single configuration string that is formatted <key=escaped value>. */ 00140 bool setConf(QString keyAndValue, QString *errmsg = 0); 00141 /** Gets values for a set of configuration keys, each of which has a single 00142 * value. */ 00143 bool getConf(QHash<QString,QString> &map, QString *errmsg = 0); 00144 /** Gets a set of configuration keyvalues and stores them in <b>map</b>. */ 00145 bool getConf(QHash<QString,QStringList> &map, QString *errmsg = 0); 00146 /** Gets a single configuration value for <b>key</b>. */ 00147 bool getConf(QString key, QString &value, QString *errmsg = 0); 00148 /** Gets a list of configuration values for <b>key</b>. */ 00149 bool getConf(QString key, QStringList &value, QString *errmsg = 0); 00150 00151 /** Sends a GETCONF message to Tor using the given list of <b>keys</b> and 00152 * returns a QVariantMap containing the specified keys and their values as 00153 * returned by Tor. Returns a default constructed QVariantMap on failure. */ 00154 QVariantMap getConf(const QStringList &keys, QString *errmsg = 0); 00155 /** Sends a GETCONF message to Tor with a single <b>key</b> and returns a 00156 * QVariant containing the value returned by Tor. Returns a default 00157 * constructed QVariant on failure. */ 00158 QVariant getConf(const QString &key, QString *errmsg = 0); 00159 /** Sends a GETCONF message to Tor with the single key and returns a QString 00160 * containing the value returned by Tor */ 00161 QString getHiddenServiceConf(const QString &key, QString *errmsg = 0); 00162 00163 /** Asks Tor to save the current configuration to its torrc */ 00164 bool saveConf(QString *errmsg = 0); 00165 /** Tells Tor to reset the given configuration keys back to defaults. */ 00166 bool resetConf(QStringList keys, QString *errmsg = 0); 00167 /** Tells Tor to reset a configuration key back to its default value. */ 00168 bool resetConf(QString key, QString *errmsg = 0); 00169 00170 /** Returns an unparsed router descriptor for the router whose fingerprint 00171 * matches <b>id</b>. The returned text can later be parsed by the 00172 * RouterDescriptor class. If <b>id</b> is invalid, then an empty 00173 * QStringList is returned. */ 00174 QStringList getRouterDescriptorText(const QString &id, QString *errmsg = 0); 00175 /** Returns the descriptor for the router whose fingerprint matches 00176 * <b>id</b>. If <b>id</b> is invalid or the router's descriptor cannot be 00177 * parsed, then an invalid RouterDescriptor is returned. */ 00178 RouterDescriptor getRouterDescriptor(const QString &id, QString *errmsg = 0); 00179 /** Returns the status of the router whose fingerprint matches <b>id</b>. If 00180 * <b>id</b> is invalid or the router's status cannot be parsed, then an 00181 * invalid RouterStatus is returned. */ 00182 RouterStatus getRouterStatus(const QString &id, QString *errmsg = 0); 00183 /** Returns a RouterStatus object for every known router in the network. If 00184 * the network status document cannot be parsed, then an empty NetworkStatus 00185 * is returned. */ 00186 NetworkStatus getNetworkStatus(QString *errmsg = 0); 00187 /** Returns the annotations for the router whose fingerprint matches 00188 * <b>id</b>. If <b>id</b> is invalid or the router's descriptor cannot be 00189 * parsed, then an empty DescriptorAnnotations is returned and 00190 * <b>errmsg</b> is set if it's not NULL. (Tor >= 0.2.0.13-alpha only) */ 00191 DescriptorAnnotations getDescriptorAnnotations(const QString &id, 00192 QString *errmsg = 0); 00193 00194 /** Gets a list of current circuits. */ 00195 CircuitList getCircuits(QString *errmsg = 0); 00196 /** Gets a list of current streams. */ 00197 StreamList getStreams(QString *errmsg = 0); 00198 00199 /** Gets a list of address mappings of the type specified by <b>type</b> 00200 * (defaults to <i>AddressMapAll</i>. */ 00201 AddressMap getAddressMap( 00202 AddressMap::AddressMapType type = AddressMap::AddressMapAll, 00203 QString *errmsg = 0); 00204 00205 public slots: 00206 /** Closes the circuit specified by <b>circId</b>. If <b>ifUnused</b> is 00207 * true, then the circuit will not be closed unless it is unused. */ 00208 bool closeCircuit(const CircuitId &circId, bool ifUnused = false, 00209 QString *errmsg = 0); 00210 /** Closes the stream specified by <b>streamId</b>. */ 00211 bool closeStream(const StreamId &streamId, QString *errmsg = 0); 00212 00213 signals: 00214 /** Emitted when the Tor process has started */ 00215 void started(); 00216 /** Emitted when the Tor process fails to start. */ 00217 void startFailed(QString errmsg); 00218 /** Emitted when the Tor process has stopped */ 00219 void stopped(int exitCode, QProcess::ExitStatus exitStatus); 00220 /** Emitted when the Tor process has stopped. */ 00221 void stopped(); 00222 /** Emitted when the controller has connected to Tor */ 00223 void connected(); 00224 /** Emitted when the controller failed to connect to Tor. */ 00225 void connectFailed(QString errmsg); 00226 /** Emitted when the controller has disconnected from Tor */ 00227 void disconnected(); 00228 /** Emitted when the control socket is connected and authenticated. */ 00229 void authenticated(); 00230 /** Emitted when Tor rejects our authentication attempt. */ 00231 void authenticationFailed(QString errmsg); 00232 00233 /** Emitted when Tor writes the message <b>msg</b> to the control port 00234 * with message severity <b>level</b>. 00235 */ 00236 void logMessage(tc::Severity level, const QString &msg); 00237 00238 /** Emitted when Tor sends a bandwidth usage update (roughly once every 00239 * second). <b>bytesReceived</b> is the number of bytes read by Tor over 00240 * the previous second and <b>bytesWritten</b> is the number of bytes 00241 * sent over the same interval. 00242 */ 00243 void bandwidthUpdate(quint64 bytesReceived, quint64 bytesSent); 00244 00245 /** Emitted when the stream status of <b>stream</b> has changed. 00246 */ 00247 void streamStatusChanged(const Stream &stream); 00248 00249 /** Emitted when the circuit status of <b>circuit</b> has changed. 00250 */ 00251 void circuitStatusChanged(const Circuit &circuit); 00252 00253 /** Emitted when Tor has mapped the address <b>from</b> to the address 00254 * <b>to</b>. <b>expires</b> indicates the time at which when the address 00255 * mapping will no longer be considered valid. 00256 */ 00257 void addressMapped(const QString &from, const QString &to, 00258 const QDateTime &expires); 00259 00260 /** Emitted when Tor has received one or more new router descriptors. 00261 * <b>ids</b> contains a list of digests of the new descriptors. 00262 */ 00263 void newDescriptors(const QStringList &ids); 00264 00265 /** Indicates Tor has been able to successfully establish one or more 00266 * circuits. 00267 */ 00268 void circuitEstablished(); 00269 00270 /** Indicates that Tor has decided the user's Tor software <b>version</b> 00271 * is no longer recommended for some <b>reason</b>. <b>recommended</b> is 00272 * a list of Tor software versions that are considered current. 00273 */ 00274 void dangerousTorVersion(tc::TorVersionStatus reason, 00275 const QString &version, 00276 const QStringList &recommended); 00277 00278 /** Emitted during Tor's startup process to indicate how far in its 00279 * bootstrapping process it has progressed. <b>status</b> may indicate 00280 * the current bootstrapping stage or an error during bootstrapping. 00281 */ 00282 void bootstrapStatusChanged(const BootstrapStatus &status); 00283 00284 /** Emitted when the user attempts to establish a connection to some 00285 * destination on port <b>port</b>, which is a port known to use 00286 * plaintext connections (as determined by Tor's WarnPlaintextPorts and 00287 * RejectPlaintextPorts torrc options). <b>rejected</b> indicates whether 00288 * Tor rejected the connection or permitted it to connect anyway. 00289 */ 00290 void dangerousPort(quint16 port, bool rejected); 00291 00292 /** Emitted when Tor detects a problem with a SOCKS connection from the 00293 * user, such as a bad hostname, dangerous SOCKS protocol type, or a bad 00294 * hostname. <b>type</b> indicates the type of error encountered and 00295 * <b>destination</b> (if non-empty) specifies the attempted connection 00296 * destination address or hostname. 00297 */ 00298 void socksError(tc::SocksError type, const QString &destination); 00299 00300 /** Emitted when Tor decides the client's external IP address has changed 00301 * to <b>ip</b>. If <b>hostname</b> is non-empty, Tor obtained the new 00302 * value for <b>ip</b> by resolving <b>hostname</b>. 00303 */ 00304 void externalAddressChanged(const QHostAddress &ip, const QString &hostname); 00305 00306 /** Indicates that Tor has determined the client's clock is potentially 00307 * skewed by <b>skew</b> seconds relative to <b>source</b>. 00308 */ 00309 void clockSkewed(int skew, const QString &source); 00310 00311 /** Emitted when Tor has encountered an internal bug. <b>reason</b> is 00312 * Tor's description of the bug. 00313 */ 00314 void bug(const QString &reason); 00315 00316 /** Emitted when Tor determines that the user's DNS provider is providing 00317 * an address for non-existent domains when it should really be saying 00318 * "NXDOMAIN". 00319 */ 00320 void dnsHijacked(); 00321 00322 /** Emitted when Tor determines that the user's DNS provider is providing 00323 * a hijacked address even for well-known websites. 00324 */ 00325 void dnsUseless(); 00326 00327 /** Indicates Tor has started testing the reachability of its OR port 00328 * using the IP address <b>ip</b> and port <b>port</b>. 00329 */ 00330 void checkingOrPortReachability(const QHostAddress &ip, quint16 port); 00331 00332 /** Tor has completed testing the reachability of its OR port using 00333 * the IP address <b>ip</b> and port <b>port</b>. If the user's OR port 00334 * was reachable, <b>reachable</b> will be set to true. 00335 */ 00336 void orPortReachabilityFinished(const QHostAddress &ip, quint16 port, 00337 bool reachable); 00338 00339 /** Indicates Tor has started testing the reachability of its directory 00340 * port using the IP address <b>ip</b> and port <b>port</b>. 00341 */ 00342 void checkingDirPortReachability(const QHostAddress &ip, quint16 port); 00343 00344 /** Tor has completed testing the reachability of its directory port using 00345 * the IP address <b>ip</b> and port <b>port</b>. If the user's directory 00346 * port was reachable, <b>reachable</b> will be set to true. 00347 */ 00348 void dirPortReachabilityFinished(const QHostAddress &ip, quint16 port, 00349 bool reachable); 00350 00351 /** Emitted when the directory authority with IP address <b>ip</b> and 00352 * port <b>port</b> rejected the user's server descriptor. <b>reason</b> 00353 * describes why the descriptor was rejected (e.g., malformed, skewed 00354 * clock, etc.). 00355 */ 00356 void serverDescriptorRejected(const QHostAddress &ip, quint16 port, 00357 const QString &reason); 00358 00359 /** Emitted when the directory authority with IP address <b>ip</b> and 00360 * port <b>port</b> accepted the user's server descriptor. 00361 */ 00362 void serverDescriptorAccepted(const QHostAddress &ip, quint16 port); 00363 00364 /** Emitted when at least one directory authority has accepted the user's 00365 * server descriptor. 00366 */ 00367 void serverDescriptorAccepted(); 00368 00369 private: 00370 /** Instantiates a connection used to talk to Tor's control port */ 00371 ControlConnection* _controlConn; 00372 /** Manages and monitors the Tor process */ 00373 TorProcess* _torProcess; 00374 /** Keep track of which events we're interested in */ 00375 TorEvents* _eventHandler; 00376 TorEvents::Events _events; 00377 /** The version of Tor we're currently talking to. */ 00378 QString _torVersion; 00379 #if defined(Q_OS_WIN32) 00380 /** Manages the Tor service, if supported and enabled */ 00381 TorService* _torService; 00382 #endif 00383 00384 /** Send a message to Tor and read the response */ 00385 bool send(ControlCommand cmd, ControlReply &reply, QString *errmsg = 0); 00386 /** Send a message to Tor and discard the response */ 00387 bool send(ControlCommand cmd, QString *errmsg = 0); 00388 /** Tells Tor the controller wants to enable <b>feature</b> via the 00389 * USEFEATURE control command. Returns true if the given feature was 00390 * successfully enabled. */ 00391 bool useFeature(const QString &feature, QString *errmsg = 0); 00392 00393 /* The slots below simply relay signals from the appropriate member objects */ 00394 private slots: 00395 void onStopped(int exitCode, QProcess::ExitStatus exitStatus); 00396 void onDisconnected(); 00397 void onLogStdout(const QString &severity, const QString &message); 00398 void onAuthenticated(); 00399 }; 00400 00401 #endif 00402