packetgen 4.0.0 → 4.1.1

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # This file is part of PacketGen
-# See https://github.com/lemontree55/packetgen for more informations
+# See https://codeberg.org/lemontree55/packetgen for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
@@ -11,8 +11,16 @@ require_relative 'option'
 module PacketGen
   module Header
     class TCP
-      # Container for TCP options in {TCP TCP header}.
+      # Container for TCP {Option options} in {TCP TCP header}.
       # @author Sylvain Daubert
+      # @since 1.0.0
+      # @since 4.1.0 +#<<+ accepts +:kind+ parameter in hash
+      # @example Add an option from a hash
+      #   opts = PacketGen::Header::TCP::Options.new
+      #   # Option kind may be set using :opt
+      #   opts << { opt: 'MSS', value: 1250 }
+      #   # It may aldo be set using :kind
+      #   opts << { kind: 'EOL' }
       class Options < BinStruct::Array
         set_of Option
 
@@ -34,8 +42,8 @@ module PacketGen
         private
 
         def record_from_hash(hsh)
-          if hsh.key? :opt
-            klassname = hsh.delete(:opt)
+          if hsh.key?(:opt) || hsh.key?(:kind)
+            klassname = hsh.delete(:opt) || hsh.delete(:kind)
             raise ArgumentError, 'opt should be a TCP::Option subclass' unless TCP.const_defined?(klassname)
 
             klass = TCP.const_get(klassname)

data/lib/packetgen/header/tcp.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # This file is part of PacketGen
-# See https://github.com/lemontree55/packetgen for more informations
+# See https://codeberg.org/lemontree55/packetgen for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
@@ -29,50 +29,56 @@ module PacketGen
     #   |                             data                              |
     #   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     # A TCP header consists of:
-    # * a source port ({#sport}, {BinStruct::Int16} type),
-    # * a destination port ({#dport}, +Int16+ type),
-    # * a sequence number ({#seqnum}, {BinStruct::Int32} type),
-    # * an acknownledge number ({#acknum}, +Int32+ type),
-    # * a 16-bit field ({#u16}, +Int16+ type) composed of:
-    #   * a 4-bit {#data_offset} self[attr],
+    # * a source port ({#sport}, +BinStruct::Int16+ type),
+    # * a destination port ({#dport}, +BinStruct::Int16+ type),
+    # * a sequence number ({#seqnum}, +BinStruct::Int32+ type),
+    # * an acknownledge number ({#acknum}, +BinStruct::Int32+ type),
+    # * a 16-bit field ({#u16}, +BinStruct::Int16+ type) composed of:
+    #   * a 4-bit {#data_offset},
     #   * a 3-bit {#reserved} field,
     #   * a 9-bit {#flags} field,
-    # * a {#window} field (+Int16+ type),
-    # * a {#checksum} field (+Int16+ type),
-    # * a urgent pointer ({#urg_pointer}, +Int16+ type),
+    # * a {#window} field (+BinStruct::Int16+ type),
+    # * a {#checksum} field (+BinStruct::Int16+ type),
+    # * a urgent pointer ({#urg_pointer}, +BinStruct::Int16+ type),
     # * an optional {#options} field ({Options} type),
-    # * and a {#body} ({BinStruct::String} type).
+    # * and a {#body} (+BinStruct::String+ type).
     #
-    # == Create a TCP header
+    # @example Create a TCP header
     #  # standalone
     #  tcph = PacketGen::Header::TCP.new
     #  # in a IP packet
     #  pkt = PacketGen.gen('IP').add('TCP')
     #  # access to TCP header
-    #  pkt.tcp   # => PacketGen::Header::TCP
+    #  pkt.tcp.class   # => PacketGen::Header::TCP
     #
-    # == TCP attributes
+    # @example TCP attributes
+    #  tcph = PacketGen::Header::TCP.new
     #  tcph.sport = 4500
     #  tcph.dport = 80
     #  tcph.seqnum = 43
     #  tcph.acknum = 0x45678925
     #  tcph.wsize = 0x240
     #  tcph.urg_pointer = 0x40
-    #  tcph.body.read 'this is a body'
+    #  tcph.body = 'this is a body'
     #
-    # == Flags
-    # TCP flags may be accesed as a 9-bit integer:
+    # @example TCP Flags
+    #  tcph = PacketGen::Header::TCP.new
+    #  # TCP flags may be accesed as a 9-bit integer:
     #  tcph.flags = 0x1002
