class Tor::TController

Tor:TController is an extension of the Tor::Controller class, providing more methods. It inherits all methods from Tor::Controller and can be used to interact with Tor.

TController examples

require 'tor_extend'
Tor::TController.new(:host=>@getbridge_config[:torcontrolhost],
                                 :port=>@getbridge_config[:torcontrolport])
Tor::TController.new(:host=>"127.0.0.1",:port=>9051)
Tor::TController.connect
Tor::TController.authenticate("\"tor_control_password\"")
Tor::TController.sr(:signal,"HUP")
Tor::TController.sr(:signal,"newnym")
Tor::TController.getinfo("ns/all") 
Tor::TController.net_status
Tor::TController.closecircuit(15)    
Tor::TController.closeallcircuits
Tor::TController.signal("reload"
Tor::TController.extendcir(0,['or1','or2','or3'])
Tor::TController.setconf("__DisablePredictedCircuits",1) 
Tor::TController.setconf("__LeaveStreamsUnattached",1)
Tor::TController.getconf("ORPort")
Tor::TController.getconf("__LeaveStreamsUnattached")
Tor::TController.get_bridges( {:type=>'http',:port=>9050,:addr=>'127.0.0.1'}  )

For more details, visit [github.com/bendiken/tor-ruby#readme], [gitweb.torproject.org/torspec.git/tree]

Public Instance Methods

attach_stream(stream_no, cir_num ,hop_count) click to toggle source

This attaches streams to circuits. No documentation yet.

# File lib/tcontroller.rb, line 246
def attach_stream(stream_no, cir_num ,hop_count)
        puts "attachstream"
    if hop_count==0     
        sr(:attachstream,"#{stream_no} #{cir_num}")
    else
        sr(:attachstream,"#{stream_no} #{cir_num} HOP=#{hop_count}")
    end
end
bridges() click to toggle source

Returns all the brdiges in the database as an array.

#bridges => [{:ipaddr, :port, :lat, :lng},...]

# File lib/tcontroller.rb, line 228
def bridges
    Bridges.all
end
cir_status() click to toggle source

This returns the circuit-status in an array, or an empty array on failure

Get the circuit-status from Tor.

Tor::TController.cir_status
 ["46 BUILT ORa,ORb,ORc PURPOSE=GENERAL"]
# File lib/tcontroller.rb, line 42
def cir_status
    cirstatus=getinfo("circuit-status")
end
closeallcircuits() click to toggle source

This attempts to close all open circuits.

Closing all circuits

Tor::TController.closeallcircuits
# File lib/tcontroller.rb, line 60
def closeallcircuits
    x=cir_status
    if !x.empty?
        x.each{|eachcircuit|
            circnum = eachcircuit.match(/^\d+/)
            closecircuit(circnum)
        }
    end
end
closecircuit(circnum) click to toggle source

This attempts to close a single circuit.

Closing circuits

Tor::TController.closecircuit(15)
# File lib/tcontroller.rb, line 51
def closecircuit (circnum)
    errorstate,ans=sr(:closecircuit," #{circnum}")
end
ds() click to toggle source

Returns the an array of of directory servers from the consensus.

#ds => [w.x.y.z:port, ...]

# File lib/tcontroller.rb, line 74
def ds
    reply=[]
    s = getinfo("ns/all")
    case version
        when /0.2.[01]/
            z=2
        when/0.2.2/
            z = 4 # To accommodate r, s , w and p]
    end
    s.collect!{|eachs| eachs.start_with?("r ") ? eachs : nil }
    s.delete nil
    s.each{|eachs|
        dsport=eachs.split[8].to_i
        rip=eachs.split[6]
        reply << "#{rip}:#{dsport}" if dsport!= 0
    }
    reply
end
extendcir(circnum,or_list) click to toggle source

This creates/extends a circuit over multiple nodes. A new circuit is created if cir_num == 0.

Creating a new circuit

create_circ = Tor::TController.extendcir(0,['or1','or2','or3'])
# File lib/tcontroller.rb, line 99
 def extendcir(circnum,or_list)
    argor=" #{circnum} #{or_list.join(',')}"
    extendcir=send_command(:extendcircuit,argor)
    circuit_id=nil
    readterm=true
    while readterm do
        case msg=read_reply
            when /^\d+ CIRC \d+ BUILT/,/250 /            #/^\d+ CIRC \d+ BUILT/
                circuit_id=msg.scan(/\d+\Z/)[0]
                readterm=false
            when /^5\d\d /
                readterm=false
            when /^\d+ /
                puts msg                                               #like extended launched
            else
                puts msg,"\n"
        end
    end
    #sr(:signal,"newnym")  
    circuit_id
end
extendcir_slowly(orarray) click to toggle source

This builds a circuit to each member of the array argument, skipping any node that fails to connect. It returns the circuit number, and the longest successful circuit that was successfully built. There is a delay of 2.0 seconds after each extension, but this can be altered by defining Tor::EXTEND_DELAY constant.

Create a circuit as long as possible using 10 elements in an array

testarray = [A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z]
Tor::TController.extendcir_slowly(testarray)
# File lib/tcontroller.rb, line 128
def extendcir_slowly(orarray)
    ordelay = defined?(EXTEND_DELAY) ? EXTEND_DELAY : Constants::EXTEND_DELAY
    cirnum = 0
    circuit = []
    orarray.each{|eachor|
        cirnum=extendcir(cirnum,[eachor])
        sleep(ordelay)    # wait for a few seconds, and check if the circuit is was successful
        p=cir_status.detect{|i|  i =~ (/^#{cirnum} / )}
        case p
          when /FAILED/,nil
            puts "cirnum=nil"
            if eachor != circuit.last
                cirnum = extendcir(0,circuit)
                sleep(circuit.count)
            elsif circuit.empty?
                return nil    # failed to build circuit at start, make sure orarray[0] is up
            end
          when /EXTENDED/, /BUILT/
            circuit << eachor
            puts "Extended! cirnum = #{cirnum}, circuit length = #{circuit.count}"
          when /LAUNCHED/
              sleep(1)
              puts x=cir_status.detect{|a| a =~ /^#{cirnum}/}
              circuit << eachor if (x =~ /BUILT/) or (x =~/EXTENDED/)
        end
    }
    [cirnum,circuit]
end
get_bridges(url, cacheddesc, *config) click to toggle source

This gets 3 bridge IP addresses from the Tor bridge website. proxyconfig is optional. default proxyconfig = {:type=>‘tor’ ,:port=>9050,:addr=>‘127.0.0.1’} The return format is fo the form:

[HTTPcode, [{:bridgeip, :bridgeport},{:bridgeip, :bridgeport},{:bridgeip, :bridgeport}]. The types can be one of ‘tor’, ‘polipo’, ‘socks’, ‘http’, ‘https’,nil, ‘none’.

torctrl_cirnum must have the form:
torctrl_cirnum ={:torctrl=>Tor::TController, :cirnum=>cirnum,:hop=>hopcount}

Get 3 bridges

Tor::TController.get_bridges( {:proxytype=>'tor',:proxyport=>9050,:proxyaddr=>'127.0.0.1'}  )
# File lib/tcontroller.rb, line 168
def get_bridges(url, cacheddesc, *config)
    if config.empty?
        proxyconfig={:type=>'tor' ,:port=>9050,:addr=>'127.0.0.1'}
    else
        proxyconfig = config[0]
    end
    if ! defined?(@myhttperrors)
         @myhttperrors=0
    end
    case proxyconfig[:type]
      when /none/,nil
        http_session=Net::HTTP.new(url.host,url.port)
      when /socks/,/tor/
        http_session=Net::HTTP.SOCKSProxy(proxyconfig[:addr], proxyconfig[:port]).new(url.host,url.port)
      when /http/,/https/,/polipo/
        http_session=Net::HTTP::Proxy(proxyconfig[:addr], proxyconfig[:port]).new(url.host,url.port)
    end
    if url.scheme=="https"
        http_session.use_ssl = true
        http_session.verify_mode = OpenSSL::SSL::VERIFY_NONE
    else
        http_session.use_ssl=false
    end
    bridges=[]
    # Rescue from http error
    begin
        resp = http_session.get2 url.path # Let Tor choose circuit itself
        # Additional code will be added shortly to attach the stream to the circuit directly
        puts "#{resp.code} HTTP response"
        #puts resp.body
        respcode= resp.code=="200" ? 200:nil
        if resp.code == "200"
            torbridgeip=resp.body.scan(/\d+\.\d+\.\d+\.\d+\:\d+/)
            torbridgeip.each{|eachbridge|
                bridgeip,bridgeport= eachbridge.split(':')
                x=Bridge.where(:ipaddr=>bridgeip, :port =>bridgeport)
                if x.empty?
                    if (bridge_geoip=cacheddesc.get_geoiprecord(bridgeip)).nil?
                        Bridge.create(:ipaddr=>bridgeip, :port =>bridgeport,
                                              :lat=>0, :lng=>0)
                    else
                        Bridge.create(:ipaddr=>bridgeip, :port =>bridgeport,
                                              :lat=>bridge_geoip.latitude.to_f,
                                              :lng=>bridge_geoip.longitude.to_f )
                    end
                end
            }
        end
     bridges = torbridgeip
    rescue
        @myhttperrors +=1
        respcode=nil
        bridges=[]
    end
    bridges #Return array of all bridges
end
get_entryguards() click to toggle source

This gets enty guards from the control port of tor using the getinfo “entry-guards” command and returns just the fingerprints in an array.

Get entry-guards

Tor::TController.get_entryguards       #=> ["$abc123","$def456"...]
# File lib/tcontroller.rb, line 262
def get_entryguards
    rslt = getinfo "entry-guards"
    reply = rslt.collect{|eachguard|   
    case eachguard
      when / unusable/
        nil
      else
        "$"+ eachguard.split(/[~ =]/)[0]
    end
    }
    reply.delete(nil)
    reply
end
get_httperrors() click to toggle source

This returns the number of HTTP errors from the #get_bridges command

# File lib/tcontroller.rb, line 278
def get_httperrors
    @myhttperrors
end
get_purposeip(nodetype) click to toggle source

This gets the IP addresses for ORs based on the characteristics of the OR. Example of the properties include: Fast, Guard, HSDir, Named, Running, Stable, V2Dir, Valid, Exit.

Get all Exit, Fast and entry Guard ORs

Tor::TController.get_purposeip("Exit")    #=> ["a.b.c.d","e.f.g.h"...]
Tor::TController.get_purposeip("fast exit")
Tor::TController.get_purposeip("Guard")
# File lib/tcontroller.rb, line 290
def get_purposeip(nodetype)
    reply=[]
    s = getinfo("ns/all")
    ctr_i= s.size / 2
    ctr_i.times{|j|
        rip=s[j*2].split[6]
        x=Router.where(:ipaddr=>rip)
        if !x.empty?
            finprint = "$" + x[0].fingerprint
            matcharray=nodetype.split.collect{|eachtype|
              if eachtype.start_with? '!'
                  matchme = eachtype[1..(eachtype.length-1)]
                  rslt = !(s[j*2+1] =~ (/#{matchme}/))
                  rslt ? rslt : nil   #return nil if false, or return the number
              else
                  s[j*2+1] =~ (/#{eachtype}/)
              end
            }
            reply << finprint if !matcharray.include? nil
        end
    }
    reply
end
getconf(confname) click to toggle source

This gets a configuration from Tor. The arguments of this command might be case sensitive. It returns the protocol error message if it fails.

Get the present ORport Tor is using

 Tor::TController.getconf("ORPort")                            #=>"9001"
 Tor::TController.getconf("__LeaveStreamsUnattached")          #=>"1"

For more details, see [https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt]
# File lib/tcontroller.rb, line 322
def getconf(confname)
    send_command(:getconf, confname)
    reply=[]
    case msg=read_reply
      when /250 /
        msg.split(/250 \S*=/).last
      else
        msg
    end
end
getinfo(*args) click to toggle source

This method sends the “GETINFO” protocol message with the arguments.

Getting more information from Tor

Tor::TController.getinfo("ns/all")
# File lib/tcontroller.rb, line 339
def getinfo(*args)
    errorcode,ans = sr(:getinfo,*args)
    ans
end
net_status() click to toggle source

This returns an array of hash tables with the fingerprints of all onion routers that have not been marked as down.

Get the network status from Tor

Tor::TController.net_status       => [ {:fingerprint=>"$ABCD"},{:fingerprint=>"$EFGH"}...]
# File lib/tcontroller.rb, line 349
def net_status 
    case version
        when /0.2.[01]/
            net_status1
        when/0.2.2/
            net_status2
    end
end
newstreams() click to toggle source

This returns all the new streams that have not been assigned to a circuit

# File lib/tcontroller.rb, line 233
def newstreams
    reply=[]
    getinfo("stream-status").each{|eachstream|
        case eachstream
          when /\d+ NEW 0/
          # It might be simpler to use this /\d+ NEW/
          reply << eachstream.scan(/\d+/)[0]
        end
    }
    reply
end
setconf(confname,value) click to toggle source

This sets a configuration in Tor to a value.

Setting Tor config

Tor::TController.setconf("__DisablePredictedCircuits",1)        =>["OK", []] 
Tor::TController.setconf("__LeaveStreamsUnattached",1)       =>["OK", []] 
Tor::TController.setconf("ORPort",9001)                                =>["OK", []]
# File lib/tcontroller.rb, line 409
def setconf(confname,value)
    sr(:setconf,"#{confname}=#{value}")
end
signal(args) click to toggle source

This method sends “signals” protocol message with the arguments.

Reload Tor config from file

Tor::TController.signal("RELOAD")
Tor::TController.signal("HUP")
# File lib/tcontroller.rb, line 419
def signal(args)
    reply=[]
    case (args)
        when /NEWNYM/,/CLEARDNSCACHE/,/RELOAD/,/HUP/,/DUMP/,/USR1/,/DEBUG/,/USR2/,/shutdown/,/INT/
            errorcode,reply=sr(:signal, args)
            close if args =~ /shutdown/ or args =~ /INT/
        when /HALT/,/TERM/
            send_command(:signal, "HALT")
            close
        else
            puts "#{args} not recognised by the at library development. Sending the signal nonetheless"
            reply=sr(:signal,args)
    end
    reply
end
sr(command, *args) click to toggle source

This sends commands and returns the protocol response code along with an array containing the results with the following format [errorcode,[array_of_results]].

Send and receive commands.

Tor::TController.sr(:signal,"reload")
Tor::TController.sr(:signal,"newnym")
# File lib/tcontroller.rb, line 442
def sr(command, *args)
    send_command(command, *args)
    reply=[]
    readterm=true
    while readterm do
        # Read as much as possible until '250 OK' or error 5YZ
        case msg=read_reply
          when /^250 OK/
                readterm=false
                puts errorstate="OK"
          when /^250[\+,\-,\s]/
            reply << msg.split(/^\d+[\+,\-,\s]\S*=/).last unless msg=~/250\+/
            errorstate = "OK"
          when /^\./
          when /^5\d\d /
            if errorstate == "OK"  # if a "2yz " code came before this then msg is part of response
                reply << msg
            else
                puts msg
                errorstate = msg.match(/^5\d\d/)
                readterm=false
            end
          else
             reply << msg
        end
    end
    reply.delete(nil)
    reply = errorstate=="OK" ? reply : []
    [errorstate,reply]
end