packetgen 3.3.3 → 4.1.0

data/lib/packetgen/packet.rb

@@ -7,50 +7,58 @@
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # This program is published under MIT license.
 
-# rubocop:disable Metrics/ClassLength
-
 module PacketGen
   # An object of type {Packet} handles a network packet. This packet may contain
   # multiple protocol headers, starting from MAC layer or from Network (OSI) layer.
   #
-  # Creating a packet is fairly simple:
-  #  Packet.gen 'IP', src: '192.168.1.1', dst: '192.168.1.2'
+  # A Packet is created using {.gen} method. Headers may be added to this packet using {#add}.
+  # It may also be created from parsing a binary string, using {.parse} method.
+  #
+  # @example Very simple packet
+  #   # Create a packet with a single IP header. IP source and destination addresses are set.
+  #   pkt = PacketGen::Packet.gen('IP', src: '192.168.1.1', dst: '192.168.1.2')
   #
-  # == Create a packet
-  # Packets may be hand-made or parsed from a binary string:
-  #  Packet.gen('IP', src: '192.168.1.1', dst: '192.168.1.2').add('UDP', sport: 45000, dport: 23)
-  #  Packet.parse(binary_string)
+  # @example Parsing a binary string
+  #  # a IP/ICMP packet, as binary string
+  #  binary_string = "E\x00\x00\x1C\xAA`\x00\x00@\x01M-\xC0\xA8\x01\x01\xC0\xA8\x01\x02\x00\b;1abcd".b
+  #  pkt = PacketGen::Packet.parse(binary_string)
+  #  pkt.is?('IP')    #=> true
+  #  pkt.is?('ICMP')  #=> true
   #
-  # == Access packet information
-  #  pkt = Packet.gen('IP').add('UDP')
-  #  # read information
-  #  pkt.udp.sport
-  #  pkt.ip.ttl
-  #  # set information
-  #  pkt.udp.dport = 2323
-  #  pkt.ip.ttl = 1
-  #  pkt.ip(ttl: 1, id: 1234)
+  # Information for each level is accessible through the associated header. Header is accessible through a
+  # method defined with its name at packet level (i.e. +#ip+ for a IP header).
   #
-  # == Save a packet to a file
-  #  pkt.write('file.pcapng')
+  # @example Accessing header information
+  #   pkt = PacketGen::Packet.gen('IP').add('UDP')
+  #   # read information
+  #   pkt.udp.sport #=> 0
+  #   pkt.ip.ttl    #=> 64
+  #   # set information
+  #   pkt.udp.dport = 2323
+  #   pkt.ip.ttl = 1
+  #   # Set multiple attributes at once
+  #   pkt.ip(ttl: 1, id: 1234)
   #
-  # == Get packets
-  # Packets may be captured from wire:
-  #  Packet.capture do |packet|
-  #    do_some_stuffs
-  #  end
-  #  packets = Packet.capture(iface: 'eth0', max: 5)  # get 5 packets from eth0
+  # Packets may be written to files using {#write}:
+  #   pkt = PacketGen::Packet.gen('Eth')
+  #   pkt.write('file.pcapng')
   #
-  # Packets may also be read from a file:
-  #  packets = Packet.read(file.pcapng)
+  # Packets may be captured from network interfaces:
+  #   # Capture all packets from default interface. Never end.
+  #   PacketGen::Packet.capture do |packet|
+  #     do_some_stuffs
+  #   end
   #
-  # == Save packets to a file
-  #  Packet.write 'file.pcapng', packets
+  #   # Get 5 packets from eth0 interface
+  #   packets = Packet.capture(iface: 'eth0', max: 5)
   #
+  # Finally, packets may also be read from a file:
+  #   packets = Packet.read(file.pcapng)
   # @author Sylvain Daubert
+  # @author LemonTree55
   class Packet
     # Get packet headers, ordered as they appear in the packet.
-    # @return [Array<Header::Base>]
+    # @return [Array<Headerable>]
     attr_reader :headers
     # Activaye or deactivate header cache (activated by default)
     # @return [Boolean]
@@ -61,20 +69,20 @@ module PacketGen
     # @param [Hash] options specific options for +protocol+
     # @return [Packet]
     def self.gen(protocol, options={})
-      self.new.add protocol, options
+      self.new.add(protocol, options)
     end
 
     # Parse a binary string and generate a Packet from it.
     #   # auto-detect first header
-    #   Packet.parse str
+    #   Packet.parse(str)
     #   # force decoding a Ethernet header for first header
