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