ethernet 0.0.0 → 0.1.0

data/.project

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>ethernet</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+	</buildSpec>
+	<natures>
+	</natures>
+</projectDescription>

data/Gemfile

@@ -1,13 +1,17 @@
-source "http://rubygems.org"
+source 'http://rubygems.org'
 # Add dependencies required to use your gem here.
 # Example:
-#   gem "activesupport", ">= 2.3.5"
+#   gem 'activesupport', '>= 2.3.5'
+
+gem 'system-getifaddrs', '~> 0.1.1', :platform => :ruby,
+    :require => 'system/getifaddrs'
 
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem "rspec", "~> 2.3.0"
-  gem "bundler", "~> 1.0.0"
-  gem "jeweler", "~> 1.5.2"
-  gem "rcov", ">= 0"
+  gem 'rdoc', '~> 3.6.1'
+  gem 'rspec', '~> 2.6.0'
+  gem 'bundler', '~> 1.0.0'
+  gem 'jeweler', '~> 1.6.0'
+  gem 'rcov', '>= 0'
 end

data/Gemfile.lock

@@ -3,26 +3,30 @@ GEM
   specs:
     diff-lcs (1.1.2)
     git (1.2.5)
-    jeweler (1.5.2)
+    jeweler (1.6.0)
       bundler (~> 1.0.0)
       git (>= 1.2.5)
       rake
-    rake (0.8.7)
+    rake (0.9.0)
     rcov (0.9.9)
-    rspec (2.3.0)
-      rspec-core (~> 2.3.0)
-      rspec-expectations (~> 2.3.0)
-      rspec-mocks (~> 2.3.0)
-    rspec-core (2.3.1)
-    rspec-expectations (2.3.0)
+    rdoc (3.6.1)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.3)
+    rspec-expectations (2.6.0)
       diff-lcs (~> 1.1.2)
