tor 0.1.0

data/AUTHORS

@@ -0,0 +1 @@
+* Arto Bendiken <arto.bendiken@gmail.com>

data/README

@@ -0,0 +1,77 @@
+Tor.rb: Onion Routing for Ruby
+==============================
+
+This is a Ruby library for interacting with the [Tor][] anonymity network.
+
+* <http://github.com/bendiken/tor-ruby>
+
+Features
+--------
+
+* Supports checking whether Tor is installed in the user's current `PATH`,
+  and if it is, returning the version number.
+* Supports querying the [Tor DNS Exit List (DNSEL)][TorDNSEL] to determine
+  whether a particular host is a Tor exit node or not.
+
+Examples
+--------
+
+    require 'rubygems'
+    require 'tor'
+
+### Checking whether Tor is installed and which version it is
+
+    Tor.available?                                     #=> true
+    Tor.version                                        #=> "0.2.1.25"
+
+### Checking whether a particular host is a Tor exit node
+
+    Tor::DNSEL.include?("208.75.57.100")               #=> true
+    Tor::DNSEL.include?("1.2.3.4")                     #=> false
+
+Documentation
+-------------
+
+* <http://cypherpunk.rubyforge.org/tor/>
+
+Dependencies
+------------
+
+* [Ruby](http://ruby-lang.org/) (>= 1.8.7) or (>= 1.8.1 with [Backports][])
+
+Installation
+------------
+
+The recommended installation method is via [RubyGems](http://rubygems.org/).
+To install the latest official release of Tor.rb, do:
+
+    % [sudo] gem install tor                 # Ruby 1.8.7+ or 1.9.x
+    % [sudo] gem install backports tor       # Ruby 1.8.1+
+
+Download
+--------
+
+To get a local working copy of the development repository, do:
+
+    % git clone git://github.com/bendiken/tor-ruby.git
+
+Alternatively, you can download the latest development version as a tarball
+as follows:
+
+    % wget http://github.com/bendiken/tor-ruby/tarball/master
+
+Author
+------
+
+* [Arto Bendiken](mailto:arto.bendiken@gmail.com) - <http://ar.to/>
+
+License
+-------
+
+Tor.rb is free and unencumbered public domain software. For more
+information, see <http://unlicense.org/> or the accompanying UNLICENSE file.
+
+[Tor]:       https://www.torproject.org/
+[TorDNSEL]:  https://www.torproject.org/tordnsel/
+[OR]:        http://en.wikipedia.org/wiki/Onion_routing
+[Backports]: http://rubygems.org/gems/backports

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/tor.rb

@@ -0,0 +1,61 @@
+if RUBY_VERSION < '1.8.7'
+  # @see http://rubygems.org/gems/backports
+  begin
+    require 'backports/1.8.7'
+  rescue LoadError
+    begin
+      require 'rubygems'
+      require 'backports/1.8.7'
+    rescue LoadError
+      abort "Tor.rb requires Ruby 1.8.7 or the Backports gem (hint: `gem install backports')."
+    end
+  end
+end
+
+##
+# @see https://www.torproject.org/
+module Tor
+  autoload :DNSEL,   'tor/dnsel'
+  autoload :VERSION, 'tor/version'
+
+  ##
+  # Returns `true` if Tor is available, `false` otherwise.
+  #
+  # @example
+  #   Tor.available?    #=> true
+  #
+  # @return [Boolean]
+  def self.available?
+    !!program_path
+  end
+
+  ##
+  # Returns the Tor version number, or `nil` if Tor is not available.
+  #
+  # @example
+  #   Tor.version       #=> "0.2.1.25"
+  #
+  # @return [String]
+  def self.version
+    if available? && `#{program_path} --version` =~ /Tor v(\d+)\.(\d+)\.(\d+)\.(\d+)/
+      [$1, $2, $3, $4].join('.')
+    end
+  end
+
+  ##
+  # Returns the path to the `tor` executable, or `nil` if the program could
+  # not be found in the user's current `PATH` environment.
+  #
+  # @example
+  #   Tor.program_path  #=> "/opt/local/bin/tor"
+  #
+  # @param  [String, #to_s] program_name
+  # @return [String]
+  def self.program_path(program_name = :tor)
+    ENV['PATH'].split(File::PATH_SEPARATOR).each do |path|
+      program_path = File.join(path, program_name.to_s)
+      return program_path if File.executable?(program_path)
+    end
+    return nil
+  end
+end

data/lib/tor/dnsel.rb

@@ -0,0 +1,148 @@
+require 'resolv' unless defined?(Resolv)
+
+module Tor
+  ##
+  # Tor DNS Exit List (DNSEL) client.
+  #
+  # Unless the target IP address and port are explicitly specified, the
+  # query will be performed using a target IP address of "8.8.8.8" and a
+  # target port of 53. These correspond to the DNS protocol port on one of
+  # the [Google Public DNS](http://code.google.com/speed/public-dns/)
+  # servers, and they are guaranteed to be reachable from Tor's default exit
+  # policy.
+  #
+  # @example Checking source IP addresses
+  #   Tor::DNSEL.include?("208.75.57.100")               #=> true
+  #   Tor::DNSEL.include?("1.2.3.4")                     #=> false
+  #
+  # @example Checking source hostnames
+  #   Tor::DNSEL.include?("ennui.lostinthenoise.net")    #=> true
+  #   Tor::DNSEL.include?("myhost.example.org")          #=> false
+  #
+  # @example Specifying an explicit target port
+  #   Tor::DNSEL.include?("208.75.57.100", :port => 80)  #=> true
+  #   Tor::DNSEL.include?("208.75.57.100", :port => 25)  #=> false
+  #
+  # @example Specifying an explicit target IP address and port
+  #   Tor::DNSEL.include?(source_addr, :addr => target_addr, :port => target_port)
+  #   Tor::DNSEL.include?("208.75.57.100", :addr => myip, :port => myport)
+  #
+  # @example Using from a Rack application
+  #   Tor::DNSEL.include?(env['REMOTE_ADDR'] || env['REMOTE_HOST'], {
+  #     :addr => env['SERVER_NAME'],
+  #     :port => env['SERVER_PORT'],
+  #   })
+  #
+  # @see https://www.torproject.org/tordnsel/
+  # @see https://trac.torproject.org/projects/tor/wiki/TheOnionRouter/TorDNSExitList
+  # @see http://gitweb.torproject.org/tor.git?a=blob_plain;hb=HEAD;f=doc/contrib/torel-design.txt
+  module DNSEL
+    RESOLVER    = Resolv::DefaultResolver unless defined?(RESOLVER)
+    TARGET_ADDR = '8.8.8.8'.freeze        unless defined?(TARGET_ADDR)     # Google Public DNS
+    TARGET_PORT = 53                      unless defined?(TARGET_PORT)     # DNS
+    DNS_SUFFIX  = 'ip-port.exitlist.torproject.org'.freeze
+
+    ##
+    # Returns `true` if the Tor DNSEL includes `host`, `false` otherwise.
+    #
+    # If the DNS server is unreachable or the DNS query times out, returns
+    # `nil` to indicate that we don't have a definitive answer one way or
+    # another.
+    #
+    # @example
+    #   Tor::DNSEL.include?("208.75.57.100")    #=> true
+    #   Tor::DNSEL.include?("1.2.3.4")          #=> false
+    #
+    # @param  [String, #to_s]          host
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [String, #to_s]  :addr ("8.8.8.8")
+    # @option options [Integer, #to_i] :port (53)
+    # @return [Boolean]
+    def self.include?(host, options = {})
+      begin
+        query(host, options) == '127.0.0.2'
+      rescue Resolv::ResolvError   # NXDOMAIN
+        false
+      rescue Resolv::ResolvTimeout
+        nil
+      rescue Errno::EHOSTUNREACH
+        nil
+      rescue Errno::EADDRNOTAVAIL
+        nil
+      end
+    end
+
+    ##
+    # Queries the Tor DNSEL for `host`, returning "172.0.0.2" if it is an
+    # exit node and raising a `Resolv::ResolvError` if it isn't.
+    #
+    # @example
+    #   Tor::DNSEL.query("208.75.57.100")       #=> "127.0.0.2"
+    #   Tor::DNSEL.query("1.2.3.4")             #=> Resolv::ResolvError
+    #
+    # @param  [String, #to_s]          host
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [String, #to_s]  :addr ("8.8.8.8")
+    # @option options [Integer, #to_i] :port (53)
+    # @return [String]
+    # @raise  [Resolv::ResolvError] for an NXDOMAIN response
+    def self.query(host, options = {})
+      getaddress(dnsname(host, options))
+    end
+
+    ##
+    # Returns the DNS name used for Tor DNSEL queries of `host`.
+    #
+    # @example
+    #   Tor::DNSEL.dnsname("1.2.3.4")           #=> "4.3.2.1.53.8.8.8.8.ip-port.exitlist.torproject.org"
+    #
+    # @param  [String, #to_s]          host
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [String, #to_s]  :addr ("8.8.8.8")
+    # @option options [Integer, #to_i] :port (53)
+    # @return [String]
+    def self.dnsname(host, options = {})
+      source_addr = getaddress(host, true)
+      target_addr = getaddress(options[:addr] || TARGET_ADDR, true)
+      target_port = options[:port] || TARGET_PORT
+      [source_addr, target_port, target_addr, DNS_SUFFIX].join('.')
+    end
+    class << self; alias_method :hostname, :dnsname; end
+
+  protected
+
+    ##
+    # Resolves `host` into an IPv4 address using Ruby's default resolver.
+    #
+    # Optionally returns the IPv4 address with its octet order reversed.
+    #
+    # @example
+    #   Tor::DNSEL.getaddress("ruby-lang.org")  #=> "221.186.184.68"
+    #   Tor::DNSEL.getaddress("1.2.3.4")        #=> "1.2.3.4"
+    #   Tor::DNSEL.getaddress("1.2.3.4", true)  #=> "4.3.2.1"
+    #
+    # @param  [String, #to_s] host
+    # @param  [Boolean]       reversed
+    # @return [String]
+    def self.getaddress(host, reversed = false)
+      host = case host.to_s
+        when Resolv::IPv6::Regex
+          raise ArgumentError.new("not an IPv4 address: #{host}")
+        when Resolv::IPv4::Regex
+          host.to_s
+        else
+          begin
+            RESOLVER.each_address(host.to_s) do |addr|
+              return addr.to_s if addr.to_s =~ Resolv::IPv4::Regex
+            end
+            raise Resolv::ResolvError.new("no address for #{host}")
+          rescue NoMethodError
+            # This is a workaround for Ruby bug #2614:
+            # @see http://redmine.ruby-lang.org/issues/show/2614
+            raise Resolv::ResolvError.new("no address for #{host}")
+          end
+      end
+      reversed ? host.split('.').reverse.join('.') : host
+    end
+  end
+end

data/lib/tor/version.rb

@@ -0,0 +1,22 @@
+module Tor
+  module VERSION
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+    EXTRA = nil
+
+    STRING = [MAJOR, MINOR, TINY, EXTRA].compact.join('.')
+
+    ##
+    # @return [String]
+    def self.to_s() STRING end
+
+    ##
+    # @return [String]
+    def self.to_str() STRING end
+
+    ##
+    # @return [Array(Integer, Integer, Integer)]
+    def self.to_a() [MAJOR, MINOR, TINY] end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification 
+name: tor
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Arto Bendiken
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-01 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 5
+        - 8
+        version: 0.5.8
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id002
+description: Tor.rb is a pure-Ruby library for interacting with the Tor anonymity network.
+email: or-talk@seul.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- AUTHORS
+- CONTRIBUTORS
+- README
+- UNLICENSE
+- VERSION
+- lib/tor/dnsel.rb
+- lib/tor/version.rb
+- lib/tor.rb
+has_rdoc: false
+homepage: http://github.com/bendiken/tor-ruby
+licenses: 
+- Public Domain
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 8
+      - 1
+      version: 1.8.1
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: 
+- Tor (>= 0.2.1.25)
+rubyforge_project: cypherpunk
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Onion routing for Ruby.
+test_files: []
+