packetgen 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f98c7d5b928554e3d6da92e42f96bf3ee0a397a8
-  data.tar.gz: 994ede3f4bc303f98df8bd29e6bcb0b34932bf75
+  metadata.gz: 67bab87e209f3ad1ca3adecf77be2b19c1ba17a5
+  data.tar.gz: c5bd835c57160261677a22693e297c8b27ac3cbe
 SHA512:
-  metadata.gz: d3a0d0198fda11d157d42ca626b6e59d0af792748b194d60dff4d0bd6a928e6b664eeb4d95d5ad70c94e3f38e690e8b616377eb95fffd9fe338158766235148c
-  data.tar.gz: '09ba37f246d17b612f0ae247dab1408a799a9782d652e29ac3e798d8b46543225b506c983546b2e5acc7effdc52aca65f17f1fec1e3d32434f68edd535439b18'
+  metadata.gz: 466fadd588084aedad8c7e9fbc7ac6313f8f66d47594171fc7728c2056369ffc2e24fedb4794f4a37cd8fcc66ed4dff7db5339e1f19fefc3522d4906a8667953
+  data.tar.gz: c8bd3cb05a61ae939f152355d45fed6ff0e26b6760dd0bea98fddff4aa86263ec1eea27b24024325ae089246cb78baad3958b9df7a949771150d65c45cba7073

data/README.md

@@ -4,17 +4,7 @@
 
 # PacketGen
 
-PacketGen provides simple ways to generate, send and capture network packets easily.
-
-## Why PacketGen
-Why create PacketGen ? There is already PacketFu!
-
-Yes. But PacketFu is limited:
-* upper protocols use fixed layers: TCP always uses IPv4, IP and IPv6 always uses Ethernet as MAC,...
-* cannot handle tunneled packets (IP-in-IP, or deciphered ESP packets,...)
-* cannot easily encapsulate or decapsulate packets
-* parse packets top-down, and sometimes bad parse down layers
-* cannot send packet on wire at IP/IPv6 level (Ethernet header is mandatory)
+PacketGen provides simple ways to generate, send and capture network packets.
 
 ## Installation
 Via RubyGems:
@@ -25,10 +15,11 @@ Or add it to a Gemfile:
 ```ruby
 gem 'packetgen'
 ```
+
 ## Usage
 
 ### Easily create packets
-```
+```ruby
 PacketGen.gen('IP')             # generate a IP packet object
 PacketGen.gen('TCP')            # generate a TCP over IP packet object
 PacketGen.gen('IP').add('TCP')  # the same
@@ -43,9 +34,7 @@ PacketGen.gen('IP').to_s
 ```
 
 ### Send packets on wire
-need PcapRub for Ethernet packets. Need a C extension (use of C socket API) for IP packets.
-
-```
+```ruby
 # send Ethernet packet
 PacketGen.gen('Eth', src: '00:00:00:00:01', dst: '00:00:00:00:02').to_w
 # send IP packet
@@ -55,14 +44,12 @@ PacketGen.gen('Eth', src: '00:00:00:00:01', dst: '00:00:00:00:02').add('IP').to_
 ```
 
 ### Parse packets from binary data
-```
+```ruby
 packet = PacketGen.parse(binary_data)
 ```
 
 ### Capture packets from wire
-need PCapRub.
-
-```
+```ruby
 # Capture packets, action from a block
 PacketGen.capture('eth0') do |packet|
   do_stuffs_with_packet
@@ -76,7 +63,7 @@ packets = PacketGen.capture('eth0', filter: 'ip src 1.1.1.2', max: 1)
 ```
 
 ### Easily manipulate packets
-```
+```ruby
 # access header fields
 pkt = PacketGen.gen('IP').add('TCP')
 pkt.ip.src = '192.168.1.1'
@@ -101,7 +88,7 @@ pkt2.decapsulate(pkt2.ip)              # pkt2 is now inner IP/TCP packet
 ```
 
 ### Read/write PcapNG files
-```
+```ruby
 # read a PcapNG file, containing multiple packets
 packets = PacketGen.read('file.pcapng')
 packets.first.udp.sport = 65535
@@ -112,44 +99,34 @@ PacketGen.write('more_packets.pcapng', packets)
 ```
 
 ### Add custom header/protocol
-Since v1.1.0, PacketGen permits adding you own header classes.
-First, define the new header class. By example:
+Since v1.1.0, PacketGen permits adding your own header classes.
+First, define the new header class. For example:
 
 ```ruby
 module MyModule
- class MyHeader < Struct.new(:field1, :field2)
-   include PacketGen::StructFu
-   include PacketGen::Header::HeaderMethods
-   extend PacketGen::Header::HeaderClassMethods
-   
-   def initialize(options={})
-     super Int32.new(options[:field1]), Int32.new(options[:field2])
-   end
-   
-   def read(str)
-     self[:field1].read str[0, 4]
-     self[:field2].read str[4, 4]
-   end
+ class MyHeader < PacketGen::Header::Base
+   define_field :field1, PacketGen::Types::Int32   
+   define_field :field2, PacketGen::Types::Int32   
  end
 end
 ```
 
 Then, class must be declared to PacketGen:
 
-```
+```ruby
 PacketGen::Header.add_class MyModule::MyHeader
 ```
 
 Finally, bindings must be declared:
 
-```
-# bind MyHeader as IP protocol number 254 (needed by Packet#parse)
+```ruby
+# bind MyHeader as IP protocol number 254 (needed by Packet#parse and Packet#add)
 PacketGen::Header::IP.bind_header MyModule::MyHeader, protocol: 254
 ```
 
 And use it:
 
