packetgen 3.3.3 → 4.0.0

data/lib/packetgen/packet.rb

@@ -61,20 +61,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 +112,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
@@ -142,7 +149,7 @@ module PacketGen
       # 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 +166,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
@@ -173,7 +180,7 @@ module PacketGen
     # @return [Boolean]
     # @raise [ArgumentError] unknown protocol
     def is?(protocol)
-      klass = check_protocol protocol
+      klass = check_protocol(protocol)
       headers.any?(klass)
     end
 
@@ -181,7 +188,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,21 +196,24 @@ 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]
     def body
-      last_header[:body] if last_header.respond_to? :body
+      last_header[:body] if last_header.respond_to?(:body)
     end
 
     # Set packet body
@@ -229,7 +239,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 +249,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 +267,12 @@ 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
     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
 
@@ -286,8 +296,8 @@ module PacketGen
 
     # 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 +309,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 +327,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+ is {#==} 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,13 +343,13 @@ 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]
     # @since 2.7.0
     def reply!
@@ -363,7 +375,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 +422,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 +449,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 +485,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 +514,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 +546,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,64 @@ module PacketGen
   module PcapNG
     # @abstract Base class for all block types
     # @author Sylvain Daubert
-    class Block < Types::Fields
+    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 +76,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))
       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

data/lib/packetgen/pcapng/epb.rb

@@ -34,29 +34,29 @@ module PacketGen
       # @!attribute interface_id
       #  32-bit interface ID
       #  @return [Integer]
-      define_field_before :block_len2, :interface_id, Types::Int32, default: 0
+      define_attr_before :block_len2, :interface_id, BinStruct::Int32, default: 0
       # @!attribute tsh
       #  high 32-bit timestamp value
       #  @return [Integer]
-      define_field_before :block_len2, :tsh, Types::Int32, default: 0
+      define_attr_before :block_len2, :tsh, BinStruct::Int32, default: 0
       # @!attribute tsl
       #  low 32-bit imestamp value
       #  @return [Integer]
-      define_field_before :block_len2, :tsl, Types::Int32, default: 0
+      define_attr_before :block_len2, :tsl, BinStruct::Int32, default: 0
       # @!attribute cap_len
       #  32-bit capture length
       #  @return [Integer]
-      define_field_before :block_len2, :cap_len, Types::Int32, default: 0
+      define_attr_before :block_len2, :cap_len, BinStruct::Int32, default: 0
       # @!attribute orig_len
       #  32-bit original length
       #  @return [Integer]
-      define_field_before :block_len2, :orig_len, Types::Int32, default: 0
+      define_attr_before :block_len2, :orig_len, BinStruct::Int32, default: 0
       # @!attribute data
-      #  @return [Types::String]
-      define_field_before :block_len2, :data, Types::String
+      #  @return [BinStruct::String]
+      define_attr_before :block_len2, :data, BinStruct::String
       # @!attribute options
-      #  @return [Types::String]
-      define_field_before :block_len2, :options, Types::String
+      #  @return [BinStruct::String]
+      define_attr_before :block_len2, :options, BinStruct::String
 
       # @param [Hash] options
       # @option options [:little, :big] :endian set block endianness
@@ -74,8 +74,6 @@ module PacketGen
       # @option options [Integer] :block_len2 block total length
       def initialize(options={})
         super
-        endianness(options[:endian] || :little)
-        recalc_block_len
         self.type = options[:type] || PcapNG::EPB_TYPE.to_i
       end
 
@@ -87,9 +85,9 @@ module PacketGen
         return self if io.eof?
 
         %i[type block_len interface_id tsh tsl cap_len orig_len].each do |attr|
-          self[attr].read io.read(self[attr].sz)
+          self[attr].read(io.read(self[attr].sz))
         end
-        self[:data].read io.read(self.cap_len)
+        self[:data].read(io.read(self.cap_len))
         read_options(io)
         read_blocklen2_and_check(io)
 
@@ -115,7 +113,7 @@ module PacketGen
       # Return the object as a String
       # @return [String]
       def to_s
-        pad_field :data, :options
+        pad_field(:data, :options)
         recalc_block_len
         super
       end
@@ -133,7 +131,7 @@ module PacketGen
       def read_options(io)
         data_pad_len = remove_padding(io, self.cap_len)
         options_len = self.block_len - self.cap_len - data_pad_len - MIN_SIZE
-        self[:options].read io.read(options_len)
+        self[:options].read(io.read(options_len))
       end
     end
   end

data/lib/packetgen/pcapng/file.rb

@@ -140,35 +140,6 @@ module PacketGen
         @sections.clear
       end
 