-    #   Packet.parse str, first_header: 'Eth'
+    #   Packet.parse(str, first_header: 'Eth')
     # @param [String] binary_str
     # @param [String,nil] first_header First protocol header. +nil+ means discover it!
     # @return [Packet]
     # @raise [ArgumentError] +first_header+ is an unknown header
     def self.parse(binary_str, first_header: nil)
-      new.parse binary_str, first_header: first_header
+      new.parse(binary_str, first_header: first_header)
     end
 
     # Capture packets from wire.
@@ -112,16 +120,23 @@ module PacketGen
       Pcap.read(filename)
     end
 
-    # Write packets to +filename+
+    # Write packets to +filename+, as pcap or PcapNG file
     #
     # For more options, see {PcapNG::File}.
     # @param [String] filename
     # @param [Array<Packet>] packets packets to write
     # @return [void]
+    # @since 4.0.0 write a pcap file if filename extension is +.pcap+
+    # @author Sylvain Daubert
+    # @author LemonTree55 (pcap)
     def self.write(filename, packets)
-      pf = PcapNG::File.new
-      pf.array_to_file packets
-      pf.to_f filename
+      if filename.end_with?('.pcap')
+        Pcap.write(filename, packets)
+      else
+        pf = PcapNG::File.new
+        pf.read_array(packets)
+        pf.to_f(filename)
+      end
     end
 
     # @private
@@ -135,14 +150,22 @@ module PacketGen
     # @param [String] protocol
     # @param [Hash] options protocol specific options
     # @return [self]
-    # @raise [BindingError] unknown protocol
+    # @raise [ArgumentError] unknown protocol
+    # @raise [BindingError] unknown binding
+    # @see #<<
+    # @example
+    #  pkt = PacketGen::Packet.gen('Eth')
+    #  # Add a IP header
+    #  pkt.add('IP')
+    #  # Add a TCP header, with some attributes and body set
+    #  pkt.add('TCP', dport: 80, seqnum: 123456, body: "abcd".b)
     def add(protocol, options={})
       klass = check_protocol(protocol)
 
       # options[:packet]= self is speedier than options.merge(packet: self)
       options[:packet] = self
       header = klass.new(options)
-      add_header header
+      add_header(header)
       self
     end
 
@@ -159,7 +182,7 @@ module PacketGen
       # options[:packet]= self is speedier than options.merge(packet: self)
       options[:packet] = self
       header = klass.new(options)
-      add_header header, previous_header: prev
+      add_header(header, previous_header: prev)
       idx = headers.index(prev) + 1
       headers[idx, 0] = header
       header[:body] = nxt
@@ -167,13 +190,14 @@ module PacketGen
     end
 
     # Check if a protocol header is embedded in packet.
+    # @example
     #   pkt = PacketGen.gen('IP').add('UDP')
     #   pkt.is?('IP')   #=> true
     #   pkt.is?('TCP')  #=> false
     # @return [Boolean]
     # @raise [ArgumentError] unknown protocol
     def is?(protocol)
-      klass = check_protocol protocol
+      klass = check_protocol(protocol)
       headers.any?(klass)
     end
 
@@ -181,7 +205,7 @@ module PacketGen
     # @return [void]
     def calc_checksum
       headers.reverse_each do |header|
-        header.calc_checksum if header.respond_to? :calc_checksum
+        header.calc_checksum if header.respond_to?(:calc_checksum)
       end
     end
 
@@ -189,27 +213,36 @@ module PacketGen
     # @return [void]
     def calc_length
       headers.reverse_each do |header|
-        header.calc_length if header.respond_to? :calc_length
+        header.calc_length if header.respond_to?(:calc_length)
       end
     end
 
     # Recalculate all calculatable fields (for now: length and checksum)
     # @return [void]
+    # @author LemonTree55
     def calc
-      calc_length
-      calc_checksum
+      headers.reverse_each do |header|
+        header.calc_length if header.respond_to?(:calc_length)
+        header.calc_checksum if header.respond_to?(:calc_checksum)
+      end
     end
 
-    # Get packet body
-    # @return [Types]
+    # Get packet body. If packet (i.e. last header) has no +:body+ field, return +nil+.
+    # @return [Headerable,BinStruct::String,nil]
     def body
-      last_header[:body] if last_header.respond_to? :body
+      last_header[:body] if last_header.respond_to?(:body)
     end
 
     # Set packet body
-    # @param [String] str
+    # @param [String] str Binary string
     # @return [void]
