tor 0.1.0 → 0.1.1

data/README

@@ -10,6 +10,8 @@ Features
 
 * Supports checking whether Tor is installed in the user's current `PATH`,
   and if it is, returning the version number.
+* Supports querying and controlling a locally-running Tor process using the
+  [Tor Control Protocol (TC)][TC] over a socket connection.
 * Supports querying the [Tor DNS Exit List (DNSEL)][TorDNSEL] to determine
   whether a particular host is a Tor exit node or not.
 
@@ -24,6 +26,13 @@ Examples
     Tor.available?                                     #=> true
     Tor.version                                        #=> "0.2.1.25"
 
+### Obtaining information about a running Tor process
+
+    Tor::Controller.connect(:port => 9051) do |tor|
+      puts "Tor version: #{tor.version}"
+      puts "Tor config file: #{tor.config_file}"
+    end
+
 ### Checking whether a particular host is a Tor exit node
 
     Tor::DNSEL.include?("208.75.57.100")               #=> true
@@ -73,5 +82,6 @@ information, see <http://unlicense.org/> or the accompanying UNLICENSE file.
 
 [Tor]:       https://www.torproject.org/
 [TorDNSEL]:  https://www.torproject.org/tordnsel/
+[TC]:        http://gitweb.torproject.org/tor.git?a=blob_plain;hb=HEAD;f=doc/spec/control-spec.txt
 [OR]:        http://en.wikipedia.org/wiki/Onion_routing
 [Backports]: http://rubygems.org/gems/backports

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/lib/tor.rb

@@ -1,3 +1,5 @@
+require 'pathname'
+
 if RUBY_VERSION < '1.8.7'
   # @see http://rubygems.org/gems/backports
   begin
@@ -15,8 +17,9 @@ end
 ##
 # @see https://www.torproject.org/
 module Tor
-  autoload :DNSEL,   'tor/dnsel'
-  autoload :VERSION, 'tor/version'
+  autoload :Controller, 'tor/control'
+  autoload :DNSEL,      'tor/dnsel'
+  autoload :VERSION,    'tor/version'
 
   ##
   # Returns `true` if Tor is available, `false` otherwise.

data/lib/tor/control.rb