-      # @deprecated
-      #  Prefer use of {#to_a} or {#to_h}.
-      # Translates a {File} into an array of packets.
-      # @param [Hash] options
-      # @option options [String] :file if given, object is cleared and filename
-      #   is analyzed before generating array. Else, array is generated from +self+
-      # @option options [Boolean] :keep_timestamps if +true+ (default value: +false+),
-      #   generates an array of hashes, each one with timestamp as key and packet
-      #   as value. There is one hash per packet.
-      # @return [Array<Packet>,Array<Hash>]
-      def file_to_array(options={})
-        Deprecation.deprecated(self.class, __method__)
-
-        file = options[:file] || options[:filename]
-        reread file
-
-        ary = []
-        blk = if options[:keep_timestamps] || options[:keep_ts]
-                proc { |pkt| { pkt.timestamp => pkt.data.to_s } }
-              else
-                proc { |pkt| pkt.data.to_s }
-              end
-        each_packet_with_interface do |pkt, _itf|
-          ary << blk.call(pkt)
-        end
-
-        ary
-      end
-
       # Translates a {File} into an array of packets.
       # @return [Array<Packet>]
       # @since 3.1.6
@@ -223,41 +194,6 @@ module PacketGen
         self.to_file(filename.to_s, append: true)
       end
 
-      # @deprecated Prefer use of {#read_array} or {#read_hash}.
-      # @overload array_to_file(ary)
-      #  Update {File} object with packets.
-      #  @param [Array] ary as generated by {#file_to_array} or Array of Packet objects.
-      #                 Update {File} object without writing file on disk
-      #  @return [self]
-      # @overload array_to_file(options={})
-      #  Update {File} and/or write it to a file
-      #  @param [Hash] options
-      #  @option options [String] :file file written on disk only if given
-      #  @option options [Array] :array can either be an array of packet data,
-      #                                 or a hash-value pair of timestamp => data.
-      #  @option options [Time] :timestamp set an initial timestamp
-      #  @option options [Integer] :ts_inc set the increment between timestamps.
-      #                                    Defaults to 1
-      #  @option options [Boolean] :append if +true+, append packets to the end of
-      #                                    the file
-      #  @return [Array] see return value from {#to_file}
-      def array_to_file(options={})
-        filename, ary, ts, ts_inc, append = array_to_file_options(options)
-
-        section = create_new_shb_section
-
-        ary.each do |pkt|
-          classify_block(section, epb_from_pkt(pkt, section, ts))
-          ts += ts_inc
-        end
-
-        if filename
-          self.to_f(filename, append: append)
-        else
-          self
-        end
-      end
-
       # Update current object from an array of packets
       # @param [Array<Packet>] packets
       # @param [Time, nil] timestamp initial timestamp, used for first packet
@@ -335,13 +271,13 @@ module PacketGen
       # @param [IO] io stream from which parse SHB
       # @return [SHB]
       def parse_shb(shb, io)
-        type = Types::Int32.new(0, shb.endian).read(io.read(4))
+        type = BinStruct::Int32.new(value: 0, endian: shb.endian).read(io.read(4))
         io.seek(-4, IO::SEEK_CUR)
         parse(type, io, shb)
       end
 
       # Parse a block from its type
-      # @param [Types::Int32] type
+      # @param [BinStruct::Int32] type
       # @param [IO] io stream from which parse block
       # @param [SHB] shb header of current section
       # @return [Block]
@@ -352,7 +288,7 @@ module PacketGen
       end
 
       # Guess class to use from type
-      # @param [Types::Int] type
+      # @param [BinStruct::Int] type
       # @return [Block]
       def guess_block_type(type)
         BLOCK_TYPES.key?(type.to_i) ? BLOCK_TYPES[type.to_i] : UnknownBlock
@@ -376,36 +312,6 @@ module PacketGen
         end
       end
 
-      def array_to_file_options(options)
-        case options
-        when Hash
-          array_to_file_options_from_hash(options)
-        when Array
-          [nil, options, Time.now, 1, false]
-        else
-          raise ArgumentError, 'unknown argument. Need either a Hash or Array'
-        end
-      end
-
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-      # Extract and check options for #array_to_file
-      def array_to_file_options_from_hash(options)
-        %i[filename arr ts].each do |deprecated_opt|
-          Deprecation.deprecated_option(self.class, :array_to_file, deprecated_opt) if options[deprecated_opt]
-        end
-
-        filename = options[:filename] || options[:file]
-        ary = options[:array] || options[:arr]
-        raise ArgumentError, ':array parameter needs to be an array' unless ary.is_a? Array
-
-        ts = options[:timestamp] || options[:ts] || Time.now
-        ts_inc = options[:ts_inc] || 1
-        append = !options[:append].nil?
-
-        [filename, ary, ts, ts_inc, append]
-      end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-
       def create_new_shb_section
         section = SHB.new
         @sections << section