-```
+```ruby
 pkt = Packet.gen('IP').add('MyHeader', field1: 0x12345678)
 pkt.myheader.field2.read 0x01
 ```
@@ -166,5 +143,5 @@ Copyright © 2016 Sylvain Daubert
 ### Other sources
 All original code maintains its copyright from its original authors and licensing.
 
-This is mainly for PcapNG (copied from [PacketFu](https://github.com/packetfu/packetfu),
+This is mainly for PcapNG (originally copied from [PacketFu](https://github.com/packetfu/packetfu),
 but i am the original author).

data/lib/packetgen.rb

@@ -85,6 +85,6 @@ end
 
 require 'packetgen/types'
 require 'packetgen/inspect'
+require 'packetgen/pcapng'
 require 'packetgen/packet'
 require 'packetgen/capture'
-require 'packetgen/pcapng'

data/lib/packetgen/header.rb

@@ -11,20 +11,14 @@ module PacketGen
   # First, define the new header class. By example:
   #  module MyModule
   #    class MyHeader < PacketGen::Header::Base
-  #      def initialize(options={})
-  #        super Int32.new(options[:field1]), Int32.new(options[:field2])
-  #      end
-  #      
-  #      def read(str)
-  #        self[:field1].read str[0, 4]
-  #        self[:field2].read str[4, 4]
-  #      end
+  #      define_field :field1, PacketGen::Types::Int32   
+  #      define_field :field2, PacketGen::Types::Int32   
   #    end
   #   end
   # Then, class must be declared to PacketGen:
   #  PacketGen::Header.add_class MyModule::MyHeader
   # Finally, bindings must be declared:
-  #  # bind MyHeader as IP protocol number 254 (needed by Packet#parse)
+  #  # bind MyHeader as IP protocol number 254 (needed by Packet#parse and Packet#add)
   #  PacketGen::Header::IP.bind_header MyModule::MyHeader, protocol: 254
   # And use it:
   #  pkt = Packet.gen('IP').add('MyHeader', field1: 0x12345678)
@@ -32,6 +26,13 @@ module PacketGen
   # @author Sylvain Daubert
   module Header
 
+    # @private snap length for PCAPRUB
+    PCAP_SNAPLEN = 0xffff
+    # @private promiscuous (or not) for PCAPRUB
+    PCAP_PROMISC = false
+    # @private timeout for PCAPRUB
+    PCAP_TIMEOUT = 1
+
     @added_header_classes = {}
 
     # Get known header classes
@@ -79,6 +80,10 @@ end
 
 require_relative 'header/base'
 require_relative 'header/eth'
+require_relative 'header/dot11'
+require_relative 'header/llc'
+require_relative 'header/dot1q'
+require_relative 'header/dot1x'
 require_relative 'header/ip'
 require_relative 'header/icmp'
 require_relative 'header/arp'

data/lib/packetgen/header/arp.rb

@@ -116,6 +116,7 @@ module PacketGen
     self.add_class ARP
 
     Eth.bind_header ARP, ethertype: 0x806
+    Dot1q.bind_header ARP, ethertype: 0x806
   end
 end
 

data/lib/packetgen/header/base.rb

@@ -86,7 +86,7 @@ module PacketGen
         def check?(fields)
           case @op
           when :or
-            @bindings.any? { |binding| binding.check?(fields) }
+            empty? || @bindings.any? { |binding| binding.check?(fields) }
           when :and
             @bindings.all? { |binding| binding.check?(fields) }
           end
@@ -100,6 +100,41 @@ module PacketGen
         end
       end
 
+      # @api private
+      # Class to handle header associations
+      class Bindings
+        include Enumerable
+
+        # op type
+        # @return [:or,:and]
+        attr_accessor :op
+        # @return [Array<Binding>]
+        attr_accessor :bindings
+
+        # @param [:or, :and] op
+        def initialize(op)
+          @op = op
+          @bindings = []
+        end
+
+        # @param [Object] arg
+        # @return [Bindings] self
+        def <<(arg)
+          @bindings << arg
+        end
+
+        # each iterator
+        # @return [void]
+        def each
+          @bindings.each { |b| yield b }
+        end
+
+        # @return [Boolean]
+        def empty?
+          @bindings.empty?
+        end
+      end
+
       # @api private
       # Reference on packet which owns this header
       attr_accessor :packet
@@ -144,6 +179,20 @@ module PacketGen
         @known_headers
       end
 
+      # Return header protocol name
+      # @return [String]
+      def protocol_name
+        self.class.to_s.sub(/.*::/, '')
+      end
+
+      # @abstract Should be redefined by subclasses. This method should check invariant
+      #   fields from header.
+      # Call by {Packet#parse} when guessing first header to check if header is correct
+      # @return [Boolean]
+      def parse?
+        true
+      end
+
       # @api private
       # Get +header+ id in packet headers array
       # @param [Header] header

data/lib/packetgen/header/dot11.rb

@@ -0,0 +1,349 @@
+# coding: utf-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.
+require 'zlib'
+
+module PacketGen
+  module Header
+
+    # PPI (Per-Packet Information) packet
+    #@author Sylvain Daubert
+    class PPI < Base
+      # @!attribute version
+      #  @return [Integer] 8-bit PPI version
+      define_field :version, Types::Int8, default: 0
+      # @!attribute flags
+      #  @return [Integer] 8-bit PPI flags
+      define_field :flags, Types::Int8
+      # @!attribute length
+      #  @return [Integer] 16-bit PPI header length
+      define_field :length, Types::Int16le, default: 8
+      # @!attribute dlt
+      #  @return [Integer] 32-bit PPI data link type
+      define_field :dlt, Types::Int32le
+      # @!attribute ppi_fields
+      #  @return [Type::String] concatenation of PPI fields
+      define_field :ppi_fields, Types::String
+      # @!attribute body
+      #  @return [Type::String]
+      define_field :body, Types::String
+      # @!attribute align
+      #  @return [Boolean] align flag from {#flags} attribute
+      define_bit_fields_on :flags, :reserved, 7, :align
+
+      # @param [String] str
+      # @return [PPI] self
+      def read(str)
+        return self if str.nil?
+        force_binary str
+        self[:version].read str[0, 1]
+        self[:flags].read str[1, 1]
+        self[:length].read str[2, 2]
+        self[:dlt].read str[4, 4]
+        self[:ppi_fields].read str[8, length - 8]
+        self[:body].read str[length, str.size]
+        self
+      end
+
+      # Check version field
+      # @see [Base#parse?]
+      def parse?
+        version == 0
+      end
+
+      # send PPI packet on wire. Dot11 FCS trailer should be set.
+      # @param [String] iface interface name
+      # @return [void]
+      def to_w(iface)
+        pcap = PCAPRUB::Pcap.open_live(iface, PCAP_SNAPLEN, PCAP_PROMISC,
+                                       PCAP_TIMEOUT)
+        pcap.inject self.to_s
+      end
+    end
+    self.add_class PPI
+
+    # Radiotap header
+    # @author Sylvain Daubert
+    class RadioTap < Base
+      # @!attribute version
+      #  @return [Integer] 8-bit version
+      define_field :version, Types::Int8, default: 0
+      # @!attribute pad
+      #  @return [Integer] 8-bit pad
+      define_field :pad, Types::Int8, default: 0
+      # @!attribute length
+      #  @return [Integer] 16-bit RadioTap header length
+      define_field :length, Types::Int16le
+      # @!attribute present_flags
+      #  @return [Integer] 32-bit integer
+      define_field :present_flags, Types::Int32le
+      # @!attribute radio_fields
+      #  @return [Type::String] concatenation of RadioTap fields
+      define_field :radio_fields, Types::String
+      # @!attribute body
+      #  @return [Type::String]
+      define_field :body, Types::String
+
+      # @param [String] str
+      # @return [RadioTap] self
+      def read(str)
+        return self if str.nil?
+        force_binary str
+        self[:version].read str[0, 1]
+        self[:pad].read str[1, 1]
+        self[:length].read str[2, 2]
+        self[:present_flags].read str[4, 4]
+        self[:radio_fields].read str[8, length - 8]
+        self[:body].read str[length, str.size]
+        self
+      end
+
+      # Check version field
+      # @see [Base#parse?]
+      def parse?
+        version == 0
+      end
+
+      # send RadioTap packet on wire. Dot11 FCS trailer should be set.
+      # @param [String] iface interface name
+      # @return [void]
+      def to_w(iface)
+        pcap = PCAPRUB::Pcap.open_live(iface, PCAP_SNAPLEN, PCAP_PROMISC,
+                                       PCAP_TIMEOUT)
+        pcap.inject self.to_s
+      end
+    end
+    self.add_class RadioTap
+
+    # IEEE 802.11 header
+    # @abstract This is a base class to demultiplex different IEEE 802.11 frames when
+    #   parsing.
+    # A IEEE 802.11 header may consists of at least:
+    # * a {#frame_ctrl} ({Types::Int16}),
+    # * a {#id}/duration ({Types::Int16le}),
+    # * and a {#mac1} ({Eth::MacAddr}).
+    # Depending on frame type and subtype, it may also contains:
+    # * a {#mac2} ({Eth::MacAddr}),
+    # * a {#mac3} ({Eth::MacAddr}),
+    # * a {#sequence_ctrl} ({Types::Int16}),
+    # * a {#mac4} ({Eth::MacAddr}),
+    # * a {#qos_ctrl} ({Types::Int16}),
+    # * a {#ht_ctrl} ({Types::Int32}),
+    # * a {#body} (a {Types::String} or another {Base} class),
+    # * a Frame check sequence ({#fcs}, of type {Types::Int32le})
+    # @author Sylvain Daubert
+    class Dot11 < Base
+
+      # Frame types
+      TYPES = %w(Management Control Data Reserved).freeze
+
+      class << self
+        # Set a flag for parsing Dot11 packets. If set to +true+, parse FCS field,
+        # else don't. Default is +true+.
+        # @return [Boolean]
+        attr_accessor :has_fcs
+      end
+      Dot11.has_fcs = true
+
+      # @!attribute frame_ctrl
+      #  @return [Integer] 16-bit frame control word
+      define_field :frame_ctrl, Types::Int16, default: 0
+      # @!attribute id
+      #  @return [Integer] 16-bit ID/Duration word
+      define_field :id, Types::Int16le, default: 0
+      # @!attribute mac1
+      #  @return [Eth::MacAddr]
+      define_field :mac1, Eth::MacAddr
+      # @!attribute mac2
+      #  @return [Eth::MacAddr]
+      define_field :mac2, Eth::MacAddr
+      # @!attribute mac3
+      #  @return [Eth::MacAddr]
+      define_field :mac3, Eth::MacAddr
+      # @!attribute sequence_ctrl
+      #  @return [Integer] 16-bit sequence control word
+      define_field :sequence_ctrl, Types::Int16le, default: 0
+      # @!attribute mac4
+      #  @return [Eth::MacAddr]
+      define_field :mac4, Eth::MacAddr
+      # @!attribute qos_ctrl
+      #  @return [Integer] 16-bit QoS control word
+      define_field :qos_ctrl, Types::Int16
+      # @!attribute ht_ctrl
+      #  @return [Integer] 16-bit HT control word
+      define_field :ht_ctrl, Types::Int32
+      # @!attribute body
+      #  @return [Types::String]
+      define_field :body, Types::String
+      # @!attribute fcs
+      #  @return [Types::Int32le]
+      define_field :fcs, Types::Int32le
+
+      # @!attribute subtype
+      #  @return [Integer] 4-bit frame subtype from {#frame_ctrl}
+      # @!attribute type
+      #  @return [Integer] 2-bit frame type from {#frame_ctrl}
+      # @!attribute proto_version
+      #  @return [Integer] 2-bit protocol version from {#frame_ctrl}
+      # @!attribute order
+      #  @return [Boolean] order flag from {#frame_ctrl}
+      # @!attribute wep
+      #  @return [Boolean] wep flag from {#frame_ctrl}
+      # @!attribute md
+      #  @return [Boolean] md flag from {#frame_ctrl}
+      # @!attribute pwmngt
+      #  @return [Boolean] pwmngt flag from {#frame_ctrl}
+      # @!attribute retry
+      #  @return [Boolean] retry flag from {#frame_ctrl}
+      # @!attribute mf
+      #  @return [Boolean] mf flag from {#frame_ctrl}
+      # @!attribute from_ds
+      #  @return [Boolean] from_ds flag from {#frame_ctrl}
+      # @!attribute to_ds
+      #  @return [Boolean] to_ds flag from {#frame_ctrl}
+      define_bit_fields_on :frame_ctrl,  :subtype, 4, :type, 2, :proto_version, 2,
+                            :order, :wep, :md, :pwmngt, :retry, :mf, :from_ds, :to_ds
+
+      alias duration id
+      # @private
+      alias old_fields fields
+
+      # @param [Hash] options
+      # @see Base#initialize
+      def initialize(options={})
+        super
+        @applicable_fields = old_fields
+      end
+
+      # Get all used field names
+      # @return [Array<Symbol>]
+      def fields
+        @applicable_fields
+      end
+
+      # @private
+      alias old_read read
+
+      # Populate object from a binary string
+      # @param [String] str
+      # @return [Dot11] may return a subclass object if a more specific class
+      #   may be determined
+      def read(str)
+        has_fcs = Dot11.has_fcs
+
+        if self.class == Dot11
+          return self if str.nil?
+          force_binary str
+          self[:frame_ctrl].read str[0, 2]
+
+          case type
+          when 0
+            Dot11::Management.new.read str
+          when 1
+            Dot11::Control.new.read str
+          when 2
+            Dot11::Data.new.read str
+          else
+            private_read str, has_fcs
+          end
+        else
+          private_read str, has_fcs
+        end
+      end
+
+      # Compute checksum and set +fcs+ field
+      # @return [Integer]
+      def calc_checksum
+        fcs = Zlib.crc32(to_s[0...-4])
+        self.fcs = fcs
+        fcs
+      end
+
+      # @return [String]
+      def to_s
+        define_applicable_fields
+        @applicable_fields.map { |f| force_binary @fields[f].to_s }.join
+      end
+
+      # Get human readable type
+      # @return [String]
+      def human_type
+        TYPES[type]
+      end
+
+      # @return [String]
+      def inspect
+        str = if self.class == Dot11
+                Inspect.dashed_line("#{self.class} #{human_type}", 2)
+              elsif self.respond_to? :human_subtype
+                Inspect.dashed_line("#{self.class} #{human_subtype}", 2)
+              else
+                Inspect.dashed_line("#{self.class}", 2)
+              end
+        define_applicable_fields
+        @applicable_fields.each do |attr|
+          next if attr == :body
+          str << Inspect.inspect_attribute(attr, @fields[attr], 2)
+        end
+        str
+      end
+
+      # send Dot11 packet on wire.
+      # @param [String] iface interface name
+      # @return [void]
+      def to_w(iface)
+        pcap = PCAPRUB::Pcap.open_live(iface, PCAP_SNAPLEN, PCAP_PROMISC,
+                                       PCAP_TIMEOUT)
+        str = self.to_s
+        pcap.inject str << [crc32].pack('V')
+      end
+
+      private
+
+      def define_applicable_fields
+        if to_ds? and from_ds?
+          @applicable_fields[6, 0] = :mac4 unless @applicable_fields.include? :mac4
+        else
+          @applicable_fields -= %i(mac4)
+        end
+        if order?
+          unless @applicable_fields.include? :ht_ctrl
+            idx = @applicable_fields.index(:body)
+            @applicable_fields[idx, 0] = :ht_ctrl
+            end
+        else
+          @applicable_fields -= %i(ht_ctrl)
+        end
+        if Dot11.has_fcs
+          @applicable_fields << :fcs unless @applicable_fields.include? :fcs
+        else
+          @applicable_fields -= %i(fcs)
+        end
+      end
+
+      def private_read(str, has_fcs)
+        self[:frame_ctrl].read str[0, 2]
+        define_applicable_fields
+        if has_fcs
+          old_read str[0...-4]
+          self[:fcs].read str[-4..-1]
+        else
+          old_read str
+        end
+        self
+      end
+    end
+
+    self.add_class Dot11
+    PPI.bind_header Dot11, dlt: PcapNG::LINKTYPE_IEEE802_11
+    RadioTap.bind_header Dot11
+  end
+end
+
+require_relative 'dot11/element'
+require_relative 'dot11/management'
+require_relative 'dot11/sub_mngt'
+require_relative 'dot11/control'
+require_relative 'dot11/data'