+    # @raise [Error] Packet (i.e. last header) has no +:body+ field.
+    # @note To set a {Headerable} object, prefer #{<<}
+    # @see #<<
+    # @since 4.1.0 raise {Error} if no body on packet
     def body=(str)
+      raise Error, 'no body in last headeré' unless last_header.respond_to?(:body)
+
       last_header.body = str
     end
 
@@ -229,7 +262,7 @@ module PacketGen
     alias write to_f
 
     # Send packet on wire. Use first header +#to_w+ method.
-    # @param [String] iface interface name. Default to first non-loopback interface
+    # @param [String,nil] iface interface name. Default to first non-loopback interface
     # @param [Boolean] calc if +true+, call {#calc} on packet before sending it.
     # @param [Integer] number number of times to send the packets
     # @param [Integer,Float] interval time, in seconds, between sending 2 packets
@@ -239,12 +272,12 @@ module PacketGen
     def to_w(iface=nil, calc: true, number: 1, interval: 1)
       iface ||= PacketGen.default_iface
 
-      if first_header.respond_to? :to_w
+      if first_header.respond_to?(:to_w)
         self.calc if calc
 
         number.times do
           first_header.to_w(iface)
-          sleep interval if number > 1
+          sleep(interval) if number > 1
         end
       else
         type = first_header.protocol_name
@@ -257,12 +290,19 @@ module PacketGen
     # @param [Boolean] parsing set to +true+ to not update last current header field
     #    from binding with first other's one. Use only when current header field
     #    has its value set accordingly.
-    # @return [self] +self+ with new headers from +other+
+    # @return [self] +self+ updated with new headers from +other+
     # @raise [BindingError] do not known how to encapsulate
     # @since 1.1.0
+    # @example
+    #   # Create a first IP packet
+    #   ip1 = PacketGen::Packet.gen('IP', id: 1)
+    #   # Create second IP packet, to encapsulate in first
+    #   ip2 = PacketGen.gen('IP', id: 2)
+    #   ip1.encapsulate(ip2)
+    #   ip1.ip(2) == ip2.ip
     def encapsulate(other, parsing: false)
       other.headers.each_with_index do |h, i|
-        add_header h, parsing: i.positive? || parsing
+        add_header(h, parsing: i.positive? || parsing)
       end
     end
 
@@ -272,6 +312,12 @@ module PacketGen
     # @raise [FormatError] any headers not in +self+
     # @raise [BindingError] removed headers result in an unknown binding
     # @since 1.1.0
+    # @example
+    #  # IP/IP encapsulation
+    #  pkt = PacketGen::Packet.gen('IP', id: 1).add('IP', id:2)
+    #  # Remove outer IP header
+    #  pkt.decapsulate(pkt.ip(1))
+    #  pkt.ip.id #=> 2
     def decapsulate(*hdrs)
       hdrs.each do |hdr|
         prev_hdr = previous_header(hdr)
@@ -280,14 +326,15 @@ module PacketGen
         add_header(next_hdr, previous_header: prev_hdr) if prev_hdr && next_hdr
       end
       invalidate_header_cache
+      self
     rescue ArgumentError => e
       raise FormatError, e.message
     end
 
     # Parse a binary string and populate Packet from it.
     # @param [String] binary_str
-    # @param [String,nil] first_header First protocol header. +nil+ means discover it!
-    # @return [Packet] self
+    # @param [String,nil] first_header First protocol header name. +nil+ means discover it!
+    # @return [self]
     # @raise [ParseError] +first_header+ is an unknown header
     # @raise [BindingError] unknwon binding between some headers
     def parse(binary_str, first_header: nil)
@@ -299,7 +346,7 @@ module PacketGen
         raise ParseError, "cannot identify first header in string: #{binary_str.inspect}" if first_header.nil?
       end
 
-      add first_header
+      add(first_header)
       headers[-1, 1] = last_header.read(binary_str)
 
       # Decode upper headers recursively
@@ -317,12 +364,14 @@ module PacketGen
       str << Inspect.inspect_body(body)
     end
 
+    # Check equality at binary level
     # @param [Packet] other
     # @return [Boolean]
     def ==(other)
       to_s == other.to_s
     end
 
+    # +true+ if {#==} is +true+ with another packet, or if +other+ is a protocol name String, whose protocol is in Packet.
     # @param [Packet] other
     # @return [Boolean]
     # @since 3.1.2
@@ -331,14 +380,15 @@ module PacketGen
       when PacketGen::Packet
         self == other
       when String