-    # Each flag may be accessed independently:
-    #  tcph.flag_syn?    # => Boolean
+    #  # Each flag may be accessed independently:
+    #  tcph.flag_syn?    # => true
     #  tcph.flag_rst = true
     #
-    # == Options
-    # {#options} TCP attribute is a {Options}. {Option} may added to it:
-    #  tcph.options << PacketGen::Header::TCP::MSS.new(1250)
-    # or:
-    #  tcph.options << { opt: 'MSS', self[attr]: 1250 }
+    # @example TCP Options
+    #  tcph = PacketGen::Header::TCP.new
+    #  # options TCP attribute is a PacketGen::Header::TCP::Options.
+    #  # PacketGen::Header::TCP::Option may added to it:
+    #  tcph.options << PacketGen::Header::TCP::MSS.new(value: 1250)
+    #  # or
+    #  tcph.options << { kind: 'MSS', value: 1250 }
+    #  tcph.options.last.class #=> PacketGen::Header::TCP::MSS
     # @author Sylvain Daubert
+    # @author LemonTree55
     class TCP < Base
     end
   end
@@ -151,7 +157,8 @@ module PacketGen
       #  @return [Options]
       define_attr :options, TCP::Options, builder: ->(h, t) { t.new(length_from: -> { h.data_offset > 5 ? (h.data_offset - 5) * 4 : 0 }) }
       # @!attribute body
-      #  @return [BinStruct::String,Header::Base]
+      #  TCP body
+      #  @return [BinStruct::String,Headerable]
       define_attr :body, BinStruct::String
 
       alias source_port sport
@@ -181,7 +188,7 @@ module PacketGen
       # @option options [Integer] :window
       # @option options [Integer] :checksum
       # @option options [Integer] :urg_pointer
-      # @option options [String] :body
+      # @option options [String, Headerable] :body
       def initialize(options={})
         opts = { data_offset: 5 }.merge!(options)
         super(opts)
@@ -195,7 +202,7 @@ module PacketGen
       end
 
       # Set all flags at once
-      # @parameter [Integer] value
+      # @param [Integer] value
       # @return [Integer]
       def flags=(value)
         new_u16 = (self.u16 & 0xfe00) | (value & 0x1ff)

data/lib/packetgen/header/tftp.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # This file is part of PacketGen
-# See https://github.com/lemontree55/packetgen for more informations
+# See https://codeberg.org/lemontree55/packetgen for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
@@ -10,25 +10,26 @@ module PacketGen
   module Header
     # A TFTP (Trivial File Transfer Protocol,
     # {https://tools.ietf.org/html/rfc1350 RFC 1350}) header consists of:
-    # * a {#opcode} ({BinStruct::Int16Enum}),
+    # * an {#opcode} (+BinStruct::Int16Enum+),
     # * and a body. Its content depends on opcode.
     #
     # Specialized subclasses exists to handle {TFTP::RRQ Read Request},
     # {TFTP::WRQ Write Request}, {TFTP::DATA DATA}, {TFTP::ACK ACK} and
     # {TFTP::ERROR ERROR} packets.
     #
-    # == Create a TFTP header
+    # @example Create a TFTP header
     #  # standalone
     #  tftp = PacketGen::Header::TFTP.new
     #  # in a packet
     #  pkt = PacketGen.gen('IP').add('UDP').add('TFTP')
     #  # access to TFTP header
-    #  pkt.tftp   # => PacketGen::Header::TFTP
+    #  pkt.tftp.class   # => PacketGen::Header::TFTP
     #
-    # == TFTP attributes
+    # @example TFTP attributes
+    #  tftp = PacketGen::Header::TFTP.new
     #  tftp.opcode = 'RRQ'
     #  tftp.opcode = 1
-    #  tftp.body.read 'this is a body'
+    #  tftp.body = 'this is a body'
     #
     # == TFTP parsing
     # When parsing, only first packet (read or write request) should be decoded
@@ -46,6 +47,7 @@ module PacketGen
     #   packets[0].tftp.decode!(packets[1..-1])
     #   packets.map { |pkt| pkt.headers.last.class.to_s }.join(',')  # => TFTP::RRQ,TFTP::DATA,UDP,TFTP::ACK
     # @author Sylvain Daubert
+    # @author LemonTree55
     # @since 2.3.0
     class TFTP < Base
       # Known opcodes
@@ -63,7 +65,8 @@ module PacketGen
       define_attr :opcode, BinStruct::Int16Enum, enum: OPCODES
 
       # @!attribute body
-      #   @return [String]
+      #   TFTP body, if opcode is unknown
+      #   @return [String,Headerable]
       define_attr :body, BinStruct::String
 
       def initialize(options={})
