ronin-support 0.5.1 → 1.0.0.beta1

data/lib/ronin/support/binary/template.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/binary/ctypes/mixin'
+require 'ronin/support/binary/array'
+
+module Ronin
+  module Support
+    module Binary
+      #
+      # Provides a translation layer between C-types and Ruby `Array#pack`
+      # codes.
+      #
+      # ## Supported Types
+      #
+      # * `:uint8` - unsigned 8-bit integer.
+      # * `:uint16` - unsigned 16-bit integer.
+      # * `:uint32` - unsigned 32-bit integer.
+      # * `:uint64` - unsigned 64-bit integer.
+      # * `:int8` - signed 8-bit integer.
+      # * `:int16` - signed 16-bit integer.
+      # * `:int32` - signed 32-bit integer.
+      # * `:int64` - signed 64-bit integer.
+      # * `:uint16_le` - unsigned 16-bit integer, little endian.
+      # * `:uint32_le` - unsigned 32-bit integer, little endian.
+      # * `:uint16_be` - unsigned 16-bit integer, big endian.
+      # * `:uint32_be` - unsigned 32-bit integer, big endian.
+      # * `:uchar` - unsigned character.
+      # * `:ushort` - unsigned short integer, native endian.
+      # * `:uint` - unsigned integer, native endian.
+      # * `:ulong` - unsigned long integer, native endian.
+      # * `:ulong_long` - unsigned quad integer, native endian.
+      # * `:char` - signed character.
+      # * `:short` - signed short integer, native endian.
+      # * `:int` - signed integer, native endian.
+      # * `:long` - signed long integer, native endian.
+      # * `:long_long` - signed quad integer, native endian.
+      # * `:float` - single-precision float, native format.
+      # * `:double` - double-precision float, native format.
+      # * `:float_le` - single-precision float, little endian.
+      # * `:double_le` - double-precision float, little endian.
+      # * `:float_be` - single-precision float, big endian.
+      # * `:double_be` - double-precision float, big endian.
+      # * `:byte` - signed byte.
+      # * `:string` - binary String, `\0` terminated.
+      # * `:uint16_le` - unsigned 16-bit integer, little endian.
+      # * `:uint32_le` - unsigned 32-bit integer, little endian.
+      # * `:uint64_le` - unsigned 64-bit integer, little endian.
+      # * `:int16_le` - signed 16-bit integer, little endian.
+      # * `:int32_le` - signed 32-bit integer, little endian.
+      # * `:int64_le` - signed 64-bit integer, little endian.
+      # * `:uint16_be` - unsigned 16-bit integer, big endian.
+      # * `:uint32_be` - unsigned 32-bit integer, big endian.
+      # * `:uint64_be` - unsigned 64-bit integer, big endian.
+      # * `:int16_be` - signed 16-bit integer, big endian.
+      # * `:int32_be` - signed 32-bit integer, big endian.
+      # * `:int64_be` - signed 64-bit integer, big endian.
+      # * `:ushort_le` - unsigned short integer, little endian.
+      # * `:uint_le` - unsigned integer, little endian.
+      # * `:ulong_le` - unsigned long integer, little endian.
+      # * `:ulong_long_le` - unsigned quad integer, little endian.
+      # * `:short_le` - signed short integer, little endian.
+      # * `:int_le` - signed integer, little endian.
+      # * `:long_le` - signed long integer, little endian.
+      # * `:long_long_le` - signed quad integer, little endian.
+      # * `:ushort_be` - unsigned short integer, little endian.
+      # * `:uint_be` - unsigned integer, little endian.
+      # * `:ulong_be` - unsigned long integer, little endian.
+      # * `:ulong_long_be` - unsigned quad integer, little endian.
+      # * `:short_be` - signed short integer, little endian.
+      # * `:int_be` - signed integer, little endian.
+      # * `:long_be` - signed long integer, little endian.
+      # * `:long_long_be` - signed quad integer, little endian.
+      #
+      # @see https://rubydoc.info/stdlib/core/Array:pack
+      #
+      # @api pbulic
+      #
+      class Template
+
+        include CTypes::Mixin
+
+        # The fields of the binary template.
+        #
+        # @return [::Array<Symbol, (Symbol, Integer), Range(Symbol)>]
+        attr_reader :fields
+
+        # The field types of the binary template.
+        #
+        # @return [::Array<CTypes::Type,
+        #                  CTypes::ArrayType,
+        #                  CTypes::UnboundArrayType>]
+        #
+        # @since 1.0.0
+        attr_reader :types
+
+        # The `Array#pack` string for the binary template.
+        #
+        # @return [String]
+        #
+        # @since 1.0.0
+        attr_reader :pack_string
+
+        #
+        # Creates a new Binary template.
+        #
+        # @param [::Array<Symbol, (Symbol, Integer)>] fields
+        #   The C-types which the packer will use.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments.
+        #
+        # @option kwargs [:little, :big, :net, nil] :endian
+        #   The desired endianness of the values within the template.
+        #
+        # @option kwargs [:x86, :x86_64,
+        #                 :ppc, :ppc64,
+        #                 :mips, :mips_le, :mips_be,
+        #                 :mips64, :mips64_le, :mips64_be,
+        #                 :arm, :arm_le, :arm_be,
+        #                 :arm64, :arm64_le, :arm64_be] :arch
+        #   The desired architecture for the values within the template.
+        #
+        # @raise [ArgumentError]
+        #   A given type is not known.
+        #
+        # @example
+        #   template = Template.new([:uint32, [:char, 100]])
+        #   template.pack(0x123456, ['A', 'B', 'C'])
+        #   # => "CBA\x00XYZ\x00\x00\x00\x00\x00\x00\x00"
+        #   template.unpack("CBA\x00XYZ\x00\x00\x00\x00\x00\x00\x00")
+        #   # => [4276803, #<Ronin::Support::Binary::Array: "XYZ\x00\x00\x00\x00\x00\x00\x00">]
+        #
+        def initialize(fields, **kwargs)
+          initialize_type_system(**kwargs)
+
+          @fields = []
+          @types  = []
+          @pack_string = String.new
+
+          fields.each do |field|
+            type = @type_resolver.resolve(field)
+
+            @fields      << field
+            @types       << type
+
+            if @pack_string
+              if type.pack_string then @pack_string << type.pack_string
+              else                     @pack_string = nil
+              end
+            end
+          end
+        end
+
+        #
+        # @example
+        #   template = Template.new[:uint32, [:char, 10]]
+        #   template.pack(0x123456, ['A', 'B', 'C'])
+        #   # => "CBA\x00XYZ\x00\x00\x00\x00\x00\x00\x00"
+        #   template.unpack("CBA\x00XYZ\x00\x00\x00\x00\x00\x00\x00")
+        #   # => [4276803, #<Ronin::Support::Binary::Array: "XYZ\x00\x00\x00\x00\x00\x00\x00">]
+        #
+        # @see #initialize
+        #
+        # @since 1.0.0
+        #
+        def self.[](*fields,**kwargs)
+          new(fields,**kwargs)
+        end
+
+        #
+        # Packs the data.
+        #
+        # @param [::Array] arguments
+        #   The values to pack.
+        #
+        # @return [String]
+        #   The packed data.
+        #
+        # @example
+        #   template = Template.new[:uint32, [:char, 10]]
+        #   template.pack(0x123456, ['A', 'B', 'C'])
+        #   # => "CBA\x00XYZ\x00\x00\x00\x00\x00\x00\x00"
+        #
+        def pack(*arguments)
+          if @pack_string
+            values = []
+
+            @types.each do |type|
+              # shift off the next value(s) and enqueue them
+              type.enqueue_value(values,arguments.shift)
+            end
+
+            values.pack(@pack_string)
+          else
+            buffer = String.new('', encoding: Encoding::ASCII_8BIT)
+
+            @types.each do |type|
+              # shift off the next value and pack it
+              buffer << type.pack(arguments.shift)
+            end
+
+            return buffer
+          end
+        end
+
+        #
+        # Unpacks the string.
+        #
+        # @param [String] data
+        #   The raw String to unpack.
+        #
+        # @return [::Array]
+        #   The unpacked data.
+        #
+        # @example
+        #   template = Template.new[:uint32, [:char, 10]]
+        #   template.unpack("CBA\x00XYZ\x00\x00\x00\x00\x00\x00\x00")
+        #   # => [4276803, #<Ronin::Support::Binary::Array: "XYZ\x00\x00\x00\x00\x00\x00\x00">]
+        #
+        def unpack(data)
+          if @pack_string
+            values = data.unpack(@pack_string)
+
+            @types.map do |type|
+              type.dequeue_value(values)
+            end
+          else
+            array  = []
+            offset = 0
+
+            @types.each do |type|
+              slice = if type.size == Float::INFINITY
+                        data.byteslice(offset..)
+                      else
+                        data.byteslice(offset,type.size)
+                      end
+
+              array  << type.unpack(slice)
+              offset += type.size
+            end
+
+            return array
+          end
+        end
+
+        #
+        # Converts the template to a `Array#pack` template String.
+        #
+        # @return [String]
+        #   The template String.
+        #
+        # @example
+        #   template = Template.new[:uint32, [:char, 10]]
+        #   template.to_s
+        #   # => "La10"
+        #
+        # @see https://rubydoc.info/stdlib/core/Array:pack
+        #
+        def to_s
+          @pack_string
+        end
+
+        alias to_str to_s
+
+      end
+    end
+  end
+end