-        is? other
+        is?(other)
       else
         false
       end
     end
 
-    # Invert all possible fields in packet to create a reply.
+    # Invert all possible attributes in packet to create a reply.
     # @return [self]
+    # @note Only modify headers responding to +#reply!+.
     # @since 2.7.0
     def reply!
       headers.each do |header|
@@ -350,12 +400,32 @@ module PacketGen
     # Forge a new packet from current one with all possible fields
     # inverted. The new packet may be a reply to current one.
     # @return [Packet]
+    # @note Only modify headers responding to +#reply!+.
     # @since 2.7.0
     def reply
       pkt = dup
       pkt.reply!
     end
 
+    # Append an already defined header to packet
+    # @param [Headerable] header
+    # @return [self]
+    # @raise [ArgumentError] unknown protocol
+    # @raise [BindingError] unknown binding
+    # @example
+    #  pkt = PacketGen.gen('Eth')
+    #  # Add a new header from its type
+    #  pkt.add('IP')
+    #  # Add a new pre-generated header
+    #  pkt << PacketGen::Header::TCP.new
+    # @see #add
+    # @since 4.1.0
+    # @author LemonTree55
+    def <<(header)
+      add_header(header)
+      self
+    end
+
     private
 
     # Dup +@headers+ instance variable. Internally used by +#dup+ and +#clone+
@@ -363,7 +433,7 @@ module PacketGen
     def initialize_copy(_other)
       @headers = headers.map(&:dup)
       headers.each do |header|
-        add_magic_header_method header
+        add_magic_header_method(header)
       end
       invalidate_header_cache
     end
@@ -410,17 +480,20 @@ module PacketGen
     end
 
     # @overload header(klass, layer=1)
+    #  Get a header given its class and its layer (example: IP-in-IP encapsulation)
     #  @param [Class] klass
     #  @param [Integer] layer
     # @overload header(klass, options={})
+    #  Get a header given its class, and set some attributes
     #  @param [String] klass
-    #  @param [Hash] options
-    #  @raise [ArgumentError] unknown option
-    # @return [Header::Base]
+    #  @param [Hash] options attributes to set
+    #  @raise [ArgumentError] unknown attribute
+    # @return [Header::Base,nil]
     def header(klass, arg)
       layer = arg.is_a?(Integer) ? arg : 1
       header = find_header(klass, layer)
-      return header unless arg.is_a? Hash
+      return nil if header.nil?
+      return header unless arg.is_a?(Hash)
 
       arg.each do |key, value|
         raise ArgumentError, "unknown #{key} attribute for #{klass}" unless header.respond_to?(:"#{key}=")
@@ -434,12 +507,14 @@ module PacketGen
     # Get header from cache, or find it in packet
     # @param [Class] klass
     # @param [Integer] layer
-    # @return [Header::Base]
+    # @return [Header::Base,nil]
     def find_header(klass, layer)
       header = fetch_header_from_cache(klass, layer)
       return header if header
 
-      header = headers.select { |h| h.is_a? klass }[layer - 1]
+      header = headers.select { |h| h.is_a?(klass) }[layer - 1]
+      return nil if header.nil?
+
       add_header_to_cache(header, klass, layer)
       header
     end
@@ -468,9 +543,9 @@ module PacketGen
       header.packet = self
       headers << header unless previous_header
 
-      return if respond_to? header.method_name
+      return if respond_to?(header.method_name)
 
-      add_magic_header_method header
+      add_magic_header_method(header)
     end
 
     # Bind +header+ to +prev_header+.
@@ -497,7 +572,7 @@ module PacketGen
 
     # Try to guess header from +binary_str+
     # @param [String] binary_str
-    # @return [String] header/protocol name
+    # @return [String,nil] header/protocol name, or nil if cannot be guessed
     def guess_first_header(binary_str)
       first_header = nil
       Header.all.each do |hklass|
@@ -529,7 +604,7 @@ module PacketGen
         nheader = nheader.read(last_known_hdr.body)
         next unless nheader.parse?
 
-        add_header nheader, parsing: true
+        add_header(nheader, parsing: true)
         break if last_header == last_known_hdr
       end
     end

data/lib/packetgen/pcap.rb

@@ -8,8 +8,7 @@
 require_relative 'pcaprub_wrapper'
 
 module PacketGen
-  # Module to read PCAP files
-  # @author Sylvain Daubert
+  # Module to read/write PCAP files
   # @api private
   # @since 3.1.4
   module Pcap
