packetgen 3.1.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 877d57dd457d4cde03fca6e13c0042168c8630b08073533b7b7fb95da49632a0
-  data.tar.gz: 5c18abe50abcb423edf22571e88241cddb6095a0c626fb6018bfbafac49278b1
+  metadata.gz: 36578b725eb28ace342c6468423d781158b376c16bcc8b949e1df62262aba11a
+  data.tar.gz: 6e3bbdfc313f54611b05a19a31336438fa781cce24bc19867a2e72d91bbc8f9e
 SHA512:
-  metadata.gz: '09c0197e3f3d1bf72dffbaf97abc4007902ade04b94a6893d1a79e97944e6560eb16aad024726497a064b9fdc59fed5efd8e456cffcaa3f7bf64b7b0c7a2604c'
-  data.tar.gz: 575402b40e5be3c8bf6d68e8dfd01fa3b4a9d3e917fda6cefa17b0759f99193bb69a5e3b5734cfa839e149856d7d98ea88e13bb8fa273c9ac295a94a79e7502b
+  metadata.gz: 64cfe76137b2f4f2ea1b75806019a28d63d32cb904fe3a22982d8cf5b090e3df74befd527606d250d49a2541842b2dba2c0e1060b61128ecd538b2c6c7e6d544
+  data.tar.gz: 9700b4a0f455d5b6918d8a0eac2309100e29db650eb2f88469a54241b8b5888d2605571883aaebe187d69db97c0e0e380ba35c4325a6bd420c492ec7dc619c55

data/README.md