@@ -0,0 +1,238 @@
+require 'socket' unless defined?(Socket)
+
+module Tor
+  ##
+  # Tor Control Protocol (TC) client.
+  #
+  # The Tor control protocol is used by other programs (such as frontend
+  # user interfaces) to communicate with a locally running Tor process. It
+  # is not part of the Tor onion routing protocol.
+  #
+  # @example Establishing a controller connection (1)
+  #   tor = Tor::Controller.new
+  #
+  # @example Establishing a controller connection (2)
+  #   tor = Tor::Controller.new(:host => '127.0.0.1', :port => 9051)
+  #
+  # @example Authenticating the controller connection
+  #   tor.authenticate
+  #
+  # @example Obtaining information about the Tor process
+  #   tor.version      #=> "0.2.1.25"
+  #   tor.config_file  #=> #<Pathname:/opt/local/etc/tor/torrc>
+  #
+  # @see   http://gitweb.torproject.org/tor.git?a=blob_plain;hb=HEAD;f=doc/spec/control-spec.txt
+  # @see   http://www.thesprawl.org/memdump/?entry=8
+  # @since 0.1.1
+  class Controller
+    PROTOCOL_VERSION = 1
+
+    ##
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [String, #to_s]  :host    ("127.0.0.1")
+    # @option options [Integer, #to_i] :port    (9051)
+    # @option options [String, #to_s]  :cookie  (nil)
+    # @option options [Integer, #to_i] :version (PROTOCOL_VERSION)
+    def self.connect(options = {}, &block)
+      if block_given?
+        result = block.call(tor = self.new(options))
+        tor.quit
+        result
+      else
+        self.new(options)
+      end
+    end
+
+    ##
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [String, #to_s]  :host    ("127.0.0.1")
+    # @option options [Integer, #to_i] :port    (9051)
+    # @option options [String, #to_s]  :cookie  (nil)
+    # @option options [Integer, #to_i] :version (PROTOCOL_VERSION)
+    def initialize(options = {}, &block)
+      @options = options.dup
+      @host    = (@options.delete(:host)    || '127.0.0.1').to_s
+      @port    = (@options.delete(:port)    || 9051).to_i
+      @version = (@options.delete(:version) || PROTOCOL_VERSION).to_i
+      connect
+      if block_given?
+        block.call(self)
+        quit
+      end
+    end
+
+    attr_reader :host, :port
+
+    ##
+    # Establishes the socket connection to the Tor process.
+    #
+    # @example
+    #   tor.close
+    #   tor.connect
+    #
+    # @return [void]
+    def connect
+      close
+      @socket = TCPSocket.new(@host, @port)
+      @socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, true)
+      self
+    end
+
+    ##
+    # Returns `true` if the controller connection is active.
+    #
+    # @example
+    #   tor.connected?      #=> true
+    #   tor.close
+    #   tor.connected?      #=> false
+    #
+    # @return [Boolean]
+    def connected?
+      !!@socket
+    end
+
+    ##
+    # Closes the socket connection to the Tor process.
+    #
+    # @example
+    #   tor.close
+    #
+    # @return [void]
+    def close
+      @socket.close if @socket
+      @socket = nil
+      self
+    end
+
+    ##
+    # Tells the Tor process to hang up on this controller connection.
+    #
+    # This command can be used before authenticating.
+    #
+    # @example
+    #   C: QUIT
+    #   S: 250 closing connection
+    #   ^D
+    #
+    # @example
+    #   tor.quit
+    #
+    # @return [void]
+    def quit
+      send_command(:quit)
+      reply = read_reply
+      close
+      reply
+    end
+
+    ##
+    # Returns `true` if the controller connection has been authenticated.
+    #
+    # @example
+    #   tor.authenticated?  #=> false
+    #   tor.authenticate
+    #   tor.authenticated?  #=> true
+    #
+    # @return [Boolean]
+    def authenticated?
+      @authenticated || false
+    end
+
+    ##
+    # Authenticates the controller connection.
+    #
+    # @example
+    #   C: AUTHENTICATE
+    #   S: 250 OK
+    #
+    # @example
+    #   tor.authenticate
+    #
+    # @return [void]
+    # @raise  [AuthenticationError] if authentication failed
+    def authenticate(cookie = nil)
+      cookie ||= @options[:cookie]
+      send(:send_line, cookie ? "AUTHENTICATE #{cookie}" : "AUTHENTICATE")
+      case reply = read_reply
+        when '250 OK' then @authenticated = true
+        else raise AuthenticationError.new(reply)
+      end
+      self
+    end
+
+    ##
+    # Returns the version number of the Tor process.
+    #
+    # @example
+    #   C: GETINFO version
+    #   S: 250-version=0.2.1.25
+    #   S: 250 OK
+    #
+    # @example
+    #   tor.version         #=> "0.2.1.25"
+    #
+    # @return [String]
+    def version
+      send_command(:getinfo, 'version')
+      reply = read_reply.split('=').last
+      read_reply # skip "250 OK"
+      reply
+    end
+
+    ##
+    # Returns the path to the Tor configuration file.
+    #
+    # @example
+    #   C: GETINFO config-file
+    #   S: 250-config-file=/opt/local/etc/tor/torrc
+    #   S: 250 OK
+    #
+    # @example
+    #   tor.config_file     #=> #<Pathname:/opt/local/etc/tor/torrc>
+    #
+    # @return [Pathname]
+    def config_file
+      send_command(:getinfo, 'config-file')
+      reply = read_reply.split('=').last
+      read_reply # skip "250 OK"
+      Pathname(reply)
+    end
+
+  protected
+
+    ##
+    # Sends a command line over the socket.
+    #
+    # @param  [Symbol, #to_s] command
+    # @param  [Array<String>] args
+    # @return [void]
+    def send_command(command, *args)
+      authenticate unless authenticated?
+      send_line(["#{command.to_s.upcase}", *args].join(' '))
+    end
+
+    ##
+    # Sends a text line over the socket.
+    #
+    # @param  [String, #to_s] line
+    # @return [void]
+    def send_line(line)
+      @socket.write(line.to_s + "\r\n")
+      @socket.flush
+    end
+
+    ##
+    # Reads a reply line from the socket.
+    #
+    # @return [String]
+    def read_reply
+      @socket.readline.chomp
+    end
+
+    ##
+    # Used to signal an authentication error.
+    #
+    # @see Tor::Controller#authenticate
+    class AuthenticationError < StandardError; end
+  end
+end

data/lib/tor/version.rb

@@ -2,7 +2,7 @@ module Tor
   module VERSION
     MAJOR = 0
     MINOR = 1
-    TINY  = 0
+    TINY  = 1
     EXTRA = nil
 
     STRING = [MAJOR, MINOR, TINY, EXTRA].compact.join('.')

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Arto Bendiken
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-01 00:00:00 +02:00
+date: 2010-08-02 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -59,11 +59,12 @@ files:
 - README
 - UNLICENSE
 - VERSION
+- lib/tor/control.rb
 - lib/tor/dnsel.rb
 - lib/tor/version.rb
 - lib/tor.rb
 has_rdoc: false
-homepage: http://github.com/bendiken/tor-ruby
+homepage: http://cypherpunk.rubyforge.org/tor/
 licenses: 
 - Public Domain
 post_install_message: