packetgen 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 89bdf542e873de9589a6c7e70b3823ccc306ad02
-  data.tar.gz: 82fd50fd41475f7471954dde56174853e24dfd1d
+  metadata.gz: 45af460b696e393ab1c89b3e27fba605246eafc5
+  data.tar.gz: 18f621d8edd0c5c5fee18a97c5ffb9c1d31043c3
 SHA512:
-  metadata.gz: b64e2a6f45b6a35c085c819567f9c08ccb2a62502c74861634408b1e1f69fc4c6ac706ad5223f57095fa2f670b2b4d46b920a5f44ecb7fa49381386a7865b736
-  data.tar.gz: 733c4d48b547aef34bef53c196da7f7d29558286f9791542c316f22e939c2a8c8f75a8b9d372b518b0588723b48c5a84606943b271c41d81d84bd4a985714cb7
+  metadata.gz: dfc16c31052743888efb32945d26d16995e975d6affb47c3a52f4fa4338e7906b75548f8d87e14c963ea89d21e08d877e3f9b62cfa723cf35da90b33a42d3cd4
+  data.tar.gz: d88d482c4eb651b4175453b29c1e71215935d8ff630598dfcb44c33662b272227bda2aea46f7c219c52cd57c9f5093cf2d03dc668e097c03c58f4a89f725dbf3

data/lib/packetgen/capture.rb

@@ -1,3 +1,8 @@
+# This file is part of PacketGen
+# See https://github.com/sdaubert/packetgen for more informations
+# Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
+# This program is published under MIT license.
+
 module PacketGen
 
   # Capture packets from wire

data/lib/packetgen/header/arp.rb

@@ -1,35 +1,59 @@
+# This file is part of PacketGen
+# See https://github.com/sdaubert/packetgen for more informations
+# Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
+# This program is published under MIT license.
+
 module PacketGen
   module Header
 
-    # ARP header class
+    # An ARP header consists of:
+    # * a hardware type ({#hrd} or {#htype}) field ({Int16}),
+    # * a protocol type ({#pro} or {#ptype}) field (+Int16+),
+    # * a hardware address length ({#hln} or {#hlen}) field ({Int8}),
+    # * a protocol address length ({#pln} or {#plen}) field (+Int8+),
+    # * a {#opcode} (or {#op}) field (+Int16+),
+    # * a source hardware address ({#sha} or {#src_mac}) field ({Eth::MacAddr}),
+    # * a source protocol address ({#spa} or {#src_ip}) field ({IP::Addr}),
+    # * a target hardware address ({#tha} or {#dst_mac}) field (+Eth::MacAddr+),
+    # * a target protocol address ({#tpa} or {#dst_ip}) field (+IP::Addr+),
+    # * and a {#body}.
+    #
+    # == Create a ARP header
+    #  # standalone
+    #  arp = PacketGen::Header::ARP.new
+    #  # in a packet
+    #  pkt = PacketGen.gen('Eth').add('ARP')
+    #  # access to ARP header
+    #  pkt.arp   # => PacketGen::Header::ARP
+    #
     # @author Sylvain Daubert
-    class ARP < Struct.new(:hw_type, :proto, :hw_len, :proto_len, :opcode,
-                          :src_mac, :src_ip, :dst_mac, :dst_ip, :body)
+    class ARP < Struct.new(:hrd, :pro, :hln, :pln, :op,
+                           :sha, :spa, :tha, :tpa, :body)
       include StructFu
       include HeaderMethods
       extend HeaderClassMethods
 
       # @param [Hash] options
-      # @option options [Integer] :hw_type network protocol type (default: 1)
-      # @option options [Integer] :proto internet protocol type (default: 0x800)
-      # @option options [Integer] :hw_len length of hardware addresses (default: 6)
-      # @option options [Integer] :proto_len length of internet addresses (default: 4)
-      # @option options [Integer] :opcode operation performing by sender (default: 1).
+      # @option options [Integer] :hrd network protocol type (default: 1)
+      # @option options [Integer] :pro internet protocol type (default: 0x800)
+      # @option options [Integer] :hln length of hardware addresses (default: 6)
+      # @option options [Integer] :pln length of internet addresses (default: 4)
+      # @option options [Integer] :op operation performing by sender (default: 1).
       #   known values are +request+ (1) and +reply+ (2)
-      # @option options [String] :src_mac sender hardware address
-      # @option options [String] :src_ip sender internet address
-      # @option options [String] :dst_mac target hardware address
-      # @option options [String] :dst_ip targetr internet address
+      # @option options [String] :sha sender hardware address
+      # @option options [String] :spa sender internet address
+      # @option options [String] :tha target hardware address
+      # @option options [String] :tpa targetr internet address
        def initialize(options={})
-        super Int16.new(options[:hw_type] || 1),
-              Int16.new(options[:proto] || 0x800),
-              Int8.new(options[:hw_len] || 6),
-              Int8.new(options[:proto_len] || 4),
-              Int16.new(options[:opcode] || 1),
-              Eth::MacAddr.new.parse(options[:src_mac]),
-              IP::Addr.new.parse(options[:src_ip]),
-              Eth::MacAddr.new.parse(options[:dst_mac]),
-              IP::Addr.new.parse(options[:dst_ip]),
+        super Int16.new(options[:hrd] || options[:htype] || 1),
+              Int16.new(options[:pro] || options[:ptype] || 0x800),
+              Int8.new(options[:hln] || options[:hlen] || 6),
+              Int8.new(options[:pln] || options[:plen] || 4),
+              Int16.new(options[:op] || options[:opcode] || 1),
+              Eth::MacAddr.new.from_human(options[:sha] || options[:src_mac]),
+              IP::Addr.new.from_human(options[:spa] || options[:src_ip]),
+              Eth::MacAddr.new.from_human(options[:tha] || options[:dst_mac]),
+              IP::Addr.new.from_human(options[:tpa] || options[:dst_ip]),
               StructFu::String.new.read(options[:body])
       end
 
@@ -39,110 +63,128 @@ module PacketGen
       def read(str)
         force_binary str
         raise ParseError, 'string too short for ARP' if str.size < self.sz
-        self[:hw_type].read str[0, 2]
-        self[:proto].read str[2, 2]
-        self[:hw_len].read str[4, 1]
-        self[:proto_len].read str[5, 1]
-        self[:opcode].read str[6, 2]
-        self[:src_mac].read str[8, 6]
-        self[:src_ip].read str[14, 4]
-        self[:dst_mac].read str[18, 6]
-        self[:dst_ip].read str[24, 4]
+        self[:hrd].read str[0, 2]
+        self[:pro].read str[2, 2]
+        self[:hln].read str[4, 1]
+        self[:pln].read str[5, 1]
+        self[:op].read str[6, 2]
+        self[:sha].read str[8, 6]
+        self[:spa].read str[14, 4]
+        self[:tha].read str[18, 6]
+        self[:tpa].read str[24, 4]
         self[:body].read str[28..-1]
       end
 
-      # @!attribute [rw] hw_type
+      # @!attribute [rw] hrd
       # @return [Integer]
-      def hw_type
-        self[:hw_type].to_i
+      def hrd
+        self[:hrd].to_i
       end
+      alias :htype :hrd
       
-      def hw_type=(i)
-        self[:hw_type].read i
+      def hrd=(i)
+        self[:hrd].read i
       end
+      alias :htype= :hrd=
 
-      # @!attribute [rw] proto
+      # @!attribute [rw] pro
       # @return [Integer]
-      def proto
-        self[:proto].to_i
+      def pro
+        self[:pro].to_i
       end
+      alias :ptype :pro
       
-      def proto=(i)
-        self[:proto].read i
+      def pro=(i)
+        self[:pro].read i
       end
+      alias :ptype= :pro=
 
-      # @!attribute [rw] hw_len
+      # @!attribute [rw] hln
       # @return [Integer]
-      def hw_len
-        self[:hw_len].to_i
+      def hln
+        self[:hln].to_i
       end
+      alias :hlen :hln
       
-      def hw_len=(i)
-        self[:hw_len].read i
+      def hln=(i)
+        self[:hln].read i
       end
+      alias :hlen= :hln=
 
-      # @!attribute [rw] proto_len
+      # @!attribute [rw] pln
       # @return [Integer]
-      def proto_len
-        self[:proto_len].to_i
+      def pln
+        self[:pln].to_i
       end
+      alias :plen :pln
       
-      def proto_len=(i)
-        self[:proto_len].read i
+      def pln=(i)
+        self[:pln].read i
       end
+      alias :plen= :pln=
 
-      # @!attribute [rw] opcode
+      # @!attribute [rw] op
       # @return [Integer]
-      def opcode
-        self[:opcode].to_i
+      def op
+        self[:op].to_i
       end
+      alias :opcode :op
       
-      def opcode=(i)
-        self[:opcode].read i
+      def op=(i)
+        self[:op].read i
       end
+      alias :opcode= :op=
 
-      # @!attribute [rw] src_mac
+      # @!attribute [rw] sha
       # @return [String]
-      def src_mac
-        self[:src_mac].to_x
+      def sha
+        self[:sha].to_human
       end
+      alias :src_mac :sha
       
-      def src_mac=(addr)
-        self[:src_mac].parse addr
+      def sha=(addr)
+        self[:sha].from_human addr
       end
+      alias :src_mac= :sha=
 
-      # @!attribute [rw] src_ip
+      # @!attribute [rw] spa
       # @return [String]
-      def src_ip
-        self[:src_ip].to_x
+      def spa
+        self[:spa].to_human
       end
+      alias :src_ip :spa
       
-      def src_ip=(addr)
-        self[:src_ip].parse addr
+      def spa=(addr)
+        self[:spa].from_human addr
       end
+      alias :src_ip= :spa=
 
-      # @!attribute [rw] dst_mac
+      # @!attribute [rw] tha
       # @return [String]
-      def dst_mac
-        self[:dst_mac].to_x
+      def tha
+        self[:tha].to_human
       end
+      alias :dst_mac :tha
       
-      def dst_mac=(addr)
-        self[:dst_mac].parse addr
+      def tha=(addr)
+        self[:tha].from_human addr
       end
+      alias :dst_mac= :tha=
 
-      # @!attribute [rw] dst_ip
+      # @!attribute [rw] tpa
       # @return [String]
-      def dst_ip
-        self[:dst_ip].to_x
+      def tpa
+        self[:tpa].to_human
       end
+      alias :dst_ip :tpa
       
-      def dst_ip=(addr)
-        self[:dst_ip].parse addr
+      def tpa=(addr)
+        self[:tpa].from_human addr
       end
+      alias :dst_ip= :tpa=
     end
 
-    Eth.bind_header ARP, proto: 0x806
+    Eth.bind_header ARP, ethertype: 0x806
   end
 end
 

data/lib/packetgen/header/eth.rb

@@ -1,9 +1,34 @@
+# This file is part of PacketGen
+# See https://github.com/sdaubert/packetgen for more informations
+# Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
+# This program is published under MIT license.
+
 module PacketGen
   module Header
 
-    # Ethernet header class
+    # An Ethernet header consists of:
+    # * a destination MAC address ({MacAddr}),
+    # * a source MAC address (MacAddr),
+    # * a {#ethertype} ({Int16}),
+    # * and a body (a {String} or another Header class).
+    #
+    # == Create a Ethernet header
+    #  # standalone
+    #  eth = PacketGen::Header::Eth.new
+    #  # in a packet
+    #  pkt = PacketGen.gen('Eth')
+    #  # access to Ethernet header
+    #  pkt.eth   # => PacketGen::Header::Eth
+    #
+    # == Ethernet attributes
+    #  eth.dst = "00:01:02:03:04:05'
+    #  eth.src        # => "00:01:01:01:01:01"
+    #  eth[:src]      # => PacketGen::Header::Eth::MacAddr
+    #  eth.ethertype  # => 16-bit Integer
+    #  eth.body = "This is a body"
+    #
     # @author Sylvain Daubert
-    class Eth < Struct.new(:dst, :src, :proto, :body)
+    class Eth < Struct.new(:dst, :src, :ethertype, :body)
       include StructFu
       include HeaderMethods
       extend HeaderClassMethods
@@ -30,10 +55,10 @@ module PacketGen
 
         end
 
-        # Parse a string to populate MacAddr
+        # Read a human-readable string to populate +MacAddr+
         # @param [String] str
         # @return [self]
-        def parse(str)
+        def from_human(str)
           return self if str.nil?
           bytes = str.split(/:/)
           unless bytes.size == 6
@@ -48,7 +73,7 @@ module PacketGen
           self
         end
 
-        # Read a MacAddr from a string
+        # Read a +MacAddr+ from a binary string
         # @param [String] str binary string
         # @return [self]
         def read(str)
@@ -65,9 +90,9 @@ module PacketGen
                      "def #{sym}=(v); self[:#{sym}].read v; end"
         end
 
-        # Addr in human readable form (dotted format)
+        # +MacAddr+ in human readable form (colon format)
         # @return [String]
-        def to_x
+        def to_human
           members.map { |m| "#{'%02x' % self[m]}" }.join(':')
         end
       end
@@ -82,11 +107,11 @@ module PacketGen
       # @param [Hash] options
       # @option options [String] :dst MAC destination address
       # @option options [String] :src MAC source address
-      # @option options [Integer] :proto
+      # @option options [Integer] :ethertype
       def initialize(options={})
-        super MacAddr.new.parse(options[:dst] || '00:00:00:00:00:00'),
-              MacAddr.new.parse(options[:src] || '00:00:00:00:00:00'),
-              Int16.new(options[:proto] || 0),
+        super MacAddr.new.from_human(options[:dst] || '00:00:00:00:00:00'),
+              MacAddr.new.from_human(options[:src] || '00:00:00:00:00:00'),
+              Int16.new(options[:ethertype] || 0),
               StructFu::String.new.read(options[:body])
       end
 
@@ -99,7 +124,7 @@ module PacketGen
         force_binary str
         self[:dst].read str[0, 6]
         self[:src].read str[6, 6]
-        self[:proto].read str[12, 2]
+        self[:ethertype].read str[12, 2]
         self[:body].read str[14..-1]
         self
       end
@@ -107,40 +132,40 @@ module PacketGen
       # Get MAC destination address
       # @return [String]
       def dst
-        self[:dst].to_x
+        self[:dst].to_human
       end
 
       # Set MAC destination address
       # @param [String] addr
       # @return [String]
       def dst=(addr)
-        self[:dst].parse addr
+        self[:dst].from_human addr
       end
 
       # Get MAC source address
       # @return [String]
       def src
-        self[:src].to_x
+        self[:src].to_human
       end
 
       # Set MAC source address
       # @param [String] addr
       # @return [String]
       def src=(addr)
-        self[:src].parse addr
+        self[:src].from_human addr
       end
 
-      # Get protocol field
+      # Get ethertype field
       # @return [Integer]
-      def proto
-        self[:proto].to_i
+      def ethertype
+        self[:ethertype].to_i
       end
 
-      # Set protocol field
-      # @param [Integer] proto
+      # Set ethertype field
+      # @param [Integer] type
       # @return [Integer]
-      def proto=(proto)
-        self[:proto].value = proto
+      def ethertype=(type)
+        self[:ethertype].value = type
       end
 
       # send Eth packet on wire.

data/lib/packetgen/header/header_class_methods.rb

@@ -1,3 +1,8 @@
+# This file is part of PacketGen
+# See https://github.com/sdaubert/packetgen for more informations
+# Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
+# This program is published under MIT license.
+
 module PacketGen
   module Header
 
@@ -22,7 +27,76 @@ module PacketGen
       def known_headers
         @known_headers ||= {}
       end
-    end
 