@@ -85,7 +88,7 @@ module PacketGen
       def read(str)
         if self.instance_of? TFTP
           super
-          if OPCODES.value? opcode
+          if OPCODES.value?(opcode)
             TFTP.const_get(human_opcode).new.read(str)
           else
             self
@@ -145,7 +148,8 @@ module PacketGen
         pkt.udp.dport = udp_dport
       end
 
-      # TFTP Read Request header
+      # TFTP Read Request header.
+      # This header remove {#body} attribute and repalces it with {#filename} and {#mode}.
       class RRQ < TFTP
         remove_attr :body
 
@@ -171,7 +175,8 @@ module PacketGen
         define_attr_before :body, :block_num, BinStruct::Int16
       end
 
-      # TFTP ACK header
+      # TFTP ACK header.
+      # This header remove {#body} attribute and repalces it with {#block_num}.
       class ACK < TFTP
         remove_attr :body
 
@@ -181,7 +186,8 @@ module PacketGen
         define_attr :block_num, BinStruct::Int16
       end
 
-      # TFTP ERROR header
+      # TFTP ERROR header.
+      # This header remove {#body} attribute and repalces it with {#error_code} and {#error_msg}.
       class ERROR < TFTP
         remove_attr :body
 

data/lib/packetgen/header/udp.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # This file is part of PacketGen
-# See https://github.com/lemontree55/packetgen for more informations
+# See https://codeberg.org/lemontree55/packetgen for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
@@ -17,28 +17,30 @@ module PacketGen
     #   |             Length            |           Checksum            |
     #   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     # A UDP header consists of:
-    # * a source port field ({#sport}, {BinStruct::Int16} type),
-    # * a destination port field ({#dport}, +Int16+ type),
-    # * a UDP length field ({#length}, +Int16+ type),
-    # * a {#checksum} field (+Int16+ type),
+    # * a source port field ({#sport}, +BinStruct::Int16+ type),
+    # * a destination port field ({#dport}, +BinStruct:Int16+ type),
+    # * a UDP length field ({#length}, +BinStruct:Int16+ type),
+    # * a {#checksum} field (+BinStruct:Int16+ type),
     # * and a {#body}.
     #
-    # == Create a UDP header
+    # @example Create a UDP header
     #  # standalone
     #  udp = PacketGen::Header::UDP.new
     #  # in a packet
-    #  pkt = PAcketGen.gen('IP').eadd('UDP')
+    #  pkt = PacketGen.gen('IP').add('UDP')
     #  # access to IP header
-    #  pkt.udp    # => PacketGen::Header::UDP
+    #  pkt.udp.class    # => PacketGen::Header::UDP
     #
-    # == UDP attributes
+    # @example UDP attributes
+    #  udp = PacketGen::Header::UDP.new
     #  udp.sport = 65432
     #  udp.dport = 53
     #  udp.length = 43
     #  udp.checksum = 0xffff
-    #  udp.body.read 'this is a UDP body'
+    #  udp.body = 'this is a UDP body'
     #
     # @author Sylvain Daubert
+    # @author LemonTree55
     class UDP < Base
       # IP protocol number for UDP
       IP_PROTOCOL = 17
@@ -60,7 +62,8 @@ module PacketGen
       #  @return [Integer]
       define_attr :checksum, BinStruct::Int16
       # @!attribute body
-      #  @return [BinStruct::String,Header::Base]
+      #  UDP body
+      #  @return [BinStruct::String,Headerable]
       define_attr :body, BinStruct::String
 
       alias source_port sport
@@ -75,7 +78,7 @@ module PacketGen
         self.length += self[:body].sz if self[:body].sz.positive?
       end
 
-      # Compute checksum and set +checksum+ field
+      # Compute checksum and set {#checksum} field
       # @return [Integer]
       def calc_checksum
         ip = ip_header(self)
@@ -86,7 +89,7 @@ module PacketGen
         self.checksum = IP.reduce_checksum(sum)
       end
 
-      # Compute length and set +length+ field
+      # Compute length and set {#length} field
       # @return [Integer]
       def calc_length
         Base.calculate_and_set_length(self)
@@ -100,7 +103,6 @@ module PacketGen
         self
       end
     end
-
     self.add_class UDP
 
     IP.bind UDP, protocol: UDP::IP_PROTOCOL

data/lib/packetgen/header.rb

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 # This file is part of PacketGen
-# See https://github.com/lemontree55/packetgen for more informations
+# See https://codeberg.org/lemontree55/packetgen for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
@@ -14,21 +14,27 @@ module PacketGen
   #
   # == Add a foreign header class
   # PacketGen permits adding your own header classes.