@@ -17,14 +16,26 @@ module PacketGen
     # @param [String] filename
     # @return [Array<Packet>]
     # @author Kent Gruber
+    # @author LemonTree55
     def self.read(filename)
       packets = []
-      PCAPRUBWrapper.read_pcap(filename: filename) do |packet|
-        next unless (packet = PacketGen.parse(packet.to_s))
+      PCAPRUBWrapper.read_pcap(filename: filename) do |raw_packet|
+        packet = PacketGen.parse(raw_packet.to_s)
+        next if packet.nil?
 
         packets << packet
       end
       packets
     end
+
+    # Write binary packets to a PCAP file
+    # @param [String] filename
+    # @param [Array<String>] packets
+    # @return [void]
+    # @since 4.0.0
+    # @author LemonTree55
+    def self.write(filename, packets)
+      PCAPRUBWrapper.pcap_write(filename, packets.map(&:to_s))
+    end
   end
 end

data/lib/packetgen/pcapng/block.rb

@@ -10,63 +10,65 @@ module PacketGen
   module PcapNG
     # @abstract Base class for all block types
     # @author Sylvain Daubert
-    class Block < Types::Fields
+    # @author LemonTree55
+    class Block < BinStruct::Struct
       # @return [:little, :big]
       attr_accessor :endian
 
       # @!attribute type
       #  32-bit block type
       #  @return [Integer]
-      define_field :type, Types::Int32
+      define_attr :type, BinStruct::Int32
       # @!attribute block_len
       #  32-bit block length
       #  @return [Integer]
-      define_field :block_len, Types::Int32
-      # @!attribute block_len
+      define_attr :block_len, BinStruct::Int32
+      # @!attribute block_len2
       #  32-bit block length
       #  @return [Integer]
-      define_field :block_len2, Types::Int32
+      define_attr :block_len2, BinStruct::Int32
 
       def initialize(options={})
         super
+        endianness(options[:endian] || :little)
+        recalc_block_len
       end
 
       # Has this block option?
       # @return [Boolean]
       # @since 2.7.0
       def options?
-        @fields.key?(:options) && @fields[:options].sz.positive?
+        @attributes.key?(:options) && @attributes[:options].sz.positive?
       end
 
-      # Calculate block length and update :block_len and block_len2 fields
+      # Calculate block length and update +block_len+ and +block_len2+ fields
       # @return [void]
       def recalc_block_len
-        len = fields.map { |f| @fields[f].to_s }.join.size
+        len = attributes.map { |f| @attributes[f].to_s }.join.size
         self.block_len = self.block_len2 = len
       end
 
       # Pad given field to 32 bit boundary, if needed
-      # @param [Array<Symbol>] fields block fields to pad
+      # @param [Array<Symbol>] fields fields to pad
       # @return [void]
+      # @author LemonTree55
       def pad_field(*fields)
         fields.each do |field|
-          obj = @fields[field]
-          pad_size = (obj.sz % 4).zero? ? 0 : (4 - (obj.sz % 4))
-          obj << "\x00" * pad_size
+          obj = @attributes[field]
+          obj << "\x00" * -(obj.sz % -4)
         end
       end
 
       private
 
       # Set the endianness for the various Int classes handled by self.
-      # Must be called by all subclass #initialize method.
       # @param [:little, :big] endian
       # @return [:little, :big] returns endian
       def endianness(endian)
         raise ArgumentError, "unknown endianness for #{self.class}" unless %i[little big].include?(endian)
 
         @endian = endian
-        @fields.each_value { |v| v.endian = endian if v.is_a?(Types::Int) }
+        @attributes.each_value { |v| v.endian = endian if v.is_a?(BinStruct::Int) }
         endian
       end
 
@@ -75,19 +77,19 @@ module PacketGen
       end
 
       def to_io(str_or_io)
-        return str_or_io if str_or_io.respond_to? :read
+        return str_or_io if str_or_io.respond_to?(:read)
 
-        StringIO.new(force_binary(str_or_io.to_s))
+        StringIO.new(str_or_io.to_s.b)
       end
 
       def remove_padding(io, data_len)
         data_pad_len = (4 - (data_len % 4)) % 4
-        io.read data_pad_len
+        io.read(data_pad_len)
         data_pad_len
       end
 
       def read_blocklen2_and_check(io)
-        self[:block_len2].read io.read(4)
+        self[:block_len2].read(io.read(4))
         check_len_coherency
       end
     end