contrib/TorControl.py

   1 #!/usr/bin/python
   2 # TorControl.py -- Python module to interface with Tor Control interface.
   3 # Copyright 2005 Nick Mathewson -- See LICENSE for licensing information.
   4 #$Id$
   5
   6 import socket
   7 import struct
   8 import sys
   9
  10 #__all__ = [ "MSG_TYPE", "" ]
  11
  12 class _Enum:
  13     # Helper: define an ordered dense name-to-number 1-1 mapping.
  14     def __init__(self, start, names):
  15         self.nameOf = {}
  16         idx = start
  17         for name in names:
  18             setattr(self,name,idx)
  19             self.nameOf[idx] = name
  20             idx += 1
  21 class _Enum2:
  22     # Helper: define an ordered sparse name-to-number 1-1 mapping.
  23     def __init__(self, **args):
  24         self.__dict__.update(args)
  25         self.nameOf = {}
  26         for k,v in args.items():
  27             self.nameOf[v] = k
  28
  29 # Message types that client or server can send.
  30 MSG_TYPE = _Enum(0x0000,
  31                  ["ERROR",
  32                   "DONE",
  33                   "SETCONF",
  34                   "GETCONF",
  35                   "CONFVALUE",
  36                   "SETEVENTS",
  37                   "EVENT",
  38                   "AUTH",
  39                   "SAVECONF",
  40                   "SIGNAL",
  41                   "MAPADDRESS",
  42                   "GETINFO",
  43                   "INFOVALUE",
  44                   "EXTENDCIRCUIT",
  45                   "ATTACHSTREAM",
  46                   "POSTDESCRIPTOR",
  47                   "FRAGMENTHEADER",
  48                   "FRAGMENT",
  49                   "REDIRECTSTREAM",
  50                   "CLOSESTREAM",
  51                   "CLOSECIRCUIT",
  52                   ])
  53
  54 # Make sure that the enumeration code is working.
  55 assert MSG_TYPE.SAVECONF == 0x0008
  56 assert MSG_TYPE.CLOSECIRCUIT == 0x0014
  57
  58 # Types of "EVENT" message.
  59 EVENT_TYPE = _Enum(0x0001,
  60                    ["CIRCSTATUS",
  61                     "STREAMSTATUS",
  62                     "ORCONNSTATUS",
  63                     "BANDWIDTH",
  64                     "OBSOLETE_LOG",
  65                     "NEWDESC",
  66                     "DEBUG_MSG",
  67                     "INFO_MSG",
  68                     "NOTICE_MSG",
  69                     "WARN_MSG",
  70                     "ERR_MSG",
  71                     ])
  72
  73 assert EVENT_TYPE.ERR_MSG == 0x000B
  74 assert EVENT_TYPE.OBSOLETE_LOG == 0x0005
  75
  76 # Status codes for "CIRCSTATUS" events.
  77 CIRC_STATUS = _Enum(0x00,
  78                     ["LAUNCHED",
  79                      "BUILT",
  80                      "EXTENDED",
  81                      "FAILED",
  82                      "CLOSED"])
  83
  84 # Status codes for "STREAMSTATUS" events
  85 STREAM_STATUS = _Enum(0x00,
  86                       ["SENT_CONNECT",
  87                        "SENT_RESOLVE",
  88                        "SUCCEEDED",
  89                        "FAILED",
  90                        "CLOSED",
  91                        "NEW_CONNECT",
  92                        "NEW_RESOLVE",
  93                        "DETACHED"])
  94
  95 # Status codes for "ORCONNSTATUS" events
  96 OR_CONN_STATUS = _Enum(0x00,
  97                        ["LAUNCHED","CONNECTED","FAILED","CLOSED"])
  98
  99 # Signal codes for "SIGNAL" events.
 100 SIGNAL = _Enum2(HUP=0x01,INT=0x02,USR1=0x0A,USR2=0x0C,TERM=0x0F)
 101
 102 # Error codes for "ERROR" events.
 103 ERR_CODES = {
 104   0x0000 : "Unspecified error",
 105   0x0001 : "Internal error",
 106   0x0002 : "Unrecognized message type",
 107   0x0003 : "Syntax error",
 108   0x0004 : "Unrecognized configuration key",
 109   0x0005 : "Invalid configuration value",
 110   0x0006 : "Unrecognized byte code",
 111   0x0007 : "Unauthorized",
 112   0x0008 : "Failed authentication attempt",
 113   0x0009 : "Resource exhausted",
 114   0x000A : "No such stream",
 115   0x000B : "No such circuit",
 116   0x000C : "No such OR"
 117 }
 118
 119 class TorCtlError(Exception):
 120     "Generic error raised by TorControl code."
 121     pass
 122
 123 class ProtocolError(TorCtlError):
 124     "Raised on violations in Tor controller protocol"
 125     pass
 126
 127 class ErrorReply(TorCtlError):
 128     ""
 129     pass
 130
 131 def parseHostAndPort(h):
 132     host, port = "localhost", 9051
 133     if ":" in h:
 134         i = h.index(":")
 135         host = h[:i]
 136         try:
 137             port = int(h[i+1:])
 138         except ValueError:
 139             print "Bad hostname %r"%h
 140             sys.exit(1)
 141     elif h:
 142         try:
 143             port = int(h)
 144         except ValueError:
 145             host = h
 146
 147     return host, port
 148
 149 def _unpack_msg(msg):
 150     "return None, minLength, body or type,body,rest"
 151     if len(msg) < 4:
 152         return None, 4, msg
 153     length,type = struct.unpack("!HH",msg)
 154     if len(msg) >= 4+length:
 155         return type,msg[4:4+length],msg[4+length:]
 156     else:
 157         return None,4+length,msg
 158
 159 def _minLengthToPack(bytes):
 160     whole,left = divmod(bytes,65535)
 161     if left:
 162         return whole*(65535+4)+4+left
 163     else:
 164         return whole*(65535+4)
 165
 166 def unpack_msg(msg):
 167     "returns as for _unpack_msg"
 168     tp,body,rest = _unpack_msg(msg)
 169     if tp != MSG_TYPE.FRAGMENTHEADER:
 170         return tp, body, rest
 171
 172     if len(body) < 6:
 173         raise ProtocolError("FRAGMENTHEADER message too short")
 174
 175     realType,realLength = struct.unpack("!HL", body[:6])
 176
 177     # Okay; could the message _possibly_ be here?
 178     minLength = _minLengthToPack(realLength+6)
 179     if len(msg) < minLength:
 180         return None,  minLength, msg
 181
 182     # Okay; optimistically try to build up the msg.
 183     soFar = [ body[6:] ]
 184     lenSoFarLen = len(body)-6
 185     while len(rest)>=4 and lenSoFar < realLength:
 186         ln, tp = struct.unpack("!HH", rest[:4])
 187         if tp != MSG_TYPE.FRAGMENT:
 188             raise ProtocolError("Missing FRAGMENT message")
 189         soFar.append(rest[4:4+ln])
 190         lenSoFar += ln
 191         if 4+ln > len(rest):
 192             rest = ""
 193             leftInPacket = 4+ln-len(rest)
 194         else:
 195             rest = rest[4+ln:]
 196             leftInPacket=0
 197
 198     if lenSoFar == realLength:
 199         return realType, "".join(soFar), rest
 200     elif lenSoFar > realLength:
 201         raise ProtocolError("Bad fragmentation: message longer than declared")
 202     else:
 203         inOtherPackets = realLength-lenSoFar-leftInPacket
 204         minLength = _minLengthToPack(inOtherPackets)
 205         return None, len(msg)+leftInPacket+inOtherPackets, msg
 206
 207 def _receive_msg(s):
 208   body = ""
 209   header = s.recv(4)
 210   length,type = struct.unpack("!HH",header)
 211   if length:
 212     body = s.recv(length)
 213   return length,type,body
 214
 215 def receive_message(s):
 216     length, tp, body = _receive_msg(s)
 217     if tp != MSG_TYPE.FRAGMENTHEADER:
 218         return length, tp, body
 219     if length < 6:
 220         raise ProtocolError("FRAGMENTHEADER message too short")
 221     realType,realLength = struct.unpack("!HL", body[:6])
 222     data = [ body[6:] ]
 223     soFar = len(data[0])
 224     while 1:
 225         length, tp, body = _receive_msg(s)
 226         if tp != MSG_TYPE.FRAGMENT:
 227             raise ProtocolError("Missing FRAGMENT message")
 228         soFar += length
 229         data.append(body)
 230         if soFar == realLength:
 231             return realLength, realType, "".join(data)
 232         elif soFar > realLengtH:
 233             raise ProtocolError("FRAGMENT message too long!")
 234
 235 _event_handler = None
 236 def receive_reply(s, expected=None):
 237     while 1:
 238         _, tp, body = receive_message(s)
 239         if tp == MSG_TYPE.EVENT:
 240             if _event_handler is not None:
 241                 _event_handler(body)
 242         elif tp == MSG_TYPE.ERROR:
 243             if len(body)<2:
 244                 raise ProtocolError("(Truncated error message)")
 245             errCode, = struct.unpack("!H", body[:2])
 246             raise ErrorReply((errCode,
 247                               ERR_CODES.get(errCode,"[unrecognized]"),
 248                               body[2:]))
 249         elif (expected is not None) and (tp not in expected):
 250             raise ProtocolError("Unexpected message type 0x%04x"%tp)
 251         else:
 252             return tp, body
 253
 254 def pack_message(type, body=""):
 255     length = len(body)
 256     if length < 65536:
 257         reqheader = struct.pack("!HH", length, type)
 258         return "%s%s"%(reqheader,body)
 259
 260     fragheader = struct.pack("!HHHL",
 261                              65535, MSG_TYPE.FRAGMENTHEADER, type, length)
 262     msgs = [ fragheader, body[:65535-6] ]
 263     body = body[65535-6:]
 264     while body:
 265         if len(body) > 65535:
 266             fl = 65535
 267         else:
 268             fl = len(body)
 269         fragheader = struct.pack("!HH", MSG_TYPE.FRAGMENT, fl)
 270         msgs.append(fragheader)
 271         msgs.append(body[:fl])
 272         body = body[fl:]
 273
 274     return "".join(msgs)
 275
 276 def send_message(s, type, body=""):
 277     s.sendall(pack_message(type, body))
 278
 279 def authenticate(s):
 280     send_message(s,MSG_TYPE.AUTH)
 281     type,body = receive_reply(s)
 282     return
 283
 284 def _parseKV(body,sep=" ",term="\n"):
 285     res = []
 286     for line in body.split(term):
 287         if not line: continue
 288         print repr(line)
 289         k, v = line.split(sep,1)
 290         res.append((k,v))
 291     return res
 292
 293 def get_option(s,name):
 294     send_message(s,MSG_TYPE.GETCONF,name)
 295     tp,body = receive_reply(s,[MSG_TYPE.CONFVALUE])
 296     return _parseKV(body)
 297
 298 def set_option(s,msg):
 299     send_message(s,MSG_TYPE.SETCONF,msg)
 300     tp,body = receive_reply(s,[MSG_TYPE.DONE])
 301
 302 def get_info(s,name):
 303     send_message(s,MSG_TYPE.GETINFO,name)
 304     tp,body = receive_reply(s,[MSG_TYPE.INFOVALUE])
 305     kvs = body.split("\0")
 306     d = {}
 307     for i in xrange(0,len(kvs)-1,2):
 308         d[kvs[i]] = kvs[i+1]
 309     return d
 310
 311 def set_events(s,events):
 312     send_message(s,MSG_TYPE.SETEVENTS,
 313                  "".join([struct.pack("!H", event) for event in events]))
 314     type,body = receive_reply(s,[MSG_TYPE.DONE])
 315     return
 316
 317 def save_conf(s):
 318     send_message(s,MSG_TYPE.SAVECONF)
 319     receive_reply(s,[MSG_TYPE.DONE])
 320
 321 def send_signal(s, sig):
 322     send_message(s,MSG_TYPE.SIGNAL,struct.pack("B",sig))
 323     receive_reply(s,[MSG_TYPE.DONE])
 324
 325 def map_address(s, kv):
 326     msg = [ "%s %s\n"%(k,v) for k,v in kv ]
 327     send_message(s,MSG_TYPE.MAPADDRESS,"".join(msg))
 328     tp, body = receive_reply(s,[MSG_TYPE.DONE])
 329     return _parseKV(body)
 330
 331 def extend_circuit(s, circid, hops):
 332     msg = struct.pack("!L",circid) + ",".join(hops) + "\0"
 333     send_message(s,MSG_TYPE.EXTENDCIRCUIT,msg)
 334     tp, body = receive_reply(s,[MSG_TYPE.DONE])
 335     if len(body) != 4:
 336         raise ProtocolError("Extendcircuit reply too short or long")
 337     return struct.unpack("!L",body)[0]
 338
 339 def redirect_stream(s, streamid, newtarget):
 340     msg = struct.pack("!L",streamid) + newtarget + "\0"
 341     send_message(s,MSG_TYPE.REDIRECTSTREAM,msg)
 342     tp,body = receive_reply(s,[MSG_TYPE.DONE])
 343
 344 def attach_stream(s, streamid, circid):
 345     msg = struct.pack("!LL",streamid, circid)
 346     send_message(s,MSG_TYPE.ATTACHSTREAM,msg)
 347     tp,body = receive_reply(s,[MSG_TYPE.DONE])
 348
 349 def close_stream(s, streamid, reason=0, flags=0):
 350     msg = struct.pack("!LBB",streamid,reason,flags)
 351     send_message(s,MSG_TYPE.CLOSESTREAM,msg)
 352     tp,body = receive_reply(s,[MSG_TYPE.DONE])
 353
 354 def close_circuit(s, circid, flags=0):
 355     msg = struct.pack("!LB",circid,flags)
 356     send_message(s,MSG_TYPE.CLOSECIRCUIT,msg)
 357     tp,body = receive_reply(s,[MSG_TYPE.DONE])
 358
 359 def post_descriptor(s, descriptor):
 360     send_message(s,MSG_TYPE.POSTDESCRIPTOR,descriptor)
 361     tp,body = receive_reply(s,[MSG_TYPE.DONE])
 362
 363
 364 def _unterminate(s):
 365     if s[-1] == '\0':
 366         return s[:-1]
 367     else:
 368         return s
 369
 370 def unpack_event(body):
 371     if len(body)<2:
 372         raise ProtocolError("EVENT body too short.")
 373     evtype, = struct.unpack("!H", body[:2])
 374     body = body[2:]
 375     if evtype == EVENT_TYPE.CIRCSTATUS:
 376         if len(body)<5:
 377             raise ProtocolError("CIRCUITSTATUS event too short.")
 378         status,ident = struct.unpack("!BL", body[:5])
 379         path = _unterminate(body[5:]).split(",")
 380         args = status, ident, path
 381     elif evtype == EVENT_TYPE.STREAMSTATUS:
 382         if len(body)<5:
 383             raise ProtocolError("CIRCUITSTATUS event too short.")
 384         status,ident = struct.unpack("!BL", body[:5])
 385         target = _unterminate(body[5:])
 386         args = status, ident, target
 387     elif evtype == EVENT_TYPE.ORCONNSTATUS:
 388         if len(body)<2:
 389             raise ProtocolError("CIRCUITSTATUS event too short.")
 390         status = ord(body[0])
 391         target = _unterminate(body[1:])
 392         args = status, target
 393     elif evtype == EVENT_TYPE.BANDWIDTH:
 394         if len(body)<8:
 395             raise ProtocolError("BANDWIDTH event too short.")
 396         read, written = struct.unpack("!LL",body[:8])
 397         args = read, written
 398     elif evtype == EVENT_TYPE.OBSOLETE_LOG:
 399         args = (_unterminate(body),)
 400     elif evtype == EVENT_TYPE.NEWDESC:
 401         args = (_unterminate(body).split(","),)
 402     elif EVENT_TYPE.DEBUG_MSG <= evtype <= EVENT_TYPE.ERR_MSG:
 403         args = (EVENT_TYPE.nameOf(evtype), _unterminate(body))
 404     else:
 405         args = (body,)
 406
 407     return evtype, args
 408
 409 def listen_for_events(s):
 410     while(1):
 411         _,type,body = receive_message(s)
 412         print unpack_event(body)
 413     return
 414
 415 def do_main_loop(host,port):
 416     print "host is %s:%d"%(host,port)
 417     s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
 418     s.connect((host,port))
 419     authenticate(s)
 420     print "nick",`get_option(s,"nickname")`
 421     print get_option(s,"DirFetchPeriod\n")
 422     print `get_info(s,"version")`
 423     #print `get_info(s,"desc/name/moria1")`
 424     print `get_info(s,"network-status")`
 425     print `get_info(s,"addr-mappings/all")`
 426     print `get_info(s,"addr-mappings/config")`
 427     print `get_info(s,"addr-mappings/cache")`
 428     print `get_info(s,"addr-mappings/control")`
 429     print `map_address(s, [("0.0.0.0", "Foobar.com"),
 430                            ("1.2.3.4", "foobaz.com"),
 431                            ("frebnitz.com", "5.6.7.8"),
 432                            (".", "abacinator.onion")])`
 433     print `extend_circuit(s,0,["moria1"])`
 434     send_signal(s,1)
 435     #save_conf(s)
 436
 437
 438     #set_option(s,"1")
 439     #set_option(s,"bandwidthburstbytes 100000")
 440     #set_option(s,"runasdaemon 1")
 441     #set_events(s,[EVENT_TYPE.WARN])
 442     set_events(s,[EVENT_TYPE.OBSOLETE_LOG])
 443
 444     listen_for_events(s)
 445
 446     return
 447
 448 if __name__ == '__main__':
 449     if len(sys.argv) != 2:
 450         print "Syntax: tor-control.py torhost:torport"
 451         sys.exit(0)
 452     sh,sp = parseHostAndPort(sys.argv[1])
 453     do_main_loop(sh,sp)
 454