ffi-pcap 0.2.0

data/lib/ffi/pcap/packet_header.rb

@@ -0,0 +1,24 @@
+module FFI
+module PCap
+  # Generic per-packet information, as supplied by libpcap. This structure
+  # is used to track only the libpcap header and just contains the timestamp
+  # and length information used by libpcap.
+  #
+  # See pcap_pkthdr struct in pcap.h
+  class PacketHeader < FFI::Struct
+    include FFI::DRY::StructHelper
+
+    dsl_layout do
+      struct :ts,      ::FFI::PCap::TimeVal,     :desc => 'time stamp'
+      field  :caplen,  :bpf_uint32, :desc => 'length of portion present'
+      field  :len,     :bpf_uint32, :desc => 'length of packet (off wire)'
+    end
+
+    alias timestamp ts
+    alias captured caplen
+    alias length len
+
+  end
+
+end
+end

data/lib/ffi/pcap/pcap.rb

@@ -0,0 +1,252 @@
+require 'enumerator'
+
+module FFI
+module PCap
+  DEFAULT_SNAPLEN = 65535  # Default snapshot length for packets
+
+  attach_function :pcap_lookupdev, [:pointer], :string
+
+  # Find the default device on which to capture.
+  # 
+  # @return [String]
+  #   Name of default device
+  #
+  # @raise [LibError]
+  #   On failure, an exception is raised with the relevant error 
+  #   message from libpcap.
+  #
+  def PCap.lookupdev
+    e = ErrorBuffer.create()
+    unless name = FFI::PCap.pcap_lookupdev(e)
+      raise(LibError, "pcap_lookupdev(): #{e.to_s}")
+    end
+    return name
+  end
+
+
+  attach_function :pcap_lookupnet, [:string, :pointer, :pointer, :pointer], :int
+
+  # Determine the IPv4 network number and mask relevant with a network 
+  # device.
+  # 
+  # @param [String] device
+  #   The name of the device to look up.
+  #
+  # @yield [netp, maskp]
+  #
+  # @yieldparam [FFI::MemoryPointer] netp
+  #   A pointer to the network return value.
+  #
+  # @yieldparam [FFI::MemoryPointer] maskp
+  #   A pointer to the netmask return value.
+  #
+  # @return [nil, String] 
+  #   The IPv4 network number and mask presented as "n.n.n.n/m.m.m.m".
+  #   nil is returned when a block is specified.
+  #
+  # @raise [LibError]
+  #   On failure, an exception is raised with the relevant error message 
+  #   from libpcap. 
+  #
+  def PCap.lookupnet(device)
+    netp  = FFI::MemoryPointer.new(find_type(:bpf_uint32))
+    maskp = FFI::MemoryPointer.new(find_type(:bpf_uint32))
+    errbuf = ErrorBuffer.create()
+    unless FFI::PCap.pcap_lookupnet(device, netp, maskp, errbuf) == 0
+      raise(LibError, "pcap_lookupnet(): #{errbuf.to_s}")
+    end
+    if block_given?
+      yield(netp, maskp)
+    else
+      return( netp.get_array_of_uchar(0,4).join('.') << "/" <<
+              maskp.get_array_of_uchar(0,4).join('.') )
+    end
+  end
+  
+
+  # Opens a new Live device for capturing from the network. See Live.new()
+  # for arguments.
+  #
+  # If passed a block, the block is passed to Live.new() and the Live
+  # object is closed after completion of the block
+  def PCap.open_live(opts={},&block)
+    ret = Live.new(opts, &block)
+    return block_given? ? ret.close : ret
+  end
+
+
+  # Opens a new Dead pcap interface for compiling filters or opening
+  # a capture for output. See Dead.new() for arguments.
+  def PCap.open_dead(opts={}, &block)
+    ret = Dead.new(opts, &block)
+    return block_given? ? ret.close : ret
+  end
+
+
+  # Opens a saved capture file for reading. See Offline.new for arguments.
+  def PCap.open_offline(path, opts={}, &block)
+    ret = Offline.new(path, opts={}, &block)
+    return block_given? ? ret.close : ret
+  end
+
+  # Same as open_offline
+  def PCap.open_file(path, opts={}, &block)
+    open_offline(path, opts, &block)
+  end
+
+  attach_function :pcap_findalldevs, [:pointer, :pointer], :int
+  attach_function :pcap_freealldevs, [Interface], :void
+
+  # List all capture devices and yield them each to a block
+  #
+  # @yield [dev]
+  #
+  # @yieldparam [Interface] dev
+  #   An Interface structure for each device.
+  #
+  # @return [nil]
+  #
+  # @raise [LibError]
+  #   On failure, an exception is raised with the relevant error 
+  #   message from libpcap.
+  #
+  def PCap.each_device
+    devices = ::FFI::MemoryPointer.new(:pointer)
+    errbuf = ErrorBuffer.create()
+
+    FFI::PCap.pcap_findalldevs(devices, errbuf)
+    node = devices.get_pointer(0)
+
+    if node.null?
+      raise(LibError, "pcap_findalldevs(): #{errbuf.to_s}")
+    end
+
+    device = Interface.new(node)
+
+    while device
+      yield(device)
+      device = device.next
+    end
+
+    FFI::PCap.pcap_freealldevs(node)
+    return nil
+  end
+
+
+  # Returns an array of device name and network/netmask pairs for
+  # each interface found on the system.
+  #
+  # If an interface does not have an address assigned, its network/netmask
+  # value is returned as a nil value.
+  def PCap.dump_devices
+    FFI::PCap.enum_for(:each_device).map do |dev| 
+      net = begin; FFI::PCap.lookupnet(dev.name); rescue LibError; end
+      [dev.name, net]
+    end
+  end
+
+
+  # Returns an array of device names for each interface found on the system.
+  def PCap.device_names
+    FFI::PCap.enum_for(:each_device).map {|dev| dev.name }
+  end
+
+  attach_function :pcap_lib_version, [], :string
+
+
+  # Get the version information for libpcap.
+  #
+  # @return [String]
+  #  Information about the version of the libpcap library being used; 
+  #  note that it  contains more information than just a version number.
+  #   
+  def PCap.lib_version
+    FFI::PCap.pcap_lib_version
+  end
+
+
+  # Extract just the version number from the lib_version string.
+  #
+  # @return [String]
+  #  Version number.
+  #   
+  def PCap.lib_version_number
+    if lib_version() =~ /libpcap version (\d+\.\d+.\d+)/
+      return $1
+    end
+  end
+
+
+  # Unix Only:
+  begin
+
+    attach_function :pcap_get_selectable_fd, [:pcap_t], :int
+
+
+    # Drops privileges back to the uid of the SUDO_USER environment 
+    # variable.
+    #
+    # Only available on Unix.
+    #
+    # This is useful for the paranoid when sudo is used to run a 
+    # ruby pcap program as root.
+    #
+    # This method can generally be called right after a call to 
+    # open_live() has returned a pcap handle or another privileged
+    # call has completed. Note, however, that once privileges are 
+    # dropped, pcap functions that a require higher privilege will 
+    # no longer work.
+    #
+    # @raise [StandardError]
+    #   An error is raised if privileges cannot be dropped for 
+    #   some reason. This may be because the SUDO_USER environment 
+    #   variable is not set, because we already have a lower
+    #   privilige and the SUDO_USER id is not the current uid,
+    #   or because the SUDO_USER environment variable is not
+    #   a valid user.
+    #
+    def PCap.drop_sudo_privs
+      if ENV["SUDO_USER"] and pwent=Etc.getpwnam(ENV["SUDO_USER"])
+        Process::Sys.setgid(pwent.gid) 
+        Process::Sys.setegid(pwent.gid) 
+        Process::Sys.setuid(pwent.uid)
+        Process::Sys.seteuid(pwent.uid)
+        return true if ( 
+          Process::Sys.getuid  == pwent.uid and 
+          Process::Sys.geteuid == pwent.uid and 
+          Process::Sys.getgid  == pwent.gid and 
+          Process::Sys.getegid == pwent.gid )
+      end
+      raise(StandardError, "Unable to drop privileges")
+    end
+
+  rescue FFI::NotFoundError
+    $pcap_not_unix=true
+  end
+
+  # Win32 only:
+  begin
+    attach_function :pcap_setbuff, [:pcap_t, :int], :int
+    attach_function :pcap_setmode, [:pcap_t, :pcap_w32_modes_enum], :int
+    attach_function :pcap_setmintocopy, [:pcap_t, :int], :int
+  rescue FFI::NotFoundError
+    $pcap_not_win32=true
+  end if $pcap_not_unix
+
+  # MSDOS only???:
+  begin
+    attach_function :pcap_stats_ex, [:pcap_t, StatEx], :int
+    attach_function :pcap_set_wait, [:pcap_t, :pointer, :int], :void
+    attach_function :pcap_mac_packets, [], :ulong
+  rescue FFI::NotFoundError
+  end if $pcap_not_win32
+
+
+  #### XXX not sure if we even want FILE io stuff yet (or ever).
+
+  #attach_function :pcap_fopen_offline, [:FILE, :pointer], :pcap_t
+  #attach_function :pcap_file, [:pcap_t], :FILE
+  #attach_function :pcap_dump_fopen, [:pcap_t, :FILE], :pcap_dumper_t
+  #attach_function :pcap_fileno, [:pcap_t], :int
+end
+end

