packetgen 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3cb4095a7e2fda39a7560ad82d4296016c5a633a
-  data.tar.gz: aed1db17fd5274a7d842ac6ba855ed73b7d271fe
+  metadata.gz: 21f7a146ddb2ba2b7e8b86933360a97d95344fef
+  data.tar.gz: e26c103bc3ef15ca5d7064163cd747716215a71b
 SHA512:
-  metadata.gz: a520f1dfaf0a6960c33fb27c5f564923c4de11c8d310b77c7dcf151c688df70d15396b1ce74987b7a8ca811e86f58a2f6eaf1d0a18ba03613ed02aebde9f9730
-  data.tar.gz: e8396d8782c437335f50a3b8ee2e63138a9b0c4ea874b46838249fcb58e8f1acc89f1a7c24c6fd0fda5169c856f9724296e2c285c826223c91eebca5eba60a95
+  metadata.gz: 304723a5e11714b3092606fd7f7529fd1a4d6ec0b427e364d3603b63cca20fbfc410a996d80a1a3cfb58106e855dcf5fbc76dd957b589eee6b97c1fa70379312
+  data.tar.gz: d95e4b3fa118e33ae9296626fd2855d6d3eaad9a4d2e0fd4605cfca5bdfd193b4397fd4411164a018dfbbf37868a35026134acf01cd2fdb52729cb90c05bc7fd

data/README.md

@@ -94,11 +94,10 @@ pkt.is? 'TCP'   # => true
 pkt.is? 'IP'    # => true
 pkt.is? 'UDP'   # => false
 
-# encapulsate/decapsulate packets (TODO)
-pkt2 = PacketGen.gen('IP').add('ESP', spi: 1234)
-pkt.encap pkt2                         # pkt is now a IP/ESP/IP/TCP packet
-                                       # eq. to pkt.encap('IP', 'ESP', esp_spi: 1234)
-pkt.decap('IP', 'ESP')                 # pkt is now inner IP/TCP packet
+# encapulsate/decapsulate packets
+pkt2 = PacketGen.gen('IP')
+pkt2.encapsulate pkt                   # pkt2 is now a IP/IP/TCP packet
+pkt2.decapsulate(pkt2.ip)              # pkt2 is now inner IP/TCP packet
 ```
 
 ### Read/write PcapNG files
@@ -112,12 +111,55 @@ pkt.write('one_packet.pcapng')
 PacketGen.write('more_packets.pcapng', packets)
 ```
 
+### Add custom header/protocol
+Since v1.1.0, PacketGen permits adding you own header classes.
+First, define the new header class. By example:
+
+```ruby
+module MyModule
+ class MyHeader < Struct.new(:field1, :field2)
+   include PacketGen::StructFu
+   include PacketGen::Header::HeaderMethods
+   extend PacketGen::Header::HeaderClassMethods
+   
+   def initialize(options={})
+     super Int32.new(options[:field1]), Int32.new(options[:field2])
+   end
+   
+   def read(str)
+     self[:field1].read str[0, 4]
+     self[:field2].read str[4, 4]
+   end
+ 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)
+PacketGen::Header::IP.bind_header MyModule::MyHeader, protocol: 254
+```
+
+And use it:
+
+```
+pkt = Packet.gen('IP').add('MyHeader', field1: 0x12345678)
+pkt.myheader.field2.read 0x01
+```
+
 ## Pull requests?
 
 yes
 
 ## License
