packetgen 2.1.2 → 2.1.3

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

@@ -9,6 +9,17 @@ module PacketGen
     class Dot11
 
       # IEEE 802.11 control frame header
+      #
+      # This class make a {Dot11} header with {#type} set to +1+
+      # (control frame).
+      #
+      # A IEEE 802.11 control header consists of:
+      # * a {#frame_ctrl} ({Types::Int16}),
+      # * a {#id}/duration ({Types::Int16le}),
+      # * a {#mac1} ({Eth::MacAddr}).
+      # * sometimes a {#mac2} ({Eth::MacAddr}),
+      # * a {#body} (a {Types::String} or another {Base} class),
+      # * and a Frame check sequence ({#fcs}, of type {Types::Int32le}).
       # @author Sylvain Daubert
       class Control < Dot11
 
@@ -49,7 +60,6 @@ module PacketGen
           if @applicable_fields.include? :mac2
             @applicable_fields -= %i(mac2) unless SUBTYPES_WITH_MAC2.include? self.subtype
           elsif SUBTYPES_WITH_MAC2.include? self.subtype
-            sz = self.sz
             @applicable_fields[3, 0] = :mac2
           end
         end

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

@@ -9,6 +9,20 @@ module PacketGen
     class Dot11
 
       # IEEE 802.11 data frame header
+      #
+      # This class make a {Dot11} header with {#type} set to +2+
+      # (data frame).
+      #
+      # A IEEE 802.11 data header consists of:
+      # * a {#frame_ctrl} ({Types::Int16}),
+      # * a {#id}/duration ({Types::Int16le}),
+      # * a {#mac2} ({Eth::MacAddr}),
+      # * a {#mac3} ({Eth::MacAddr}),
+      # * a {#sequence_ctrl} ({Types::Int16}),
+      # * sometimes a {#mac4} ({Eth::MacAddr}),
+      # * sometimes a {#qos_ctrl} ({Types::Int16}),
+      # * a {#body} (a {Types::String} or another {Base} class),
+      # * and a Frame check sequence ({#fcs}, of type {Types::Int32le}).
       # @author Sylvain Daubert
       class Data < Dot11
 

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

@@ -9,6 +9,8 @@ module PacketGen
     class Dot11
 
       # IEEE 802.11 information element
+      #
+      # An {Element} is a piece of data contained in a Dot11 management frame.
       # @author Sylvain Daubert
       class Element < Types::TLV
         # Known element types

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

@@ -9,6 +9,33 @@ module PacketGen
     class Dot11
 
       # IEEE 802.11 management frame header
+      #
+      # This class make a {Dot11} header with {#type} set to +0+
+      # (management frame).
+      #
+      # A IEEE 802.11 management header consists of:
+      # * a {#frame_ctrl} ({Types::Int16}),
+      # * a {#id}/duration ({Types::Int16le}),
+      # * a {#mac1} ({Eth::MacAddr}).
+      # * a {#mac2} ({Eth::MacAddr}),
+      # * a {#mac3} ({Eth::MacAddr}),
+      # * a {#sequence_ctrl} ({Types::Int16}),
+      # * a {#body} (a {Types::String} or another {Base} class),
+      # * and a Frame check sequence ({#fcs}, of type {Types::Int32le}).
+      #
+      # Management frames should be constructed with more headers from 
+      # {SubMngt} subclasses.
+      #
+      # By example, build a {DeAuth} frame:
+      #   PacketGen.gen('Dot11::Management').add('Dot11::DeAuth')
+      #
+      # Some frames need to have {Element}. By example a {Beacon} frame:
+      #   pkt = PacketGen.gen('Dot11::Management', mac1: broadcast, mac2: bssid, mac3: bssid).
+      #                   add('Dot11::Beacon')
+      #   pkt.dot11_beacon.add_elements(type: 'SSID', value: ssid)
+      #   pkt.dot11_beacon.add_elements(type: 'Rates', value: "\x82\x84\x8b\x96\x12\x24\x48\x6c")
+      #   pkt.dot11_beacon.add_elements(type: 'DSset', value: "\x06")
+      #   pkt.dot11_beacon.add_elements(type: 'TIM', value: "\x00\x01\x00\x00")
       # @author Sylvain Daubert
       class Management < Dot11
 
@@ -19,6 +46,22 @@ module PacketGen
           @applicable_fields -= %i(mac4 qos_ctrl ht_ctrl)
           define_applicable_fields
         end