data/lib/ronin/support/binary/union.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/binary/struct'
+
+module Ronin
+  module Support
+    module Binary
+      #
+      # Generic Binary Union class.
+      #
+      # @note This class provides lazy memory mapped access to an underlying
+      # buffer. This means values are decoded/encoded each time they are read
+      # or written to.
+      #
+      # ## Examples
+      #
+      # ### Defining Fields
+      #
+      #     class MyUnion < Ronin::Support::Binary::Union
+      #
+      #       member :c, :char
+      #       member :i, :int16
+      #       member :u, :uint32
+      #     
+      #     end
+      #
+      # ### Initializing Fields
+      #
+      #     union   = MyUnion.new
+      #     union.i = -1
+      #
+      #     union = MyUnion.new(i: -1)
+      #
+      # ### Inheriting Unions
+      #
+      #     class MyUnion < Ronin::Support::Binary::Union
+      #
+      #       member :c, :char
+      #       member :i, :int16
+      #       member :u, :uint32
+      #     
+      #     end
+      #     
+      #     class MyUnion2 < MyUnion
+      #     
+      #       member :f, :float32
+      #       member :d, :float64
+      #     
+      #     end
+      #     
+      #     union   = MyUnion.new
+      #     union.i = -1
+      #     
+      #     union2   = MyUnion.new
+      #     union2.i = -1
+      #     union2.d = 1.123
+      #
+      # ### Packing Unions
+      #
+      #     class MyUnion < Ronin::Support::Binary::Union
+      #     
+      #       member :c, :char
+      #       member :i, :int16
+      #       member :u, :uint32
+      #     
+      #     end
+      #     
+      #     union = MyUnion.new
+      #     union.u = 0x11111111
+      #     union.i = -1
+      #     union.pack
+      #     # => "\xFF\xFF\x11\x11"
+      #
+      # ### Unpacking Unions
+      #
+      #     class MyUnion < Ronin::Support::Binary::Union
+      #     
+      #       member :c, :char
+      #       member :i, :int32
+      #       member :u, :uint32
+      #     
+      #     end
+      #     
+      #     union = MyUnion.unpack("\xFF\xFF\x11\x11")
+      #     union.c
+      #     # => "\xFF"
+      #     union.i
+      #     # => -1
+      #     union.u
+      #     # => 286392319
+      #
+      # ### Array Fields
+      #
+      #     class MyUnion < Ronin::Support::Binary::Union
+      #     
+      #       member :c, :char
+      #       member :i, :int16
+      #       member :u, :uint32
+      #       member :nums, [:uint8, 10]
+      #     
+      #     end
+      #
+      #     union = MyUnion.new
+      #     union.nums = [0x01, 0x02, 0x03, 0x04]
+      #     union.pack
+      #     # => "\x01\x02\x03\x04\x00\x00\x00\x00\x00\x00"
+      #
+      # ### Unbounded Array Fields
+      #
+      #     class MyUnion < Ronin::Support::Binary::Union
+      #     
+      #       member :c, :char
+      #       member :i, :int16
+      #       member :u, :uint32
+      #       member :payload, (:uint8..)
+      #     
+      #     end
+      #     
+      #     union = MyUnion.new
+      #     union.payload = [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]
+      #     union.pack
+      #     # => "\x01\x02\x03\x04\x05\x06\a\b"
+      #
+      # ### Default Endianness
+      #
+      #     class MyUnion < Ronin::Support::Binary::Union
+      #     
+      #       endian :big
+      #     
+      #       member :c, :char
+      #       member :i, :int32
+      #       member :u, :uint32
+      #     
+      #     end
+      #     
+      #     union = MyUnion.new(u: 0xaabbccdd)
+      #     union.pack
+      #     # => "\xAA\xBB\xCC\xDD"
+      #
+      # @api public
+      #
+      class Union < Struct
+      end
+    end
+  end
+end

data/lib/ronin/support/binary.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/binary/core_ext'
+require 'ronin/support/binary/template'
+require 'ronin/support/binary/buffer'
+require 'ronin/support/binary/array'
+require 'ronin/support/binary/stack'
+require 'ronin/support/binary/struct'
+require 'ronin/support/binary/union'
+require 'ronin/support/binary/hexdump'