-MIT License (see [LICENSE](https://github.com/sdaubert/packetgen/LICENSE))
+MIT License (see [LICENSE](https://github.com/sdaubert/packetgen/blob/master/LICENSE))
 
 Copyright © 2016 Sylvain Daubert
 

data/lib/packetgen/header.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 # This file is part of PacketGen
 # See https://github.com/sdaubert/packetgen for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
@@ -5,14 +6,81 @@
 
 module PacketGen
   # Namespace for protocol header classes
+  # == Add a foreign header class
+  # Since v1.1.0, PacketGen permits adding you own header classes.
+  # First, define the new header class. By example:
+  #  module MyModule
+  #    class MyHeader < Struct.new(:field1, :field2)
+  #      include PacketGen::StructFu
+  #      include PacketGen::Header::HeaderMethods
+  #      extend PacketGen::Header::HeaderClassMethods
+  #      
+  #      def initialize(options={})
+  #        super Int32.new(options[:field1]), Int32.new(options[:field2])
+  #      end
+  #      
+  #      def read(str)
+  #        self[:field1].read str[0, 4]
+  #        self[:field2].read str[4, 4]
+  #      end
+  #    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)
+  #  PacketGen::Header::IP.bind_header MyModule::MyHeader, protocol: 254
+  # And use it:
+  #  pkt = Packet.gen('IP').add('MyHeader', field1: 0x12345678)
+  #  pkt.myheader.field2.read 0x01
   # @author Sylvain Daubert
   module Header
 
+    @added_header_classes = {}
+
     # Get known header classes
     # @return [Array<Class>]
     def self.all
-      constants.map { |sym| const_get sym }.
-        select { |klass| klass < Struct && klass < HeaderMethods }
+      return @header_classes if @header_classes
+
+      @builtin ||= constants.map { |sym| const_get sym }.
+                 select { |klass| klass < Struct && klass < HeaderMethods }
+      @header_classes = @builtin + @added_header_classes.values
+    end
+
+    # Add a foreign header class to known header classes. This is
+    # needed by {Packet.gen} and {Packet#add}.
+    # @param [Class] klass a header class, which should include
+    #   {Header::HeaderMethods} and {Header::HeaderClassMethods}
+    # @return [void]
+    # @since 1.1.0
+    def self.add_class(klass)
+      protocol_name = klass.to_s.sub(/.*::/, '')
+      @added_header_classes[protocol_name] = klass
+      @header_classes = nil
+    end
+
+    # Remove a foreign header (previously added by {.add_header_class}à
+    # from known header classes.
+    # @param [Class] klass
+    # @return [void]
+    # @since 1.1.0
+    def self.remove_class(klass)
+      protocol_name = klass.to_s.sub(/.*::/, '')
+      @added_header_classes.delete protocol_name
+      @header_classes = nil
+    end
+
+    # Get header class from its name
+    # @param [String] name
+    # @return [Class,nil]
+    # @since 1.1.0
+    def self.get_header_class_by_name(name)
+      if Header.const_defined? name
+        Header.const_get name
+      else
+        @added_header_classes[name]
+      end
     end
   end
 end

data/lib/packetgen/packet.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 # This file is part of PacketGen
 # See https://github.com/sdaubert/packetgen for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>
@@ -163,25 +164,7 @@ module PacketGen
       klass = check_protocol(protocol)
 
       header = klass.new(options)
-      prev_header = @headers.last
-      if prev_header
-        binding = prev_header.class.known_headers[klass]
-        if binding.nil?
-          msg = "#{prev_header.class} knowns no layer association with #{protocol}. "
-          msg << "Try #{prev_header.class}.bind_layer(PacketGen::Header::#{protocol}, "
-          msg << "#{prev_header.protocol_name.downcase}_proto_field: "
-          msg << "value_for_#{protocol.downcase})"
-          raise ArgumentError, msg
-        end
-        prev_header[binding.key].read binding.value
-        prev_header.body = header
-      end
-      header.packet = self
-      @headers << header
-      unless respond_to? protocol.downcase
-        self.class.class_eval "def #{protocol.downcase}(arg=nil);" \
-                              "header('#{protocol}', arg); end"
-      end
+      add_header header
       self
     end
 
@@ -257,6 +240,34 @@ module PacketGen
       end
     end
 
+    # Encapulate another packet in +self+
+    # @param [Packet] other
+    # @return [self] +self+ with new headers from +other+
+    # @since 1.1.0
+    def encapsulate(other)
+      other.headers.each { |h| add_header h }
+    end
+
+    # Remove headers from +self+
+    # @param [Array<Header>] headers
+    # @return [self] +self+ with some headers removed
+    # @raise [FormatError] any headers not in +self+
+    # @raise [FormatError] removed headers result in an unknown binding
+    # @since 1.1.0
+    def decapsulate(*headers)
+      headers.each do |header|
+        idx = @headers.index(header)
+        raise FormatError, 'header not in packet!' if idx.nil?
+
+        prev_header = idx > 0 ? @headers[idx - 1] : nil
+        next_header = (idx+1) < @headers.size ? @headers[idx + 1] : nil
+        @headers.delete_at(idx)
+        add_header(next_header, prev_header) if prev_header and next_header
+      end
+    rescue ArgumentError => ex
+      raise FormatError, ex.message
+    end
+
     # @return [String]
     def inspect
       str = Inspect.dashed_line(self.class)
@@ -274,17 +285,15 @@ module PacketGen
 
     private
 
-    # @overload header(protocol, layer=1)
-    #  @param [String] protocol
+    # @overload header(klass, layer=1)
+    #  @param [Class] klass
     #  @param [Integer] layer
-    # @overload header(protocol, options)
-    #  @param [String] protocol
+    # @overload header(klass, options={})
+    #  @param [String] klass
     #  @param [Hash] options
+    #  @raise [ArgumentError] unknown option
     # @return [Header::Base]
-    # @raise [ArgumentError] unknown protocol
-    def header(protocol, arg)
-      klass = check_protocol protocol
-
+    def header(klass, arg)
       headers = @headers.select { |h| h.is_a? klass }
       layer = arg.is_a?(Integer) ? arg : 1
       header = headers[layer - 1]
@@ -292,7 +301,7 @@ module PacketGen
       if arg.is_a? Hash
         arg.each do |key, value|
           unless header.respond_to? "#{key}="
-            raise ArgumentError, "unknown #{key} attribute for #{header.class}"
+            raise ArgumentError, "unknown #{key} attribute for #{klass}"
           end
           header.send "#{key}=", value
         end
@@ -305,13 +314,37 @@ module PacketGen
     # @param [String] protocol
     # @raise [ArgumentError] unknown protocol
     def check_protocol(protocol)
-      unless Header.const_defined? protocol
-        raise ArgumentError, "unknown #{protocol} protocol"
-      end
-      klass = Header.const_get(protocol)
-      raise ArgumentError, "unknown #{protocol} protocol" unless klass.is_a? Class
+      klass = Header.get_header_class_by_name(protocol)
+      raise ArgumentError, "unknown #{protocol} protocol" if klass.nil?
       klass
     end
+
+    # Add a header to packet
+    # @param [Header::HeaderMethods] header
+    # @param [Header::HeaderMethods] previous_header
+    # @return [void]
+    def add_header(header, previous_header=nil)
+      protocol = header.protocol_name
+      prev_header = previous_header || @headers.last
+      if prev_header
+        binding = prev_header.class.known_headers[header.class]
+        if binding.nil?
+          msg = "#{prev_header.class} knowns no layer association with #{protocol}. "
+          msg << "Try #{prev_header.class}.bind_layer(PacketGen::Header::#{protocol}, "
+          msg << "#{prev_header.protocol_name.downcase}_proto_field: "
+          msg << "value_for_#{protocol.downcase})"
+          raise ArgumentError, msg
+        end
+        prev_header[binding.key].read binding.value
+        prev_header.body = header
+      end
+      header.packet = self
+      @headers << header unless previous_header
+      unless respond_to? protocol.downcase
+        self.class.class_eval "def #{protocol.downcase}(arg=nil);" \
+                              "header(#{header.class}, arg); end"
+      end
+    end
   end
 end
 

data/lib/packetgen/version.rb

@@ -8,5 +8,5 @@
 # @author Sylvain Daubert
 module PacketGen
   # PacketGen version
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

data/lib/packetgen.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 # This file is part of PacketGen
 # See https://github.com/sdaubert/packetgen for more informations
 # Copyright (C) 2016 Sylvain Daubert <sylvain.daubert@laposte.net>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: packetgen
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Sylvain Daubert
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-19 00:00:00.000000000 Z
+date: 2016-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pcaprub