+
+        # Add an {Element}
+        # @param [Integer,String] type element type
+        # @param [Object] value element value
+        # @return [self]
+        # @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
+          else
+            raise FormatError, 'Before adding an Element, you have to add a Dot11::SubMngt subclass instance'
+          end
+
+          self
+        end
       end
     end
   end

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

@@ -9,6 +9,12 @@ module PacketGen
     class Dot11
 
       # @abstract Base class for all subtype management frames
+      # Subclasses of this class are used to specialize {Management}. A
+      # +SubMngt+ class set +subtype+ field in Dot11 header and may add some
+      # fields.
+      #
+      # All SubMngt subclasses have ability to have {Element}. These elements
+      # may be accessed through {#elements}.
       # @author Sylvain Daubert
       class SubMngt < Base
         # @return [Array<Element>]
@@ -38,12 +44,23 @@ module PacketGen
         # @return [String]
         def inspect
           str = super
-          str << Inspect.dashed_line('Dot11 Elements', level=3)
+          str << Inspect.dashed_line('Dot11 Elements', 3)
           @elements.each do |el|
             str << Inspect.shift_level(4) << 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
+        def add_element(type:, value:)
+          element = Element.new(type: type, value: value)
+          @elements << element
+          self
+        end
 
         private
 
@@ -59,6 +76,12 @@ module PacketGen
       end
 
       # IEEE 802.11 Association Request frame
+      #
+      # Specialize {Dot11::Management} with +subtype+ set to 0.
+      #
+      # Add fields:
+      # * {#cap} ({Types::Int16le}),
+      # * {#listen_interval} ({Types::Int16le}).
       # @author Sylvain Daubert
       class AssoReq < SubMngt
         # @!attribute cap
@@ -72,6 +95,13 @@ module PacketGen
       Management.bind_header AssoReq, op: :and, type: 0, subtype: 0
 
       # IEEE 802.11 Association Response frame
+      #
+      # Specialize {Dot11::Management} with +subtype+ set to 1.
+      #
+      # Add fields:
+      # * {#cap} ({Types::Int16le}),
+      # * {#status} ({Types::Int16le}),
+      # * {#aid} ({Types::Int16le}).
       # @author Sylvain Daubert
       class AssoResp < SubMngt
         # @!attribute cap
@@ -88,6 +118,13 @@ module PacketGen
       Management.bind_header AssoResp, op: :and, type: 0, subtype: 1
 
       # IEEE 802.11 ReAssociation Request frame
+      #
+      # Specialize {Dot11::Management} with +subtype+ set to 2.
+      #
+      # Add fields:
+      # * {#cap} ({Types::Int16le}),
+      # * {#listen_interval} ({Types::Int16le}),
+      # * {#current_ap} ({Eth::MacAddr}).
       # @author Sylvain Daubert
       class ReAssoReq < AssoReq
         # @!attribute current_ap
@@ -98,6 +135,13 @@ module PacketGen
       Management.bind_header ReAssoReq, op: :and, type: 0, subtype: 2
 
       # IEEE 802.11 ReAssociation Response frame
+      #
+      # Specialize {Dot11::Management} with +subtype+ set to 3.
+      #
+      # Add fields:
+      # * {#cap} ({Types::Int16le}),
+      # * {#status} ({Types::Int16le}),
+      # * {#aid} ({Types::Int16le}).
       # @author Sylvain Daubert
       class ReAssoResp < AssoResp
       end
@@ -105,6 +149,10 @@ module PacketGen
       Management.bind_header ReAssoResp, op: :and, type: 0, subtype: 3
 
       # IEEE 802.11 Probe Request frame
+      #
+      # Specialize {Dot11::Management} with +subtype+ set to 4.
+      #
+      # This class adds no field.
       # @author Sylvain Daubert
       class ProbeReq < SubMngt
       end
@@ -112,6 +160,13 @@ module PacketGen
       Management.bind_header ProbeReq, op: :and, type: 0, subtype: 4
 
       # IEEE 802.11 Probe Response frame
+      #
+      # Specialize {Dot11::Management} with +subtype+ set to 5.
+      #
+      # Add fields:
+      # * {#timestamp} ({Types::Int64le}),
+      # * {#beacon_interval} ({Types::Int16le}),
+      # * {#cap} ({Types::Int16le}).
       # @author Sylvain Daubert
       class ProbeResp < SubMngt
         # @!attribute timestamp
@@ -128,6 +183,13 @@ module PacketGen
       Management.bind_header ProbeResp, op: :and, type: 0, subtype: 5
 
       # IEEE 802.11 Beacon frame