data/lib/ffi/pcap/stat.rb

@@ -0,0 +1,57 @@
+module FFI
+module PCap
+  # As returned by pcap_stats()
+  #
+  # See pcap_stat struct in pcap.h.
+  class Stat < FFI::Struct
+    include FFI::DRY::StructHelper
+
+    dsl_layout do
+      field :ps_recv,   :uint, :desc => "number of packets received"
+      field :ps_drop,   :uint, :desc => "numer of packets dropped"
+      field :ps_ifdrop, :uint, :desc => "drops by interface (not yet supported)"
+      # bs_capt field intentionally left off (WIN32 only)
+    end
+
+    alias received ps_recv
+    alias dropped ps_drop
+    alias interface_dropped ps_ifdrop
+
+  end
+
+  # As returned by pcap_stats_ex() (MSDOS only)
+  #
+  # See pcap_stat_ex struct in pcap.h
+  class StatEx < FFI::Struct
+    include FFI::DRY::StructHelper
+
+    dsl_layout do
+      field :rx_packets,  :ulong, :desc => "total packets received"
+      field :tx_packets,  :ulong, :desc => "total packets transmitted"
+      field :rx_bytes,    :ulong, :desc => "total bytes received"
+      field :tx_bytes,    :ulong, :desc => "total bytes transmitted"
+      field :rx_errors,   :ulong, :desc => "bad packets received"
+      field :tx_errors,   :ulong, :desc => "packet transmit problems"
+      field :rx_dropped,  :ulong, :desc => "no space in Rx buffers"
+      field :tx_dropped,  :ulong, :desc => "no space available for Tx"
+      field :multicast,   :ulong, :desc => "multicast packets received"
+      field :collisions,  :ulong
+
+      # detailed rx errors
+      field :rx_length_errors, :ulong
+      field :rx_over_errors,   :ulong, :desc => "ring buff overflow"
+      field :rx_crc_errors,    :ulong, :desc => "pkt with crc error"
+      field :rx_frame_errors,  :ulong, :desc => "frame alignment errors"
+      field :rx_fifo_errors,   :ulong, :desc => "fifo overrun"
+      field :rx_missed_errors, :ulong, :desc => "missed packet"
+
+      # detailed tx_errors
+      field :tx_aborted_errors,   :ulong
+      field :tx_carrier_errors,   :ulong
+      field :tx_fifo_errors,      :ulong
+      field :tx_heartbeat_errors, :ulong
+      field :tx_window_errors,    :ulong
+    end
+  end
+end
+end

data/lib/ffi/pcap/time_val.rb

@@ -0,0 +1,48 @@
+module FFI
+module PCap
+  class TimeVal < FFI::Struct
+    include FFI::DRY::StructHelper
+
+    dsl_layout do
+      field :tv_sec, :time_t
+      field :tv_usec, :suseconds_t
+    end
+
+    def initialize(*args)
+      if args.size == 1 and (t=args[0]).kind_of?(Time)
+        self.time = t
+      else
+        super(*args)
+      end
+    end
+
+    alias sec tv_sec
+    alias usec tv_usec
+
+    # Returns the time value as a ruby Time object.
+    #
+    # @return [Time]
+    #   A ruby time object derived from this TimeVal.
+    def time
+      Time.at(self.tv_sec, self.tv_usec)
+    end
+
+    alias to_time time
+
+    # Sets the time value from a ruby Time object
+    #
+    # @param [Time] t
+    #   A ruby time object from which to set the time.
+    #
+    # @return [Time]
+    #   Returns the same Time object supplied per convention.
+    #
+    def time=(t)
+      self.tv_sec = t.tv_sec
+      self.tv_usec = t.tv_usec
+      return t
+    end
+
+  end
+end
+end

data/lib/ffi/pcap/typedefs.rb

@@ -0,0 +1,27 @@
+module FFI
+module PCap
+  typedef :pointer, :FILE
+
+  typedef :int,  :bpf_int32
+  typedef :uint, :bpf_uint32
+
+  enum :pcap_direction_t, [
+    :pcap_d_inout,
+    :pcap_d_in,
+    :pcap_d_out
+  ]
+
+  # For Win32-only pcap_setmode()
+  enum :pcap_w32_modes_enum, [ :capt, :stat, :mon ] 
+
+  typedef :pointer, :pcap_t
+  typedef :pointer, :pcap_dumper_t
+  typedef :pointer, :pcap_addr_t
+
+  # add some of the more temperamental FFI types if needed
+  [ [:long, :time_t],
+    [:uint32, :suseconds_t],
+  ].each {|t, d| begin; find_type(d); rescue TypeError; typedef t,d; end }
+
+end
+end

data/lib/ffi/pcap/version.rb

@@ -0,0 +1,6 @@
+module FFI
+module PCap
+  # ffi/pcap version
+  VERSION = '0.1.2'
+end
+end

data/spec/data_link_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+
+describe DataLink do
+  before(:all) do
+    @datalink = DataLink.new(0)
+  end
+
+  it "should map datalink names to datalink layer type values" do
+    DataLink.name_to_val(:en10mb).should == 1
+  end
+
+  it "should map datalink layer type values to datalink names" do
+    DataLink.val_to_name(1).should == "EN10MB"
+  end
+
+  it "should be initialized from a pcap datalink value" do
+    @datalink.name.should == 'NULL'
+  end
+
+  it "should support initialization from a pcap datalink name symbol" do
+    @datalink = DataLink.new(:null)
+    DataLink.should === @datalink
+  end
+
+  it "should support initialization from a pcap datalink name string" do
+    dl = DataLink.new('en10mb')
+    DataLink.should === dl
+  end
+
+  it "should allow equality comparison against numeric values" do
+    (@datalink == 0).should == true
+    (@datalink == 1).should == false
+  end
+
+  it "should allow equality comparison against String names" do
+    (@datalink == "null").should == true
+    (@datalink == "en10mb").should == false
+  end
+
+  it "should allow equality comparison against Symbol names" do
+    (@datalink == :null).should == true
+    (@datalink == :en10mb).should == false
+  end
+
+  it "should allow comparison against another DataLink" do
+    (@datalink == DataLink.new(0)).should == true
+    (@datalink == DataLink.new(1)).should == false
+  end
+
+  it "should still compare correctly against any other object" do
+    (@datalink == Object.new).should == false
+  end
+
+  it "should have a description" do
+    @datalink.description.should_not be_empty
+  end
+
+  it "should convert to an Integer for the DLT value" do
+    @datalink.to_i.should == 0
+  end
+
+  it "should convert to a String for the DLT name" do
+    @datalink.to_s.should == 'NULL'
+  end
+end