+      # Define a bitfield on given attribute
+      #   class MyHeader < Struct.new(:flags)
+      #   
+      #     def initialize(options={})
+      #       super Int16.new(options[:flags])
+      #     end
+      #     
+      #     # define a bit field on :flag attribute:
+      #     # flag1, flag2 and flag3 are 1-bit fields
+      #     # type and stype are 3-bit fields. reserved is a 6-bit field
+      #     define_bit_fields_on :flags, :flag1, :flag2, :flag3, :type, 3, :stype, 3, :reserved: 6
+      #   end
+      # A bitfield of size 1 bit defines 2 methods:
+      # * +#field?+ which returns a Boolean,
+      # * +#field=+ which takes and returns a Boolean.
+      # A bitfield of more bits defines 2 methods:
+      # * +#field+ which returns an Integer,
+      # * +#field=+ which takes and returns an Integer.
+      # @param [Symbol] attr attribute name (attribute should a {StructFu::Int}
+      #   subclass)
+      # @param [Array] args list of bitfield names. Name may be followed
+      #   by bitfield size. If no size is given, 1 bit is assumed.
+      # @return [void]
+      def define_bit_fields_on(attr, *args)
+        total_size = self.new[attr].width * 8
+        idx = total_size - 1
+
+        field = args.shift
+        while field
+          next unless field.is_a? Symbol
+          size = if args.first.is_a? Integer
+                   args.shift
+                 else
+                   1
+                 end
+          unless field == :_
+            shift = idx - (size - 1)
+            field_mask = (2**size - 1) << shift
+            clear_mask = (2**total_size - 1) & (~field_mask & (2**total_size - 1))
+
+            if size == 1
+              class_eval <<-EOM
+              def #{field}?
+                val = (self[:#{attr}].to_i & #{field_mask}) >> #{shift}
+                val != 0
+              end
+              def #{field}=(v)
+                val = v ? 1 : 0
+                self[:#{attr}].value = self[:#{attr}].to_i & #{clear_mask}
+                self[:#{attr}].value |= val << #{shift}
+              end
+              EOM
+            else
+              class_eval <<-EOM
+              def #{field}
+                (self[:#{attr}].to_i & #{field_mask}) >> #{shift}
+              end
+              def #{field}=(v)
+                self[:#{attr}].value = self[:#{attr}].to_i & #{clear_mask}
+                self[:#{attr}].value |= (v & #{2**size - 1}) << #{shift}
+              end
+              EOM
+            end
+          end
+
+          idx -= size
+          field = args.shift
+        end
+      end
+    end
   end
 end

data/lib/packetgen/header/header_methods.rb

@@ -1,3 +1,8 @@
+# This file is part of PacketGen
+# See https://github.com/sdaubert/packetgen for more informations
+# Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
+# This program is published under MIT license.
+
 module PacketGen
   module Header
 
@@ -46,6 +51,17 @@ module PacketGen
         raise FormatError, 'no IP or IPv6 header in packet' if iph.nil?
         iph
       end
+
+      # Common inspect method for headers
+      # @return [String]
+      def inspect
+        str = Inspect.dashed_line(self.class, 2)
+        to_h.each do |attr, value|
+          next if attr == :body
+          str << Inspect.inspect_attribute(attr, value, 2)
+        end
+        str
+      end
     end
   end
 end

data/lib/packetgen/header/icmp.rb

@@ -1,9 +1,32 @@
+# This file is part of PacketGen
+# See https://github.com/sdaubert/packetgen for more informations
+# Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
+# This program is published under MIT license.
+
 module PacketGen
   module Header
 
-    # ICMP header class
+    # A ICMP header consists of:
+    # * a {#type} field ({Int8} type),
+    # * a {#code} field ({Int8} type),
+    # * a {#checksum} field ({Int16} type),
+    # * and a {#body}.
+    #
+    # == Create a ICMP header
+    #  # standalone
+    #  icmp = PacketGen::Header::ICMP.new
+    #  # in a packet
+    #  pkt = PacketGen.gen('IP').add('ICMP')
+    #  # access to ICMP header
+    #  pkt.icmp     # => PacketGen::Header::ICMP
+    #
+    # == ICMP attributes
+    #  icmp.code = 0
+    #  icmp.type = 200
+    #  icmp.checksum = 0x248a
+    #  icmp.body.read 'this is a body'
     # @author Sylvain Daubert
-    class ICMP < Struct.new(:type, :code, :sum, :body)
+    class ICMP < Struct.new(:type, :code, :checksum, :body)
       include StructFu
       include HeaderMethods
       extend HeaderClassMethods
@@ -14,12 +37,12 @@ module PacketGen
       # @param [Hash] options
       # @option options [Integer] :type
       # @option options [Integer] :code
-      # @option options [Integer] :sum
+      # @option options [Integer] :checksum
       # @option options [String] :body
       def initialize(options={})
         super Int8.new(options[:type]),
               Int8.new(options[:code]),
-              Int16.new(options[:sum]),
+              Int16.new(options[:checksum]),
               StructFu::String.new.read(options[:body])
       end
 
@@ -28,17 +51,17 @@ module PacketGen
       # @return [self]
       def read(str)
         return self if str.nil?
-        raise ParseError, 'string too short for Eth' if str.size < self.sz
+        raise ParseError, 'string too short for ICMP' if str.size < self.sz
         force_binary str
         self[:type].read str[0, 1]
         self[:code].read str[1, 1]
-        self[:sum].read str[2, 2]
+        self[:checksum].read str[2, 2]
         self[:body].read str[4..-1]
       end
 
-      # Compute checksum and set +sum+ field
+      # Compute checksum and set +checksum+ field
       # @return [Integer]
-      def calc_sum
+      def calc_checksum
         sum = (type << 8) | code
 
         payload = body.to_s
@@ -49,7 +72,7 @@ module PacketGen
           sum = (sum & 0xffff) + (sum >> 16)
         end
         sum = ~sum & 0xffff
-        self[:sum].value = (sum == 0) ? 0xffff : sum
+        self[:checksum].value = (sum == 0) ? 0xffff : sum
       end
 
       # Getter for type attribute
@@ -78,20 +101,20 @@ module PacketGen
         self[:code].value = code
       end
 
-      # Getter for sum attribute
+      # Getter for checksum attribute
       # @return [Integer]
-      def sum
-        self[:sum].to_i
+      def checksum
+        self[:checksum].to_i
       end
 
-      # Setter for sum attribute
+      # Setter for checksum attribute
       # @param [Integer] sum
       # @return [Integer]
-      def sum=(sum)
-        self[:sum].value = sum
+      def checksum=(sum)
+        self[:checksum].value = sum
       end
     end
 
-    IP.bind_header ICMP, proto: ICMP::IP_PROTOCOL
+    IP.bind_header ICMP, protocol: ICMP::IP_PROTOCOL
   end
 end