+      #
+      # Specialize {Dot11::Management} with +subtype+ set to 8.
+      #
+      # Add fields:
+      # * {#timestamp} ({Types::Int64le}),
+      # * {#interval} ({Types::Int16le}),
+      # * {#cap} ({Types::Int16le}).
       # @author Sylvain Daubert
       class Beacon < SubMngt
         # @!attribute timestamp
@@ -144,12 +206,21 @@ module PacketGen
       Management.bind_header Beacon, op: :and, type: 0, subtype: 8
 
       # IEEE 802.11 ATIM frame
+      #
+      # Specialize {Dot11::Management} with +subtype+ set to 9.
+      #
+      # This class defines no field.
       # @author Sylvain Daubert
       class ATIM < SubMngt; end
       Header.add_class ATIM
       Management.bind_header ATIM, op: :and, type: 0, subtype: 9
 
       # IEEE 802.11 Disassociation frame
+      #
+      # Specialize {Dot11::Management} with +subtype+ set to 10.
+      #
+      # Add fields:
+      # * {#reason} ({Types::Int16le}).
       # @author Sylvain Daubert
       class Disas < SubMngt
         # @!attribute reason
@@ -160,6 +231,13 @@ module PacketGen
       Management.bind_header Disas, op: :and, type: 0, subtype: 10
 
       # IEEE 802.11 Authentication frame
+      #
+      # Specialize {Dot11::Management} with +subtype+ set to 11.
+      #
+      # Add fields:
+      # * {#algo} ({Types::Int16le}),
+      # * {#seqnum} ({Types::Int16le}),
+      # * {#status} ({Types::Int16le}).
       # @author Sylvain Daubert
       class Auth < SubMngt
         # @!attribute algo
@@ -176,6 +254,11 @@ module PacketGen
       Management.bind_header Auth, op: :and, type: 0, subtype: 11
 
       # IEEE 802.11 Deauthentication frame
+      #
+      # Specialize {Dot11::Management} with +subtype+ set to 12.
+      #
+      # Add fields:
+      # * {#reason} ({Types::Int16le}).
       # @author Sylvain Daubert
       class DeAuth < SubMngt
         # @!attribute reason

data/lib/packetgen/header/dot1x.rb

@@ -26,19 +26,19 @@ module PacketGen
 
       # IEEE 802.1X packet types
       TYPES = {
-        0 => 'EAP Packet',
-        1 => 'Start',
-        2 => 'Logoff',
-        3 => 'Key',
-        4 => 'Encap-ASF-Alert'
-      }
+        'EAP Packet'      => 0,
+        'Start'           => 1,
+        'Logoff'          => 2,
+        'Key'             => 3,
+        'Encap-ASF-Alert' => 4
+      }.freeze
 
       # @!attribute version
       #  @return [Integer] 8-bit Protocol Version
       define_field :version, Types::Int8, default: 1
       # @!attribute type
       #  @return [Integer] 8-bit Packet Type
-      define_field :type, Types::Int8
+      define_field :type, Types::Int8Enum, enum: TYPES
       # @!attribute length
       #  @return [Integer] 16-bit body length
       define_field :length, Types::Int16
@@ -46,29 +46,10 @@ module PacketGen
       #  @return [Types::String,Header::Base]
       define_field :body, Types::String
 
-      # @private
-      alias old_type= type=
-
-      # Set type attribute
-      # @param [String,Integer] type
-      # @return [Integer]
-      def type=(type)
-        case type
-        when Integer
-          self.old_type = type
-        else
-          v = TYPES.key(type.to_s)
-          raise ArgumentError, "unknown type #{type}" if v.nil?
-          self.old_type = v
-        end
-      end
-
       # Get human readable type
       # @return [String]
       def human_type
-        v = TYPES[self.type]
-        v = self.type if v.nil?
-        v.to_s
+        self[:type].to_human
       end
     end
 

data/lib/packetgen/header/ike.rb

@@ -78,19 +78,21 @@ module PacketGen
       PROTO_AH  = 2
       PROTO_ESP = 3
 
-      TYPE_IKE_SA_INIT     = 34
-      TYPE_IKE_AUTH        = 35
-      TYPE_CREATE_CHILD_SA = 36
-      TYPE_INFORMATIONAL   = 37
+      EXCHANGE_TYPES = {
+        'IKE_SA_INIT'     => 34,
+        'IKE_AUTH'        => 35,
+        'CREATE_CHILD_SA' => 36,
+        'INFORMATIONAL'   => 37
+      }.freeze
 
       # @!attribute init_spi
       #  64-bit initiator SPI
       #  @return [Integer]