-  # First, define the new header class. By example:
-  #  module MyModule
-  #    class MyHeader < PacketGen::Header::Base
-  #      define_attr :field1, BinStruct::Int32
-  #      define_attr :field2, BinStruct::Int32
-  #    end
+  # First, define the new header class. Then, this class must be declared to PacketGen using {Header.add_class}.
+  # Finally, bindings must be declared.
+  #
+  # @example Foreign header class
+  #   # Define a new header
+  #   module MyModule
+  #     class MyHeader < PacketGen::Header::Base
+  #       define_attr :field1, BinStruct::Int32
+  #       define_attr :field2, BinStruct::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 and Packet#add)
-  #  PacketGen::Header::IP.bind_header(MyModule::MyHeader, protocol: 254)
-  # And use it:
-  #  pkt = Packet.gen('IP').add('MyHeader', field1: 0x12345678, field3: 0x87654321)
+  #
+  #   # Declare the new header to PacketGen
+  #   PacketGen::Header.add_class(MyModule::MyHeader)
+  #   # bind it as IP protocol number 254 (needed by Packet#parse and Packet#add)
+  #   PacketGen::Header::IP.bind(MyModule::MyHeader, protocol: 254)
+  #
+  #   # Use it
+  #   pkt = PacketGen.gen('IP').add('MyModule::MyHeader', field1: 0x12345678, field3: 0x87654321)
   # @author Sylvain Daubert
+  # @author LemonTree55
   module Header
     @added_header_classes = {}
 

data/lib/packetgen/headerable.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # This file is part of PacketGen
-# See https://github.com/lemontree55/packetgen for more informations
+# See https://codeberg.org/lemontree55/packetgen for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
@@ -9,7 +9,13 @@
 module PacketGen
   # This mixin module defines minimal API for a class to act as a header
   # in {Packet}.
+  #
+  # Some others methods may optionally be defined by a {Headerable} object:
+  # * +#calc_length+ to calculate length from content. It should be defined if header as a length attribute.
+  # * +#calc_checksum+ to calculate checksum. It should be defined if header as a checksum attriibute.
+  # * +#reply+ to invert fields in header for a reply.
   # @author Sylvain Daubert
+  # @author LemonTree55
   # @since 3.0.2
   module Headerable
     # This modules handles class methods for {Headerable headerable classes}.
@@ -51,7 +57,7 @@ module PacketGen
     end
 
     # @abstract Should be redefined by subclasses. This method should check invariant
-    #   attributes.from header.
+    #   attributes from header.
     # Called by {Packet#parse} when guessing first header to check if header is correct
     # @return [Boolean]
     def parse?
@@ -74,8 +80,8 @@ module PacketGen
       @packet
     end
 
-    # @abstract This method is called when a header is added to a packet.
-    #   This base method does nothing but may be overriden by subclasses.
+    # @abstract This base method does nothing but may be overriden by subclasses.
+    # This method is called when a header is added to a packet.
     # @param [Packet] packet packet to which self is added
     # @return [void]
     def added_to_packet(packet) end

data/lib/packetgen/inject.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # This file is part of PacketGen
-# See https://github.com/lemontree55/packetgen for more informations
+# See https://codeberg.org/lemontree55/packetgen for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.

data/lib/packetgen/inspect.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # This file is part of PacketGen
-# See https://github.com/lemontree55/packetgen for more informations
+# See https://codeberg.org/lemontree55/packetgen for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
 # Copyright (C) 2024 LemonTree55 <lenontree@proton.me>
 # This program is published under MIT license.
@@ -61,18 +61,13 @@ module PacketGen
       str << Inspect::FMT_ATTR % [type, attr, value]
     end
 
-    # Format an attribute for +#inspect+.
-    # 3 cases are handled:
-    # * attribute value is a {BinStruct::Int}: show value as integer and in
-    #   hexdecimal format,
-    # * attribute value responds to +#to_human+: call it,
-    # * else, +#to_s+ is used to format attribute value.
+    # Format an attribute for +#inspect+. Call +#format_inspect} on +value+.
     # @param [Symbol] attr attribute name
     # @param [Object] value attribute value
     # @param [Integer] level
     # @return [String]
     def self.inspect_attribute(attr, value, level=1)
-      type = value.class.to_s.sub(/.*::/, '')
+      type = value.type_name
       self.format(type, attr, value.format_inspect, level)
     end