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 3900 2009-06-26 23:20:39Z 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 <QObject> 00021 #include <QHash> 00022 #include <QList> 00023 #include <QStringList> 00024 #include <QVariant> 00025 00026 #include "controlconnection.h" 00027 #include "torprocess.h" 00028 #include "torevents.h" 00029 #include "torsignal.h" 00030 #include "routerdescriptor.h" 00031 #include "routerstatus.h" 00032 #include "bootstrapstatus.h" 00033 #include "addressmap.h" 00034 #include "protocolinfo.h" 00035 00036 #if defined(Q_OS_WIN32) 00037 #include "torservice.h" 00038 #endif 00039 00040 00041 /** DescriptorAnnotations stores a map of annotation keys to (possibly empty) 00042 * annotation values. */ 00043 typedef QHash<QString,QString> DescriptorAnnotations; 00044 00045 00046 class TorControl : public QObject 00047 { 00048 Q_OBJECT 00049 00050 public: 00051 /** Default constructor */ 00052 TorControl(); 00053 /** Default destructor */ 00054 ~TorControl(); 00055 00056 /** Start the Tor process */ 00057 void start(const QString &tor, const QStringList &args); 00058 /** Stop the Tor process */ 00059 bool stop(QString *errmsg = 0); 00060 /** Detect if the Tor process is running */ 00061 bool isRunning(); 00062 /** Detects if the Tor process is running under Vidalia. */ 00063 bool isVidaliaRunningTor(); 00064 /** Stops reading log messages from the Tor process's stdout. This has no 00065 * effect if isVidaliaRunningTor() is false. */ 00066 void closeTorStdout(); 00067 00068 /** Connect to Tor's control socket */ 00069 void connect(const QHostAddress &address, quint16 port); 00070 /** Disconnect from Tor's control socket */ 00071 void disconnect(); 00072 /** Check if we're connected to Tor's control socket */ 00073 bool isConnected(); 00074 /** Sends an authentication cookie to Tor. */ 00075 bool authenticate(const QByteArray cookie, QString *errmsg = 0); 00076 /** Sends an authentication password to Tor. */ 00077 bool authenticate(const QString password = QString(), QString *errmsg = 0); 00078 00079 /** Sends a PROTOCOLINFO command to Tor and parses the response. */ 00080 ProtocolInfo protocolInfo(QString *errmsg = 0); 00081 00082 /** Returns the Tor software's current bootstrap phase and status. */ 00083 BootstrapStatus bootstrapStatus(QString *errmsg = 0); 00084 00085 /** Returns true if Tor either has an open circuit or (on Tor >= 00086 * 0.2.0.1-alpha) has previously decided it's able to establish a circuit. */ 00087 bool circuitEstablished(); 00088 00089 /** Sends a GETINFO message to Tor based on the given keys */ 00090 bool getInfo(QHash<QString,QString> &map, QString *errmsg = 0); 00091 /** Sends a GETINFO message for a single info value to Tor */ 00092 bool getInfo(QString key, QString &val, QString *errmsg = 0); 00093 00094 /** Sends a GETINFO message to Tor using the given list of <b>keys</b> and 00095 * returns a QVariantMap containing the specified keys and their values as 00096 * returned by Tor. Returns a default constructed QVariantMap on failure. */ 00097 QVariantMap getInfo(const QStringList &keys, QString *errmsg = 0); 00098 /** Sends a GETINFO message to Tor with a single <b>key</b> and returns a 00099 * QVariant containing the value returned by Tor. Returns a default 00100 * constructed QVariant on failure. */ 00101 QVariant getInfo(const QString &key, QString *errmsg = 0); 00102 00103 00104 /** Sends a signal to Tor */ 00105 bool signal(TorSignal::Signal sig, QString *errmsg = 0); 00106 00107 /** Returns an address on which Tor is listening for application 00108 * requests. If none are available, a null QHostAddress is returned. */ 00109 QHostAddress getSocksAddress(QString *errmsg = 0); 00110 /** Returns a (possibly empty) list of all currently configured 00111 * SocksListenAddress entries. */ 00112 QStringList getSocksAddressList(QString *errmsg = 0); 00113 /** Returns a valid SOCKS port for Tor, or 0 if Tor is not accepting 00114 * application requests. */ 00115 quint16 getSocksPort(QString *errmsg = 0); 00116 /** Returns a list of all currently configured SOCKS ports. If Tor is not 00117 * accepting any application connections, an empty list will be returned. */ 00118 QList<quint16> getSocksPortList(QString *errmsg = 0); 00119 00120 /** Returns Tor's version as a string. */ 00121 QString getTorVersionString(); 00122 /** Returns Tor's version as a numeric value. */ 00123 quint32 getTorVersion(); 00124 00125 /** Sets an event and its handler. If add is true, then the event is added, 00126 * otherwise it is removed. If set is true, then the given event will be 00127 * registered with Tor. */ 00128 bool setEvent(TorEvents::TorEvent e, QObject *obj, 00129 bool add, bool set = true, QString *errmsg = 0); 00130 /** Registers for a set of logging events according to the given filter. */ 00131 bool setLogEvents(uint filter, QObject *obj, QString *errmsg = 0); 00132 /** Register events of interest with Tor */ 00133 bool setEvents(QString *errmsg = 0); 00134 00135 00136 /** Sets each configuration key in <b>map</b> to the value associated with its key. */ 00137 bool setConf(QHash<QString,QString> map, QString *errmsg = 0); 00138 /** Sets a single configuration key to the given value. */ 00139 bool setConf(QString key, QString value, QString *errmsg = 0); 00140 /** Sets a single configuration string that is formatted <key=escaped value>. */ 00141 bool setConf(QString keyAndValue, QString *errmsg = 0); 00142 /** Gets values for a set of configuration keys, each of which has a single 00143 * value. */ 00144 bool getConf(QHash<QString,QString> &map, QString *errmsg = 0); 00145 /** Gets a set of configuration keyvalues and stores them in <b>map</b>. */ 00146 bool getConf(QHash<QString,QStringList> &map, QString *errmsg = 0); 00147 /** Gets a single configuration value for <b>key</b>. */ 00148 bool getConf(QString key, QString &value, QString *errmsg = 0); 00149 /** Gets a list of configuration values for <b>key</b>. */ 00150 bool getConf(QString key, QStringList &value, QString *errmsg = 0); 00151 00152 /** Sends a GETCONF message to Tor using the given list of <b>keys</b> and 00153 * returns a QVariantMap containing the specified keys and their values as 00154 * returned by Tor. Returns a default constructed QVariantMap on failure. */ 00155 QVariantMap getConf(const QStringList &keys, QString *errmsg = 0); 00156 /** Sends a GETCONF message to Tor with a single <b>key</b> and returns a 00157 * QVariant containing the value returned by Tor. Returns a default 00158 * constructed QVariant on failure. */ 00159 QVariant getConf(const QString &key, QString *errmsg = 0); 00160 /** Sends a GETCONF message to Tor with the single key and returns a QString 00161 * containing the value returned by Tor */ 00162 QString getHiddenServiceConf(const QString &key, QString *errmsg = 0); 00163 00164 /** Asks Tor to save the current configuration to its torrc */ 00165 bool saveConf(QString *errmsg = 0); 00166 /** Tells Tor to reset the given configuration keys back to defaults. */ 00167 bool resetConf(QStringList keys, QString *errmsg = 0); 00168 /** Tells Tor to reset a configuration key back to its default value. */ 00169 bool resetConf(QString key, QString *errmsg = 0); 00170 00171 /** Returns the descriptor for the router whose fingerprint matches 00172 * <b>id</b>. If <b>id</b> is invalid or the router's descriptor cannot be 00173 * parsed, then an invalid RouterDescriptor is returned. */ 00174 RouterDescriptor getRouterDescriptor(const QString &id, QString *errmsg = 0); 00175 /** Returns the status of the router whose fingerprint matches <b>id</b>. If 00176 * <b>id</b> is invalid or the router's status cannot be parsed, then an 00177 * invalid RouterStatus is returned. */ 00178 RouterStatus getRouterStatus(const QString &id, QString *errmsg = 0); 00179 /** Returns a RouterStatus object for every known router in the network. If 00180 * the network status document cannot be parsed, then an empty NetworkStatus 00181 * is returned. */ 00182 NetworkStatus getNetworkStatus(QString *errmsg = 0); 00183 /** Returns the annotations for the router whose fingerprint matches 00184 * <b>id</b>. If <b>id</b> is invalid or the router's descriptor cannot be 00185 * parsed, then an empty DescriptorAnnotations is returned and 00186 * <b>errmsg</b> is set if it's not NULL. (Tor >= 0.2.0.13-alpha only) */ 00187 DescriptorAnnotations getDescriptorAnnotations(const QString &id, 00188 QString *errmsg = 0); 00189 00190 /** Gets a list of current circuits. */ 00191 CircuitList getCircuits(QString *errmsg = 0); 00192 /** Gets a list of current streams. */ 00193 StreamList getStreams(QString *errmsg = 0); 00194 00195 /** Gets a list of address mappings of the type specified by <b>type</b> 00196 * (defaults to <i>AddressMapAll</i>. */ 00197 AddressMap getAddressMap( 00198 AddressMap::AddressMapType type = AddressMap::AddressMapAll, 00199 QString *errmsg = 0); 00200 00201 public slots: 00202 /** Closes the circuit specified by <b>circId</b>. If <b>ifUnused</b> is 00203 * true, then the circuit will not be closed unless it is unused. */ 00204 bool closeCircuit(const CircuitId &circId, bool ifUnused = false, 00205 QString *errmsg = 0); 00206 /** Closes the stream specified by <b>streamId</b>. */ 00207 bool closeStream(const StreamId &streamId, QString *errmsg = 0); 00208 00209 signals: 00210 /** Emitted when the Tor process has started */ 00211 void started(); 00212 /** Emitted when the Tor process fails to start. */ 00213 void startFailed(QString errmsg); 00214 /** Emitted when the Tor process has stopped */ 00215 void stopped(int exitCode, QProcess::ExitStatus exitStatus); 00216 /** Emitted when the Tor process has stopped. */ 00217 void stopped(); 00218 /** Emitted when the controller has connected to Tor */ 00219 void connected(); 00220 /** Emitted when the controller failed to connect to Tor. */ 00221 void connectFailed(QString errmsg); 00222 /** Emitted when the controller has disconnected from Tor */ 00223 void disconnected(); 00224 /** Emitted when the control socket is connected and authenticated. */ 00225 void authenticated(); 00226 /** Emitted when Tor rejects our authentication attempt. */ 00227 void authenticationFailed(QString errmsg); 00228 00229 private: 00230 /** Instantiates a connection used to talk to Tor's control port */ 00231 ControlConnection* _controlConn; 00232 /** Manages and monitors the Tor process */ 00233 TorProcess* _torProcess; 00234 /** Keep track of which events we're interested in */ 00235 TorEvents _torEvents; 00236 /** The version of Tor we're currently talking to. */ 00237 QString _torVersion; 00238 #if defined(Q_OS_WIN32) 00239 /** Manages the Tor service, if supported and enabled */ 00240 TorService* _torService; 00241 #endif 00242 00243 /** Send a message to Tor and read the response */ 00244 bool send(ControlCommand cmd, ControlReply &reply, QString *errmsg = 0); 00245 /** Send a message to Tor and discard the response */ 00246 bool send(ControlCommand cmd, QString *errmsg = 0); 00247 /** Tells Tor the controller wants to enable <b>feature</b> via the 00248 * USEFEATURE control command. Returns true if the given feature was 00249 * successfully enabled. */ 00250 bool useFeature(const QString &feature, QString *errmsg = 0); 00251 00252 /* The slots below simply relay signals from the appropriate member objects */ 00253 private slots: 00254 void onStarted(); 00255 void onStartFailed(QString errmsg); 00256 void onStopped(int exitCode, QProcess::ExitStatus exitStatus); 00257 void onConnected(); 00258 void onConnectFailed(QString errmsg); 00259 void onDisconnected(); 00260 void onLogStdout(QString severity, QString message); 00261 void onAuthenticated(); 00262 }; 00263 00264 #endif 00265