@@ -164,7 +164,7 @@ PacketGen provides a plugin system (see [wiki](https://github.com/sdaubert/packe
 Available plugins (available as gem) are:
 
 * [packetgen-plugin-ipsec](https://github.com/sdaubert/packetgen-plugin-ipsec): add support for ESP and IKEv2 protocols. Before PacketGen3, these protocols were included in packetgen.
-* [packetgen-plugin-smb](https://github.com/sdaubert/packetgen-plugin-smb): add (limited) support for SMB protocol suite.
+* [packetgen-plugin-smb](https://github.com/sdaubert/packetgen-plugin-smb): add support for SMB protocol suite.
 
 ## See also
 

data/lib/packetgen/header/dhcp/option.rb

@@ -56,19 +56,47 @@ module PacketGen
         'end' => 255
       }.freeze
 
-      # Option class with string value
+      # @!parse
+      #  # Option class with string value. {#type #type} and {#length #length} are
+      #  # {Types::Int8}.
+      #  #
+      #  # See also {IPAddrOption}, {Int8Option}, {Int16Option} and {Int32Option}.
+      #  # @since 2.2.0
+      #  # @since 3.1.0 subclass of {Types::AbstractTLV}
+      #  class Option < Types::AbstractTLV; end
+      # @private
       Option = Types::AbstractTLV.create
       Option.define_type_enum DHCP_OPTIONS
-      # Option class with IP address value
+      # @!parse
+      #  # {Option} class with IP address value
+      #  # @since 2.2.0
+      #  # @since 3.1.0 subclass of {Types::AbstractTLV}
+      #  class IPAddrOption < Types::AbstractTLV; end
+      # @private
       IPAddrOption = Types::AbstractTLV.create(value_class: IP::Addr)
       IPAddrOption.define_type_enum DHCP_OPTIONS
-      # Option class with int8 value
+      # @!parse
+      #  # {Option} class with int8 value
+      #  # @since 2.2.0
+      #  # @since 3.1.0 subclass of {Types::AbstractTLV}
+      #  class Int8Option < Types::AbstractTLV; end
+      # @private
       Int8Option = Types::AbstractTLV.create(value_class: Types::Int8)
       Int8Option.define_type_enum DHCP_OPTIONS
-      # Option class with int16 value
+      # @!parse
+      #  # {Option} class with int16 value
+      #  # @since 2.2.0
+      #  # @since 3.1.0 subclass of {Types::AbstractTLV}
+      #  class Int16Option < Types::AbstractTLV; end
+      # @private
       Int16Option = Types::AbstractTLV.create(value_class: Types::Int16)
       Int16Option.define_type_enum DHCP_OPTIONS
-      # Option class with int32 value
+      # @!parse
+      #  # {Option} class with int32 value
+      #  # @since 2.2.0
+      #  # @since 3.1.0 subclass of {Types::AbstractTLV}
+      #  class Int32Option < Types::AbstractTLV; end
+      # @private
       Int32Option = Types::AbstractTLV.create(value_class: Types::Int32)
       Int32Option.define_type_enum DHCP_OPTIONS
 

data/lib/packetgen/header/dhcp/options.rb

@@ -8,7 +8,7 @@
 module PacketGen
   module Header
     class DHCP
-      # Container class for DHCP Options
+      # Container class for {Option DHCP Options}.
       #
       # == Add DHCP options to an +Options+ instance
       #   options = PacketGen::Header::DHCP::Options.new

data/lib/packetgen/header/dns.rb

@@ -43,10 +43,14 @@ module PacketGen
     # == DNS attributes
     #  dns.id = 0x1234
     #  dns.qr = false
-    #  dns.opcode = 0xe
-    #  dns.opcode = 'query'
+    #  # opcode may be set as an Integer (all values are possible)
+    #  # or as a String (only keys from PacketGen::Header::DNS::OPCODES)
+    #  dns.opcode = 0xe       # set as integer, value not defined in standard
+    #  dns.opcode = 'query'   # set as string
     #  dns.aa = dns.tc = dns.rd = dns.ra = false
-    #  dns.rcode = 0xa
+    #  # rcode may be set as an Integer (all values are possible)
+    #  # or as a String (only keys from PacketGen::Header::DNS::RCODES)
+    #  dns.rcode = 11
     #  dns.rcode = 'refused'
     #  dns.qdcount = 123
     #  dns.ancount = 0x1234
@@ -71,8 +75,8 @@ module PacketGen
     #  dns.qd.push({ rtype: 'Question', name: 'example.net', type: 'AAAA' })
     #
     # == Add a ressource record to a DNS section
-    # Adding a {RR} with {RRSection#<<} automagically increments section counter.
-    # To not modify it, use {RRSection#push}
+    # Adding a {RR} with {RRSection#<< RRSection#<<} automagically increments section counter.
+    # To not modify it, use {RRSection#push RRSection#push}
     #  # add a RR to answer section. Increment ancount
     #  dns.an << PacketGen::Header::DNS::RR.new(dns, name: 'example.net', rdata: IPAddr.new('1.2.3.4').hton)
     #  # or
@@ -89,7 +93,9 @@ module PacketGen
     #  # or
     #  dns.ar << { rtype: 'OPT', udp_size: 4096, ext_rcode: 43 }
     #  # add an option to OPT record
-    #  dns.ar.last.options << PacketGen::Header::DNS::Option.new(code: 48, length: 2, data: "12")
+    #  dns.ar.last.options << PacketGen::Header::DNS::Option.new(code: 48, data: '12')
+    #  # or
+    #  dns.ar.last.options << { code: 48, data: '12' }
     # @author Sylvain Daubert
     # @since 1.3.0
     class DNS < Base

data/lib/packetgen/header/dns/opt.rb

@@ -14,9 +14,12 @@ module PacketGen
       #
       # a OPT record may contain zero or more {Option options} in its {#rdata}.
       # @author Sylvain Daubert
+      # @since 1.3.0
+      # @since 3.1.1 {#options} is a {ArrayOfOptions}
       class OPT < RR
-        # @return [Array<Option>]
-        attr_reader :options
+        # @!attribute options
+        #   @return [ArrayOfOptions]
+        define_field_after :rdata, :options, ArrayOfOptions
 
         # @param [DNS] dns
         # @param [Hash] options
@@ -35,7 +38,6 @@ module PacketGen
         def initialize(dns, options={})
           opts = { name: '.', rrclass: 512, type: 41 }.merge!(options)
           super dns, opts
-          @options = []
 
           self.udp_size = options[:udp_size] if options[:udp_size]
           self.ext_rcode = options[:ext_rcode] if options[:ext_rcode]
@@ -120,22 +122,11 @@ module PacketGen
           do? ? 'do' : 'none'
         end
 
-        # @return [String]
-        def human_options
-          str = @options.map(&:to_human).join(';')
-          str.empty? ? 'none' : str
-        end
-
         # @return [String]
         def to_human
           "#{name} #{human_type} UDPsize:#{udp_size} " \
           "extRCODE:#{ext_rcode} EDNSversion:#{version} flags:#{human_flags} " \
-          "options:#{human_options}"
-        end
-
-        # @return [String]
-        def to_s
-          super + @options.map(&:to_s).join
+          "options:#{options.empty? ? 'none' : options.to_human}"
         end
       end
     end

data/lib/packetgen/header/dns/option.rb

@@ -8,9 +8,32 @@
 module PacketGen
   module Header
     class DNS
-      # DNS option
+      # @!parse
+      #  # DNS option is a TLV object:
+      #  # * {#code} is a {Types::Int16},
+      #  # * {#length #length} is a {Types::Int16},
+      #  # * {#data} is a {Types::String}.
+      #  #
+      #  # @since 1.3.0
+      #  # @since 3.1.0 defined with {Types::AbstractTLV}
+      #  # @!parse class Option < Types::AbstractTLV; end
+      #  # @!attribute code
+      #  #   Alias for {#type}
+      #  #   @return [Integer]
+      #  # @!attribute data
+      #  #   Alias for {#value}
+      #  #   @return [Types::String]
+      #  class Option < Types::AbstractTLV; end
+      # @private
       Option = Types::AbstractTLV.create(type_class: Types::Int16,
-                                         length_class: Types::Int16)
+                                         length_class: Types::Int16,
+                                         aliases: { code: :type, data: :value })
+
+      # Array of {Option}.
+      # @since 3.1.1
+      class ArrayOfOptions < Types::Array
+        set_of Option
+      end
     end
   end
 end

data/lib/packetgen/header/dot11/element.rb

@@ -9,9 +9,14 @@
 module PacketGen
   module Header
     class Dot11
-      # IEEE 802.11 information element
-      #
-      # An {Element} is a piece of data contained in a Dot11 management frame.
+      # @!parse
+      #  # IEEE 802.11 information element
+      #  #
+      #  # An {Element} is a piece of data contained in a Dot11 management frame.
+      #  # @since 1.4.0
+      #  # @since 3.1.0 subclass of {Types::AbstractTLV}
+      #  class Element < Types::AbstractTLV; end
+      # @private
       Element = Types::AbstractTLV.create
 
       class Element
@@ -35,6 +40,12 @@ module PacketGen
         }.freeze
       end
       Element.define_type_enum Element::TYPES.invert
+
+      # Array of {Element}.
+      # @since 3.1.1
+      class ArrayOfElements < Types::Array
+        set_of Element
+      end
     end
   end
 end

data/lib/packetgen/header/dot11/management.rb

@@ -54,8 +54,7 @@ module PacketGen
         # @since 2.1.3
         def add_element(type:, value:)
           if self[:body].is_a? SubMngt
-            element = Element.new(type: type, value: value)
-            self[:body].elements << element
+            self[:body].elements << { type: type, value: value }
           else
             raise FormatError, 'Before adding an Element, you have to add a Dot11::SubMngt subclass instance'
           end

data/lib/packetgen/header/dot11/sub_mngt.rb

@@ -19,61 +19,31 @@ module PacketGen
       # @author Sylvain Daubert
       class SubMngt < Base
         # @return [Array<Element>]
-        attr_accessor :elements
-
-        # @param [Hash] options
-        # @see Base#initialize
-        def initialize(options={})
-          super
-          @elements = []
-        end
-
-        # Populate object from binary string
-        # @param [String] str
-        # @return [SubMngt] self
-        def read(str)
-          super
-          read_elements str[sz, str.size] || ''
-          self
-        end
-
-        # @return [String]
-        def to_s
-          super + @elements.map(&:to_s).join
-        end
+        define_field :elements, ArrayOfElements
 
         # @return [String]
-        def inspect
-          str = super
-          str << Inspect.dashed_line('Dot11 Elements', 2)
-          @elements.each do |el|
-            str << Inspect.shift_level(2) << el.to_human << "\n"
-          end
-          str
-        end
+        #def inspect
+        #  str = super
+        #  str << Inspect.dashed_line('Dot11 Elements', 2)
+        #  @elements.each do |el|
+        #    str << Inspect.shift_level(2) << el.to_human << "\n"
+        #  end
+        #  str
+        #end
 
         # Add an {Element} to header
         # @param [Integer,String] type element type
         # @param [Object] value element value
         # @return [self]
         # @since 2.1.3
+        # @since 3.1.1 #elements in no more an Array but an {ArrayOfElements}
+        # @deprecated Prefer use of +submngt.element << {type: type, value: value}+
         def add_element(type:, value:)
+          Deprecation.deprecated(self.class, __method__, 'elements')
           element = Element.new(type: type, value: value)
-          @elements << element
+          self.elements << element
           self
         end
-
-        private
-
-        def read_elements(str)
-          start = 0
-          elsz = Element.new.sz
-          while str.size - start >= elsz
-            el = Element.new.read(str[start, str.size])
-            @elements << el
-            start += el.sz
-          end
-        end
       end
 
       # IEEE 802.11 Association Request frame
@@ -87,10 +57,10 @@ module PacketGen
       class AssoReq < SubMngt
         # @!attribute cap
         #  @return [Integer] 16-bit capabillities word
-        define_field :cap, Types::Int16le
+        define_field_before :elements, :cap, Types::Int16le
         # @!attribute listen_interval
         #  @return [Integer] 16-bit listen interval value
-        define_field :listen_interval, Types::Int16le, default: 0x00c8
+        define_field_before :elements, :listen_interval, Types::Int16le, default: 0x00c8
       end
       Header.add_class AssoReq
       Management.bind AssoReq, type: 0, subtype: 0
@@ -107,13 +77,13 @@ module PacketGen
       class AssoResp < SubMngt
         # @!attribute cap
         #  @return [Integer] 16-bit capabillities word
-        define_field :cap, Types::Int16le
+        define_field_before :elements, :cap, Types::Int16le
         # @!attribute status
         #  @return [Integer] 16-bit status word
-        define_field :status, Types::Int16le
+        define_field_before :elements, :status, Types::Int16le
         # @!attribute aid
         #  @return [Integer] 16-bit AID word
-        define_field :aid, Types::Int16le
+        define_field_before :elements, :aid, Types::Int16le
       end
       Header.add_class AssoResp
       Management.bind AssoResp, type: 0, subtype: 1
@@ -130,7 +100,7 @@ module PacketGen
       class ReAssoReq < AssoReq
         # @!attribute current_ap
         #  @return [Eth::MAcAddr]
-        define_field :current_ap, Eth::MacAddr
+        define_field_before :elements, :current_ap, Eth::MacAddr
       end
       Header.add_class ReAssoReq
       Management.bind ReAssoReq, type: 0, subtype: 2
@@ -172,13 +142,13 @@ module PacketGen
       class ProbeResp < SubMngt
         # @!attribute timestamp
         #  @return [Integer] 64-bit timestamp
-        define_field :timestamp, Types::Int64le
+        define_field_before :elements, :timestamp, Types::Int64le
         # @!attribute beacon_interval
         #  @return [Integer] 16-bit beacon interval value
-        define_field :beacon_interval, Types::Int16le, default: 0x0064
+        define_field_before :elements, :beacon_interval, Types::Int16le, default: 0x0064
         # @!attribute cap
         #  @return [Integer] 16-bit capabillities word
-        define_field :cap, Types::Int16le
+        define_field_before :elements, :cap, Types::Int16le
       end
       Header.add_class ProbeResp
       Management.bind ProbeResp, type: 0, subtype: 5
@@ -195,13 +165,13 @@ module PacketGen
       class Beacon < SubMngt
         # @!attribute timestamp
         #  @return [Integer] 64-bit timestamp
-        define_field :timestamp, Types::Int64le
+        define_field_before :elements, :timestamp, Types::Int64le
         # @!attribute interval
         #  @return [Integer] 16-bit interval value
-        define_field :interval, Types::Int16le, default: 0x64
+        define_field_before :elements, :interval, Types::Int16le, default: 0x64
         # @!attribute cap
         #  @return [Integer] 16-bit capabillities word
-        define_field :cap, Types::Int16le
+        define_field_before :elements, :cap, Types::Int16le
       end
       Header.add_class Beacon
       Management.bind Beacon, type: 0, subtype: 8
@@ -226,7 +196,7 @@ module PacketGen
       class Disas < SubMngt
         # @!attribute reason
         #  @return [Integer] 16-bit reason value
-        define_field :reason, Types::Int16le
+        define_field_before :elements, :reason, Types::Int16le
       end
       Header.add_class Disas
       Management.bind Disas, type: 0, subtype: 10
@@ -243,13 +213,13 @@ module PacketGen
       class Auth < SubMngt
         # @!attribute algo
         #  @return [Integer] 16-bit algo value
-        define_field :algo, Types::Int16le
+        define_field_before :elements, :algo, Types::Int16le
         # @!attribute seqnum
         #  @return [Integer] 16-bit seqnum value
-        define_field :seqnum, Types::Int16le
+        define_field_before :elements, :seqnum, Types::Int16le
         # @!attribute status
         #  @return [Integer] 16-bit status word
-        define_field :status, Types::Int16le
+        define_field_before :elements, :status, Types::Int16le
       end
       Header.add_class Auth
       Management.bind Auth, type: 0, subtype: 11
@@ -264,7 +234,7 @@ module PacketGen
       class DeAuth < SubMngt
         # @!attribute reason
         #  @return [Integer] 16-bit reason value
-        define_field :reason, Types::Int16le
+        define_field_before :elements, :reason, Types::Int16le
       end
       Header.add_class DeAuth
       Management.bind DeAuth, type: 0, subtype: 12

data/lib/packetgen/header/ipv6/hop_by_hop.rb

@@ -8,7 +8,11 @@
 module PacketGen
   module Header
     class IPv6
-      # Option for {HopByHop} IPv6 extension header.
+      # @!parse
+      #  # Option for {HopByHop} IPv6 extension header.
+      #  # @since 3.1.0 subclass of {Types::AbstractTLV}
+      #  class Option <AbstractTLV; end
+      # @private
       Option = Types::AbstractTLV.create
 
       class Option

data/lib/packetgen/types/abstract_tlv.rb

@@ -40,20 +40,40 @@ module PacketGen
     #   tlv = MyTLV.new(type: 1, value: '1.2.3.4')
     #   tlv.type        #=> 1
     #   tlv.length      #=> 4
-    #   tlv.value       #=> 42
+    #   tlv.value       #=> '1.2.3.4'
     #   tlv.to_s        #=> "\x00\x01\x00\x04\x01\x02\x03\x04"
+    #
+    # Some aliases may also be defined. For example, to create a TLV type
+    # whose +type+ field should be named +code+:
+    #   MyTLV = PacketGen::Types::AbstractTLV.create(type_class: PacketGen::Types::Int16,
+    #                                                length_class: PacketGen::Types::Int16,
+    #                                                aliases: { code: :type })
+    #   tlv = MyTLV.new(code: 1, value: 'abcd')
+    #   tlv.code        #=> 1
+    #   tlv.type        #=> 1
+    #   tlv.length      #=> 4
+    #   tlv.value       #=> 'abcd'
+    #
     # @author Sylvain Daubert
     # @since 3.1.0
+    # @since 3.1.1 add +:aliases+ keyword to {#initialize}
     class AbstractTLV < Types::Fields
+      class <<self
+        # @return [Hash]
+        attr_accessor :aliases
+      end
+      self.aliases = {}
+
       # Generate a TLV class
       # @param [Class] type_class Class to use for +type+
       # @param [Class] length_class Class to use for +length+
       # @param [Class] value_class Class to use for +value+
       # @return [Class]
-      def self.create(type_class: Int8Enum, length_class: Int8, value_class: String)
+      def self.create(type_class: Int8Enum, length_class: Int8, value_class: String, aliases: {})
         raise Error, '.create cannot be called on a subclass of PacketGen::Types::AbstractTLV' unless self.equal? AbstractTLV
 
         klass = Class.new(self)
+        klass.aliases = aliases
 
         if type_class < Enum
           klass.define_field :type, type_class, enum: {}
@@ -63,6 +83,13 @@ module PacketGen
         klass.define_field :length, length_class
         klass.define_field :value, value_class
 
+        aliases.each do |al, orig|
+          klass.instance_eval do
+            alias_method al, orig if klass.method_defined?(orig)
+            alias_method :"#{al}=", :"#{orig}=" if klass.method_defined?(:"#{orig}=")
+          end
+        end
+
         klass
       end
       # @!attribute type
@@ -90,6 +117,10 @@ module PacketGen
       # @option options [Integer] :length
       # @option options [Object] :value
       def initialize(options={})
+        self.class.aliases.each do |al, orig|
+          options[orig] = options[al] if options.key?(al)
+        end
+
         super
         # used #value= defined below, which set length if needed
         self.value = options[:value] if options[:value]

data/lib/packetgen/version.rb

@@ -10,5 +10,5 @@
 # @author Sylvain Daubert
 module PacketGen
   # PacketGen version
-  VERSION = '3.1.0'
+  VERSION = '3.1.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: packetgen
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.1.1
 platform: ruby
 authors:
 - Sylvain Daubert
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-11-28 00:00:00.000000000 Z
+date: 2018-12-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: interfacez