-      define_field :init_spi, Types::Int64 
+      define_field :init_spi, Types::Int64
       # @!attribute resp_spi
       #  64-bit responder SPI
       #  @return [Integer]
-      define_field :resp_spi, Types::Int64 
+      define_field :resp_spi, Types::Int64
       # @!attribute next
       #  8-bit next payload type
       #  @return [Integer]
@@ -102,7 +104,7 @@ module PacketGen
       # @!attribute [r] exchange_type
       #  8-bit exchange type
       #  @return [Integer]
-      define_field :exchange_type, Types::Int8
+      define_field :exchange_type, Types::Int8Enum, enum: EXCHANGE_TYPES
       # @!attribute flags
       #  8-bit flags
       #  @return [Integer]
@@ -152,30 +154,13 @@ module PacketGen
         self.type = options[:exchange_type] if options[:exchange_type]
       end
 
-        # Set exchange type
-        # @param [Integer,String] value
-        # @return [Integer]
-      def exchange_type=(value)
-        type = case value
-               when Integer
-                 value
-               else
-                 c = self.class.constants.grep(/TYPE_#{value}/).first
-                 c ? self.class.const_get(c) : nil
-               end
-        raise ArgumentError, "unknown exchange type #{value.inspect}" unless type
-        self[:exchange_type].value = type
-      end
       alias type exchange_type
       alias type= exchange_type=
 
       # Get exchange type name
       # @return [String
       def human_exchange_type
-          name = self.class.constants.grep(/TYPE_/).
-                 select { |c| self.class.const_get(c) == type }.
-                 first || "type #{type}"
-          name.to_s.sub(/TYPE_/, '')
+        self[:exchange_type].to_human
       end
       alias human_type human_exchange_type
 

data/lib/packetgen/header/ike/cert.rb

@@ -39,50 +39,34 @@ module PacketGen
         # Payload type number
         PAYLOAD_TYPE = 37
 
-        ENCODING_PKCS7_WRAPPED_X509   = 1
-        ENCODING_PGP                  = 2
-        ENCODING_DNS_SIGNED_KEY       = 3
-        ENCODING_X509_CERT_SIG        = 4
-        ENCODING_KERBEROS_TOKEN       = 6
-        ENCODING_X509_CRL             = 7
-        ENCODING_X509_ARL             = 8
-        ENCODING_SPKI_CERT            = 9
-        ENCODING_X509_CERT_ATTR       = 10
-        ENCODING_HASH_URL_X509_CERT   = 12
-        ENCODING_HASH_URL_X509_BUNDLE = 13
+        ENCODINGS = {
+          'PKCS7_WRAPPED_X509'   => 1,
+          'PGP'                  => 2,
+          'DNS_SIGNED_KEY'       => 3,
+          'X509_CERT_SIG'        => 4,
+          'KERBEROS_TOKEN'       => 6,
+          'X509_CRL'             => 7,
+          'X509_ARL'             => 8,
+          'SPKI_CERT'            => 9,
+          'X509_CERT_ATTR'       => 10,
+          'HASH_URL_X509_CERT'   => 12,
+          'HASH_URL_X509_BUNDLE' => 13
+        }.freeze
 
         # @attribute encoding
         #   8-bit certificate encoding
         #   @return [Integer]
-        define_field_before :content, :encoding, Types::Int8
+        define_field_before :content, :encoding, Types::Int8Enum, enum: ENCODINGS
 
         def initialize(options={})
           super
           self.encoding = options[:encoding] if options[:encoding]
         end
 
-        # Set encoding
-        # @param [Integer,String] value
-        # @return [Integer]
-        def encoding=(value)
-          encoding = case value
-               when Integer
-                 value
-               else
-                 c = self.class.constants.grep(/ENCODING_#{value}/).first
-                 c ? self.class.const_get(c) : nil
-               end
-          raise ArgumentError, "unknown ID encoding #{value.inspect}" unless encoding
-          self[:encoding].value = encoding
-        end
-
         # Get encoding name
         # @return [String]
         def human_encoding
-          name = self.class.constants.grep(/ENCODING_/).
-                 select { |c| self.class.const_get(c) == encoding }.
-                 first || "encoding #{encoding}"
-          name.to_s.sub(/ENCODING_/, '')
+          self[:encoding].to_human
         end
 
         # @return [String]