-    rspec-mocks (2.3.0)
+    rspec-mocks (2.6.0)
+    system-getifaddrs (0.1.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler (~> 1.0.0)
-  jeweler (~> 1.5.2)
+  jeweler (~> 1.6.0)
   rcov
-  rspec (~> 2.3.0)
+  rdoc (~> 3.6.1)
+  rspec (~> 2.6.0)
+  system-getifaddrs (~> 0.1.1)

data/README.rdoc

@@ -16,10 +16,10 @@ This project is a low-level ethernet communication rubygems library. Its initial
 
 == Author
 
+Victor Costan victor@costan.us
 HaoQi Li haoqili@mit.edu
 
 == Copyright
 
 Copyright (c) 2011 Massachusetts Institute of Technology. 
 See LICENSE.txt for further details.
-

data/Rakefile

@@ -13,16 +13,13 @@ require 'jeweler'
 Jeweler::Tasks.new do |gem|
   # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
   gem.name = "ethernet"
-  gem.homepage = "http://github.com/haoqili/ethernet"
+  gem.homepage = "http://github.com/costan/ethernet"
   gem.license = "MIT"
-  gem.summary = %Q{A ruby gem library for ethernet communication.}
-  gem.description = %Q{This project is a low-level ethernet communication rubygems library.}
-  gem.email = "haoqili@mit.edu"
-  gem.authors = ["HaoQi Li"]
-  # Include your dependencies below. Runtime dependencies are required when using your gem,
-  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
-  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
-  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+  gem.summary = %Q{Ethernet (link-layer level) sockets.}
+  gem.description = %Q{Provides a Socket-like API that bypasses TCP/IP. Useful for exotic devices and FPGA development.}
+  gem.email = "victor@costan.us"
+  gem.authors = ["Victor Costan", "HaoQi Li"]
+  # dependencies defined in Gemfile
 end
 Jeweler::RubygemsDotOrgTasks.new
 
@@ -39,7 +36,7 @@ end
 
 task :default => :spec
 
-require 'rake/rdoctask'
+require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|
   version = File.exist?('VERSION') ? File.read('VERSION') : ""
 

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.1.0

data/bin/ethernet_ping

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'ethernet' #'scratchpad'
+
+if ARGV.length < 4
+  print <<END_USAGE
+Usage: #{$0} net_interface ether_type dest_mac data
+  net_interface: name of the Ethernet interface, e.g. eth0
+  ether_type: packet type for the Ethernet II frame, in hex (2 bytes)
+  dest_mac: destination MAC for the ping packets, in hex (6 bytes)
+  data: ping packet data, in hex (0-padded to 64 bytes)
+END_USAGE
+  exit 1
+end
+ 
+interface = ARGV[0]
+ether_type = [ARGV[1]].pack('H*').unpack('n').first
+dest_mac = ARGV[2]
+data = [ARGV[3]].pack('H*')
+
+#client = Scratchpad::Ethernet::PingClient.new interface, ether_type, dest_mac
+client = Ethernet::PingClient.new interface, ether_type, dest_mac
+
+loop do
+  print "Pinging #{dest_mac}... "
+  STDOUT.flush
+  puts client.ping(data) ? "OK" : "Failed"
+  STDOUT.flush
+  sleep 1
+end

data/ethernet.gemspec

@@ -5,19 +5,21 @@
 
 Gem::Specification.new do |s|
   s.name = %q{ethernet}
-  s.version = "0.0.0"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["HaoQi Li"]
-  s.date = %q{2011-03-11}
-  s.description = %q{This project is a low-level ethernet communication rubygems library.}
-  s.email = %q{haoqili@mit.edu}
+  s.authors = [%q{Victor Costan}, %q{HaoQi Li}]
+  s.date = %q{2011-05-27}
+  s.description = %q{Provides a Socket-like API that bypasses TCP/IP. Useful for exotic devices and FPGA development.}
+  s.email = %q{victor@costan.us}
+  s.executables = [%q{ethernet_ping}]
   s.extra_rdoc_files = [
     "LICENSE.txt",
     "README.rdoc"
   ]
   s.files = [
     ".document",
+    ".project",
     ".rspec",
     "Gemfile",
     "Gemfile.lock",
@@ -25,39 +27,52 @@ Gem::Specification.new do |s|
     "README.rdoc",
     "Rakefile",
     "VERSION",
+    "bin/ethernet_ping",
     "ethernet.gemspec",
     "lib/ethernet.rb",
+    "lib/ethernet/devices.rb",
+    "lib/ethernet/frame_socket.rb",
+    "lib/ethernet/ping.rb",
+    "lib/ethernet/provisioning.rb",
+    "lib/ethernet/raw_socket_factory.rb",
+    "spec/ethernet/devices_spec.rb",
+    "spec/ethernet/frame_socket_spec.rb",
+    "spec/ethernet/raw_socket_factory_spec.rb",
     "spec/ethernet_spec.rb",
-    "spec/spec_helper.rb"
-  ]
-  s.homepage = %q{http://github.com/haoqili/ethernet}
-  s.licenses = ["MIT"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.6.2}
-  s.summary = %q{A ruby gem library for ethernet communication.}
-  s.test_files = [
-    "spec/ethernet_spec.rb",
-    "spec/spec_helper.rb"
+    "spec/spec_helper.rb",
+    "spec/support/ifconfig_cli.rb",
+    "spec/support/raw_socket_stub.rb"
   ]
+  s.homepage = %q{http://github.com/costan/ethernet}
+  s.licenses = [%q{MIT}]
+  s.require_paths = [%q{lib}]
+  s.rubygems_version = %q{1.8.4}
+  s.summary = %q{Ethernet (link-layer level) sockets.}
 
   if s.respond_to? :specification_version then
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<rspec>, ["~> 2.3.0"])
+      s.add_runtime_dependency(%q<system-getifaddrs>, ["~> 0.1.1"])
+      s.add_development_dependency(%q<rdoc>, ["~> 3.6.1"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.6.0"])
       s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.0"])
       s.add_development_dependency(%q<rcov>, [">= 0"])
     else
-      s.add_dependency(%q<rspec>, ["~> 2.3.0"])
+      s.add_dependency(%q<system-getifaddrs>, ["~> 0.1.1"])
+      s.add_dependency(%q<rdoc>, ["~> 3.6.1"])
+      s.add_dependency(%q<rspec>, ["~> 2.6.0"])
       s.add_dependency(%q<bundler>, ["~> 1.0.0"])
-      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.0"])
       s.add_dependency(%q<rcov>, [">= 0"])
     end
   else
-    s.add_dependency(%q<rspec>, ["~> 2.3.0"])
+    s.add_dependency(%q<system-getifaddrs>, ["~> 0.1.1"])
+    s.add_dependency(%q<rdoc>, ["~> 3.6.1"])
+    s.add_dependency(%q<rspec>, ["~> 2.6.0"])
     s.add_dependency(%q<bundler>, ["~> 1.0.0"])
-    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.0"])
     s.add_dependency(%q<rcov>, [">= 0"])
   end
 end

data/lib/ethernet/devices.rb

@@ -0,0 +1,41 @@
+# OS-dependent gem includes.
+case RUBY_PLATFORM
+when /linux/
+when /darwin/
+  require 'system/getifaddrs'
+end
+
+# :nodoc: namespace
+module Ethernet
+
+# Information about the available Ethernet devices.
+module Devices
+  # An array of device names for the machine's Ethernet devices.
+  def self.all
+    case RUBY_PLATFORM
+    when /linux/, /darwin/
+      System.get_ifaddrs.keys.map(&:to_s)
+    else
+      raise "Unsupported platform #{RUBY_PLATFORM}"
+    end
+  end
+  
+  # The MAC address for an Ethernet device.
+  #
+  # Args:
+  #   eth_device:: device name for the Ethernet card, e.g. 'eth0'
+  def self.mac(eth_device)
+    case RUBY_PLATFORM
+    when /linux/
+      # /usr/include/net/if.h, structure ifreq
+      ifreq = [eth_device].pack 'a32'
+      # 0x8927 is SIOCGIFHWADDR in /usr/include/bits/ioctls.h
+      RawSocketFactory.socket.ioctl 0x8927, ifreq
+      ifreq[18, 6]
+    else
+      raise "Unsupported platform #{RUBY_PLATFORM}"
+    end
+  end
+end  # class Ethernet::Devices
+
+end  # namespace Ethernet

data/lib/ethernet/frame_socket.rb

@@ -0,0 +1,122 @@
+# :nodoc: namespace
+module Ethernet
+
+# Wraps an Ethernet socket and abstracts away the Ethernet II frame.
+class FrameSocket
+  # Creates a wrapper around a raw Ethernet socket.
+  #
+  # Args:
+  #   raw_socket_or_device:: a raw Ethernet socket or a string containing an
+  #                          Ethernet device name
+  #   ether_type:: 2-byte Ethernet packet type number
+  #   mac_address:: 6-byte MAC address for the Ethernet socket (optional if
+  #                 raw_socket_or_device is an Ethernet device name)
+  #
+  # Raises:
+  #   RuntimeError:: if mac isn't exactly 6-bytes long
+  def initialize(raw_socket_or_device, ether_type, mac_address = nil)
+    check_mac mac_address if mac_address
+    
+    if raw_socket_or_device.respond_to? :to_str
+      @source_mac = mac_address || Ethernet::Devices.mac(raw_socket_or_device)
+      @socket = RawSocketFactory.socket raw_socket_or_device, ether_type
+    else
+      raise 'MAC address needed with raw socket' unless mac_address
+      @source_mac = mac_address.dup
+      @socket = raw_socket_or_device
+    end
+    
+    @dest_mac = nil
+    @ether_type = [ether_type].pack('n')
+  end
+
+  # Sets the destination MAC address for future calls to send.
+  #
+  # Args:
+  #   mac:: 6-byte MAC address for the Ethernet socket
+  #
+  # Raises:
+  #   RuntimeError:: if mac isn't exactly 6-bytes long
+  def connect(mac_address)
+    check_mac mac_address
+    @dest_mac = mac_address
+  end
+  
+  # Closes the underlying socket.
+  def close
+    @socket.close
+  end
+  
+  # Sends an Ethernet II frame.
+  #
+  # Args:
+  #   data:: the data bytes to be sent
+  #
+  # Raises:
+  #   RuntimeError:: if connect wasn' previously called
+  def send(data, send_flags = 0)
+    raise "Not connected" unless @dest_mac
+    send_to @dest_mac, data, send_flags
+  end
+  
+  # Sends an Ethernet II frame.
+  #
+  # Args:
+  #   mac_address:: the destination MAC address
+  #   data:: the data bytes to be sent
+  #
+  # Raises:
+  #   RuntimeError:: if connect wasn' previously called
+  def send_to(mac_address, data, send_flags = 0)
+    check_mac mac_address
+
+    padding = (data.length < 46) ? "\0" * (46 - data.length) : ''
+    packet = [mac_address, @source_mac, @ether_type, data, padding].join
+    @socket.send packet, send_flags
+  end
+  
+  # Receives an Ethernet II frame.
+  #
+  # Args:
+  #   buffer_size:: optional maximum packet size argument passed to the raw
+  #                 socket's recv method
+  #
+  # Returns the data and the source MAC address in the frame.
+  #
+  # This will discard incoming frames that don't match the MAC address that the
+  # socket is connected to, or the Ethernet packet type.
+  def recv(buffer_size = 8192)
+    raise "Not connected" unless @dest_mac
+    loop do
+      data, mac_address = recv_from buffer_size
+      return data if @dest_mac == mac_address
+    end
+  end
+  
+  # Receives an Ethernet II frame.
+  #
+  # Args:
+  #   buffer_size:: optional maximum packet size argument passed to the raw
+  #                 socket's recv method
+  #
+  # Returns the data in the frame.
+  #
+  # This will discard incoming frames that don't match the MAC address that the
+  # socket is connected to, or the Ethernet packet type.
+  def recv_from(buffer_size = 8192)
+    loop do
+      packet = @socket.recv buffer_size
+      next unless packet[12, 2] == @ether_type
+      next unless packet[0, 6] == @source_mac
+      return packet[14..-1], packet[6, 6]
+    end
+  end
+  
+  # Raises an exception if the given MAC address is invalid.
+  def check_mac(mac_address)
+    raise "Invalid MAC address" unless mac_address.length == 6
+  end
+  private :check_mac
+end  # class Ethernet::FrameSocket
+
+end  # namespace Ethernet

data/lib/ethernet/ping.rb

@@ -0,0 +1,89 @@
+# TODO(pwnall): move to separate gem
+
+
+# copied from victor's scratchpad/lib/scratchpad/ethernet/ping.rb
+# changes see raw_socket.rb
+# :%s/if_name/eth_device/g
+# .get_interface_mac() --> .mac()
+# Ethernet.socket --> Ethernet::RawSocket.socket
+# Ethernet.mac --> Ethernet::RawSocket.mac
+
+# :nodoc: namespace # module Scratchpad
+
+# :nodoc: namespace
+module Ethernet
+
+# Responder for ping utility using raw Ethernet sockets.
+class PingServer
+  module Connection
+    def receive_data(packet)
+      source_mac = packet[0, 6].unpack('H*')
+      dest_mac = packet[6, 6].unpack('H*')
+      ether_type = packet[12, 2].unpack('H*')
+      
+      puts "Src: #{source_mac} Dst: #{dest_mac} Eth: #{ether_type}\n"
+      puts packet[14..-1].unpack('H*')
+      
+      # Exchange the source and destination ARP addresses.
+      packet[0, 6], packet[6, 6] = packet[6, 6], packet[0, 6]
+      send_data packet
+    end
+  end
+
+  class ConnectionWrapper
+    include Connection
+    
+    def initialize(socket)
+      @socket = socket
+    end
+    
+    def send_data(data)
+      @socket.send data, 0
+    end
+  end
+  
+  def run
+    connection = ConnectionWrapper.new @socket
+    loop do
+      packet = @socket.recv 65536
+      connection.receive_data packet
+    end
+  end
+  
+  def initialize(eth_device, ether_type)
+    @socket = Ethernet::RawSocket.socket eth_device, ether_type
+  end
+end  # module Ethernet::PingServer
+  
+# Ping utility 
+class PingClient
+  def initialize(eth_device, ether_type, destination_mac)
+    @socket = Ethernet::RawSocket.socket eth_device, ether_type
+    @source_mac = [Ethernet::RawSocket.mac(eth_device).unpack('H*').first].pack('H*')[0, 6]
+    @dest_mac = [destination_mac].pack('H*')[0, 6]
+    @ether_type = [ether_type].pack('n')    
+  end
+  
+  attr_reader :socket
+  attr_reader :source_mac
+  attr_reader :dest_mac
+  
+  # Pings over raw Ethernet sockets.
+  #
+  # Returns true if the ping receives a response, false otherwise.
+  def ping(data, timeout = 1)
+    data = data.clone
+    # Pad data to have at least 64 bytes.
+    data += "\0" * (64 - data.length) if data.length < 64
+ 
+    ping_packet = @dest_mac + @source_mac + @ether_type + data
+    @socket.send ping_packet, 0
+
+    response_packet = @source_mac + @dest_mac + @ether_type + data
+    response = @socket.recv response_packet.length * 2
+    
+    response == response_packet
+  end
+end  # module Ethernet::PingClient
+
+end  # namespace Ethernet

data/lib/ethernet/provisioning.rb

@@ -0,0 +1,44 @@
+require 'rbconfig'
+
+
+# :nodoc: namespace
+module Ethernet
+
+# Setup issues such as assigning permissions for Ethernet-level transmission.
+module Provisioning
+  # Allow non-root users to create low-level Ethernet sockets.
+  #
+  # This is a security risk, because Ethernet sockets can be used to spy on all
+  # traffic on the machine's network. This should not be called on production
+  # machines.
+  #
+  # Returns true for success, false otherwise. If the call fails, it is most
+  # likely because it is not run by root / Administrator.
+  def self.usermode_sockets
+    case RUBY_PLATFORM
+    when /darwin/
+      return false unless Kernel.system("chmod o+r /dev/bpf*")
+    when /linux/
+      ruby = File.join Config::CONFIG['bindir'],
+                       Config::CONFIG['ruby_install_name']
+      unless Kernel.system("setcap 'CAP_NET_RAW+eip CAP_NET_ADMIN+eip' #{ruby}")
+        return false
+      end
+      
+      # Try to enable Wireshark packet capture for debugging.
+      # No big deal if this fails.
+      dumpcap = '/usr/bin/dumpcap'
+      if File.exist? dumpcap
+        Kernel.system("setcap 'CAP_NET_RAW+eip CAP_NET_ADMIN+eip' #{dumpcap}")
+      end
+    when /win/
+      # NOTE: this might not work
+      return false unless Kernel.system("sc config npf start= auto")
+    else
+      raise "Unsupported platform #{RUBY_PLATFORM}"
+    end
+    true
+  end
+end  # class Ethernet::Provisioning
+
+end  # namespace Ethernet

data/lib/ethernet/raw_socket_factory.rb

@@ -0,0 +1,91 @@
+require 'socket'
+
+case RUBY_PLATFORM
+when /linux/
+  require 'system/getifaddrs' # for listing
+end
+
+# :nodoc: namespace
+module Ethernet
+
+# Low-level socket creation functionality.
+module RawSocketFactory
+  # A raw socket sends and receives raw Ethernet frames.
+  #
+  # Args:
+  #   eth_device:: device name for the Ethernet card, e.g. 'eth0'
+  #   ether_type:: only receive Ethernet frames with this protocol number
+  def self.socket(eth_device = nil, ether_type = nil)
+    ether_type ||= all_ethernet_protocols
+    socket = Socket.new raw_address_family, Socket::SOCK_RAW, htons(ether_type)
+    socket.setsockopt Socket::SOL_SOCKET, Socket::SO_BROADCAST, true
+    set_socket_eth_device(socket, eth_device, ether_type) if eth_device
+    socket
+  end
+  
+  class <<self
+    # Sets the Ethernet interface and protocol type for a socket.
+    def set_socket_eth_device(socket, eth_device, ether_type)
+      case RUBY_PLATFORM
+      when /linux/
+        if_number = get_interface_number eth_device
+        # struct sockaddr_ll in /usr/include/linux/if_packet.h
+        socket_address = [raw_address_family, htons(ether_type), if_number,
+                          0xFFFF, 0, 0, ""].pack 'SSISCCa8'
+        socket.bind socket_address
+      else
+        raise "Unsupported platform #{RUBY_PLATFORM}"
+      end
+      socket
+    end
+    private :set_socket_eth_device
+    
+    # The interface number for an Ethernet interface.
+    def get_interface_number(eth_device)
+      case RUBY_PLATFORM
+      when /linux/
+        # /usr/include/net/if.h, structure ifreq
+        ifreq = [eth_device].pack 'a32'
+        # 0x8933 is SIOCGIFINDEX in /usr/include/bits/ioctls.h
+        socket.ioctl 0x8933, ifreq
+        ifreq[16, 4].unpack('I').first
+      else
+        raise "Unsupported platform #{RUBY_PLATFORM}"
+      end
+    end
+    private :get_interface_number
+    
+    # The protocol number for listening to all ethernet protocols.
+    def all_ethernet_protocols
+      case RUBY_PLATFORM
+      when /linux/
+        3  # cat /usr/include/linux/if_ether.h | grep ETH_P_ALL
+      else
+        raise "Unsupported platform #{RUBY_PLATFORM}"
+      end
+    end
+    private :all_ethernet_protocols
+    
+    # The AF / PF number for raw sockets.
+    def raw_address_family
+      case RUBY_PLATFORM
+      when /linux/
+        17  # cat /usr/include/bits/socket.h | grep PF_PACKET
+      when /darwin/
+        18  # cat /usr/include/sys/socket.h | grep AF_LINK
+      else
+        raise "Unsupported platform #{RUBY_PLATFORM}"
+      end
+    end
+    private :raw_address_family
+  
+    # Converts a 16-bit integer from host-order to network-order.
+    def htons(short_integer)
+      [short_integer].pack('n').unpack('S').first
+    end
+    private :htons
+  end
+end  # module Ethernet::RawSocketFactory
+
+end  # namespace Ethernet
+

data/lib/ethernet.rb

@@ -0,0 +1,48 @@
+# Facade methods for the library.
+#
+# See the inner classes for more advanced functionality.
+module Ethernet
+  # Hash mapping Ethernet device names to their MAC addresses.
+  def self.devices
+    Hash[Ethernet::Devices.all.map { |dev| [dev, Ethernet::Devices.mac(dev)] }]
+  end
+
+  # Ethernet socket that abstracts away frames.
+  #
+  # Args:
+  #   eth_device:: device name for the Ethernet card, e.g. 'eth0'
+  #   ether_type:: 2-byte Ethernet packet type number
+  def self.socket(eth_device, ether_type)
+    Ethernet::FrameSocket.new eth_device, ether_type
+  end
+
+  # Allow non-root users to create low-level Ethernet sockets.
+  #
+  # This is a security risk, because Ethernet sockets can be used to spy on all
+  # traffic on the machine's network. This should not be called on production
+  # machines.
+  #
+  # Returns true for success, false otherwise. If the call fails, it is most
+  # likely because it is not run by root / Administrator.
+  def self.provision
+    Ethernet::Provisioning.usermode_sockets
+  end
+  
+  # A socket that sends and receives raw Ethernet frames.
+  #
+  # Args:
+  #   eth_device:: device name for the Ethernet card, e.g. 'eth0'
+  #   ether_type:: only receive Ethernet frames with this protocol number
+  def self.raw_socket(eth_device = nil, ether_type = nil)
+    Ethernet::RawSocketFactory.socket eth_device, ether_type
+  end
+end
+
+require 'ethernet/devices.rb'
+require 'ethernet/frame_socket.rb'
+require 'ethernet/provisioning.rb'
+require 'ethernet/raw_socket_factory.rb'
+
+
+# TODO(pwnall): move to separate gem
+require 'ethernet/ping.rb'

data/spec/ethernet/devices_spec.rb

@@ -0,0 +1,39 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe Ethernet::Devices do
+  let(:golden_devices) { IfconfigCli.run }
+  let(:golden_active_devices) do
+    golden_devices.keys.select { |device| golden_devices[device][:active] }
+  end
+  
+  describe 'testing environment' do
+    it 'should have at least one active ethernet device' do
+      golden_active_devices.should have_at_least(1).device
+    end
+  end
+  
+  describe 'all' do
+    let(:devices) { Ethernet::Devices.all }
+    
+    it "should find active ethernet devices" do
+      golden_active_devices.each do |device|
+        devices.should include(device)
+      end
+    end
+  end
+  
+  let(:eth_device) { IfconfigCli.live_device }
+  let(:mac) { Ethernet::Devices.mac eth_device }
+  
+  describe 'mac' do
+    let(:golden_mac) { [golden_devices[eth_device][:mac]].pack('H*') }
+    
+    it 'should have 6 bytes' do
+      mac.length.should == 6
+    end
+    
+    it 'should match ifconfig output' do
+      mac.should == golden_mac
+    end
+  end
+end

data/spec/ethernet/frame_socket_spec.rb

@@ -0,0 +1,102 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe Ethernet::FrameSocket do
+  let(:eth_device) { IfconfigCli.live_device }
+  let(:eth_type) { 0x0800 }
+  let(:mac) { Ethernet::Devices.mac eth_device }
+  let(:dest_mac) { "\x00\x11\x22\x33\x44\x55" }
+  let(:bcast_mac) { "\xff" * 6 }
+  
+  shared_examples_for 'a real socket' do
+    it 'should output a packet' do
+      @socket.send_to dest_mac, "\r\n"
+    end
+
+    it 'should receive some network noise' do
+      @socket.recv_from.first.should_not be_empty
+    end
+  end
+
+  describe 'on eth0' do
+    before { @socket = Ethernet::FrameSocket.new eth_device, eth_type }
+    after { @socket.close }
+
+    it_should_behave_like 'a real socket'
+  end
+  
+  describe 'from raw socket' do
+    before do
+      raw_socket = Ethernet::RawSocketFactory.socket eth_device, eth_type
+      @socket = Ethernet::FrameSocket.new raw_socket, eth_type, mac
+    end
+    after { @socket.close }
+
+    it_should_behave_like 'a real socket'
+  end
+  
+  describe 'stubbed' do
+    let(:socket_stub) do
+      RawSocketStub.new([
+        [mac, dest_mac, "\x88\xB7", 'Wrong Ethernet type'].join,
+        [bcast_mac, dest_mac, [eth_type].pack('n'), 'Wrong dest MAC'].join,
+        [mac, bcast_mac, [eth_type].pack('n'), 'Bcast'].join,
+        [mac, dest_mac, [eth_type].pack('n'), 'Correct'].join,
+      ])
+    end
+    let(:socket) { Ethernet::FrameSocket.new socket_stub, eth_type, mac }
+    
+    shared_examples_for 'after a small send call' do
+      it 'should send a single packet' do
+        socket_stub.sends.length.should == 1
+      end
+      it 'should pad the packet' do
+        socket_stub.sends.first.length.should == 60
+      end
+      it 'should assemble packet correctly in send' do
+        gold = [dest_mac, mac, [eth_type].pack('n'), 'Send data'].join
+        socket_stub.sends.first[0, gold.length].should == gold
+      end
+    end
+    
+    describe 'send_to' do
+      before { socket.send_to dest_mac, 'Send data' }
+      it_should_behave_like 'after a small send call'
+    end
+    
+    describe 'recv_from' do
+      it 'should filter down to the correct packet' do
+        socket.recv_from.should == ['Bcast', bcast_mac]
+      end
+    end
+    
+    describe 'unconnected' do
+      it 'should complain in recv' do
+        lambda { socket.recv }.should raise_error(RuntimeError)
+      end
+
+      it 'should complain in send' do
+        lambda { socket.send 'Send data' }.should raise_error(RuntimeError)
+      end
+    end
+    
+    describe 'connected' do
+      before { socket.connect dest_mac }
+      
+      describe 'send' do
+        before { socket.send 'Send data' }
+        it_should_behave_like 'after a small send call'
+      end
+      
+      describe 'recv' do
+        it 'should filter down to the correct packet' do
+          socket.recv.should == 'Correct'
+        end
+      end
+    end
+    
+    it 'should delegate close' do
+      socket_stub.should_receive(:close).once
+      socket.close
+    end
+  end
+end

data/spec/ethernet/raw_socket_factory_spec.rb

@@ -0,0 +1,26 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe Ethernet::RawSocketFactory do
+  let(:eth_device) { IfconfigCli.live_device }
+  let(:mac) { Ethernet::Devices.mac eth_device }
+  
+  describe 'socket' do
+    let(:eth_type) { 0x88B7 }
+    
+    before { @socket = Ethernet::RawSocketFactory.socket eth_device }
+    after { @socket.close }
+    
+    it 'should be able to receive data' do
+      @socket.should respond_to(:recv)
+    end
+    
+    it 'should output a packet' do
+      packet = [mac, mac, [eth_type].pack('n'), "\r\n" * 32].join
+      @socket.send packet, 0
+    end
+
+    it 'should receive some network noise' do
+      @socket.recv(8192).should_not be_empty
+    end
+  end
+end

data/spec/ethernet_spec.rb

@@ -1,7 +1,45 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
-describe "Ethernet" do
-  it "fails" do
-    fail "hey buddy, you should probably rename this file and start specing for real"
+describe Ethernet do
+  describe 'provision' do
+    it 'delegates to Provisioning' do
+      Ethernet::Provisioning.should_receive(:usermode_sockets).and_return(:yay)
+      Ethernet.provision.should == :yay
+    end
+  end
+
+  describe 'devices' do
+    it 'delegates to Devices' do
+      Ethernet::Devices.should_receive(:all).and_return(['yay'])
+      Ethernet::Devices.should_receive(:mac).with('yay').and_return('42')
+      golden = { 'yay' => '42' }
+      Ethernet.devices.should == golden
+    end
+    
+    let (:devices) { Ethernet.devices }
+    
+    it 'contains at least one device' do
+      devices.keys.should have_at_least(1).name
+    end
+
+    it 'has a MAC for the first device' do
+      devices[devices.keys.first].length.should == 6
+    end
+  end
+  
+  describe 'socket' do
+    it 'delegates to FrameSocket' do
+      Ethernet::FrameSocket.should_receive(:new).with('yay', 1234).
+                            and_return(:yay)
+      Ethernet.socket('yay', 1234).should == :yay
+    end
+  end
+
+  describe 'raw_socket' do
+    it 'delegates to RawSocketFactory' do
+      Ethernet::RawSocketFactory.should_receive(:socket).with('yay', 1234).
+                            and_return(:yay)
+      Ethernet.raw_socket('yay', 1234).should == :yay
+    end
   end
 end

data/spec/support/ifconfig_cli.rb

@@ -0,0 +1,37 @@
+# Wraps ifconfig calls useful for testing.
+module IfconfigCli
+  # Runs ifconfig and parses its output.
+  def self.run
+    case RUBY_PLATFORM
+    when /win/
+    else
+      output = `ifconfig -a`
+      info_blocks = output.split /\n(?=\w)/ 
+      Hash[info_blocks.map { |i|
+        name = i.split(' ', 2).first
+        mac = if match = /hwaddr\s([0-9a-f:]+)\s/i.match(i)
+          # Linux ifconfig output.
+          match[1].gsub(':', '').downcase
+        elsif match = /ether\s([0-9a-f:]+)\s/i.match(i)
+          # OSX ifconfig output.
+          match[1].gsub(':', '').downcase
+        elsif match = /\s(([0-9a-f]{2}:){5}[0-9a-f]{2})\s/i.match(i)
+          # First thing that looks like a MAC address.
+          match[1].gsub(':', '').downcase
+        else
+          nil
+        end
+        active = /inet\s/.match(i) ? true : false
+        [name, { :mac => mac, :active => active }]
+      }]
+    end
+  end
+  
+  # The name of the first active Ethernet device.
+  #
+  # The return value will most likely be eth0 on Linux and en0 on OSX.
+  def self.live_device
+    run_result = run
+    run_result.keys.sort.find { |device| run_result[device][:active] }
+  end
+end

data/spec/support/raw_socket_stub.rb

@@ -0,0 +1,23 @@
+class RawSocketStub
+  def initialize(recv_data)
+    @packets = recv_data
+    @sends = []
+  end
+  
+  def recv(buffer_size)
+    raise 'recv called too many times' if @packets.empty?
+    @packets.shift
+  end
+  
+  def send(data, flags)
+    raise 'Weird flags' if flags != 0
+    @sends << data
+  end
+  
+  def close
+    @packets = nil
+    @sends = nil
+  end
+
+  attr_reader :sends
+end

metadata

@@ -1,66 +1,121 @@
 --- !ruby/object:Gem::Specification 
 name: ethernet
 version: !ruby/object:Gem::Version 
+  hash: 27
   prerelease: 
-  version: 0.0.0
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
 platform: ruby
 authors: 
+- Victor Costan
 - HaoQi Li
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2011-03-11 00:00:00 -05:00
-default_executable: 
+date: 2011-05-27 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  type: :runtime
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        version: 2.3.0
-  type: :development
+        hash: 25
+        segments: 
+        - 0
+        - 1
+        - 1
+        version: 0.1.1
   prerelease: false
   version_requirements: *id001
+  name: system-getifaddrs
 - !ruby/object:Gem::Dependency 
-  name: bundler
+  type: :development
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        version: 1.0.0
-  type: :development
+        hash: 29
+        segments: 
+        - 3
+        - 6
+        - 1
+        version: 3.6.1
   prerelease: false
   version_requirements: *id002
+  name: rdoc
 - !ruby/object:Gem::Dependency 
-  name: jeweler
+  type: :development
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        version: 1.5.2
-  type: :development
+        hash: 23
+        segments: 
+        - 2
+        - 6
+        - 0
+        version: 2.6.0
   prerelease: false
   version_requirements: *id003
+  name: rspec
 - !ruby/object:Gem::Dependency 
-  name: rcov
+  type: :development
   requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  prerelease: false
+  version_requirements: *id004
+  name: bundler
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 1
+        - 6
+        - 0
+        version: 1.6.0
+  prerelease: false
+  version_requirements: *id005
+  name: jeweler
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
-  type: :development
   prerelease: false
-  version_requirements: *id004
-description: This project is a low-level ethernet communication rubygems library.
-email: haoqili@mit.edu
-executables: []
-
+  version_requirements: *id006
+  name: rcov
+description: Provides a Socket-like API that bypasses TCP/IP. Useful for exotic devices and FPGA development.
+email: victor@costan.us
+executables: 
+- ethernet_ping
 extensions: []
 
 extra_rdoc_files: 
@@ -68,6 +123,7 @@ extra_rdoc_files:
 - README.rdoc
 files: 
 - .document
+- .project
 - .rspec
 - Gemfile
 - Gemfile.lock
@@ -75,12 +131,22 @@ files:
 - README.rdoc
 - Rakefile
 - VERSION
+- bin/ethernet_ping
 - ethernet.gemspec
 - lib/ethernet.rb
+- lib/ethernet/devices.rb
+- lib/ethernet/frame_socket.rb
+- lib/ethernet/ping.rb
+- lib/ethernet/provisioning.rb
+- lib/ethernet/raw_socket_factory.rb
+- spec/ethernet/devices_spec.rb
+- spec/ethernet/frame_socket_spec.rb
+- spec/ethernet/raw_socket_factory_spec.rb
 - spec/ethernet_spec.rb
 - spec/spec_helper.rb
-has_rdoc: true
-homepage: http://github.com/haoqili/ethernet
+- spec/support/ifconfig_cli.rb
+- spec/support/raw_socket_stub.rb
+homepage: http://github.com/costan/ethernet
 licenses: 
 - MIT
 post_install_message: 
@@ -93,7 +159,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -231959181
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -102,14 +168,16 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.4
 signing_key: 
 specification_version: 3
-summary: A ruby gem library for ethernet communication.
-test_files: 
-- spec/ethernet_spec.rb
-- spec/spec_helper.rb
+summary: Ethernet (link-layer level) sockets.
+test_files: []
+