ronin-support 0.5.2 → 1.0.0.beta1

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

@@ -0,0 +1,268 @@
+# 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'
+require 'ronin/support/binary/byte_slice'
+
+module Ronin
+  module Support
+    module Binary
+      #
+      # Base class for all memory objects.
+      #
+      # @api private
+      #
+      # @since 1.0.0
+      #
+      class Memory
+
+        # The underlying String buffer.
+        #
+        # @return [String, ByteSlice]
+        attr_reader :string
+
+        #
+        # Initializes the memory.
+        #
+        # @param [Integer, String, ByteSlice] size_or_string
+        #   The size of the buffer or an existing String which will be used
+        #   as the underlying buffer.
+        #
+        # @raise [ArgumentError]
+        #   The argument was not an Integer, String, or {ByteSlice}.
+        #
+        def initialize(size_or_string)
+          case size_or_string
+          when String, ByteSlice
+            @string = size_or_string
+          when Integer
+            size    = size_or_string
+            @string = String.new("\0" * size, encoding: Encoding::ASCII_8BIT)
+          else
+            raise(ArgumentError,"first argument must be either a size (Integer) or a buffer (String): #{size_or_string.inspect}")
+          end
+        end
+
+        #
+        # The size of the underlying buffer.
+        #
+        # @return [Integer]
+        #
+        def size
+          @string.bytesize
+        end
+
+        #
+        # Reads a character or a substring from the underlying buffer at the
+        # given index.
+        #
+        # @param [Integer, (Integer, Integer), Range(Integer)] index_or_range
+        #   The index or range within the buffer to read from.
+        #
+        # @param [Integer, Float::INFINITY, nil] length
+        #   The optional length in bytes to read.
+        #
+        # @return [String, nil]
+        #   The character or substring at the given index or range.
+        #
+        # @example Reading a single char at the given index:
+        #   memory[0]
+        #   # => "\x00"
+        #
+        # @example Reading multiple chars at the range of indexes:
+        #   memory[0..2]
+        #   # => "\x00\x00"
+        #
+        # @example Reading multiple chars at the given index and length:
+        #   memory[0,2]
+        #   # => "\x00\x00"
+        #
+        def [](index_or_range,length=nil)
+          case index_or_range
+          when Range
+            range = index_or_range
+
+            @string[range]
+          when Integer
+            index  = index_or_range
+
+            case length
+            when Integer         then @string[index,length]
+            when nil             then @string[index]
+            when Float::INFINITY then @string[index,@string.length - index]
+            else
+              raise(ArgumentError,"invalid length (#{length.inspect}) must be an Integer, nil, or Float::INFINITY")
+            end
+          else
+            raise(ArgumentError,"invalid index (#{index_or_range.inspect}) must be an Integer or a Range")
+          end
+        end
+
+        #
+        # Writes a value to the underlying buffer at the given index.
+        #
+        # @param [Integer, Range(Integer)] index_or_range
+        #   The index within the string to write to.
+        #
+        # @param [Integer, Float::INFINITY, nil] length
+        #   Optional additional length argument.
+        #
+        # @param [String] value
+        #   The integer, float, or character value to write to the buffer.
+        #
+        # @return [String]
+        #   The string written into the buffer.
+        #
+        # @example Writing a single char:
+        #   buffer[0] = 'A'
+        #
+        # @example Writing multiple characters to the given range of indexes:
+        #   buffer[0..3] = "AAA"
+        #
+        def []=(index_or_range,length=nil,value)
+          case index_or_range
+          when Range
+            range = index_or_range
+
+            @string[range] = value
+          when Integer
+            index  = index_or_range
+
+            case length
+            when Integer then @string[index,length] = value
+            when nil     then @string[index] = value
+            when Float::INFINITY
+              @string[index,@string.length - index] = value
+            else
+              raise(ArgumentError,"invalid length (#{length.inspect}) must be an Integer, nil, or Float::INFINITY")
+            end
+          else
+            raise(ArgumentError,"invalid index (#{index_or_range.inspect}) must be an Integer or a Range")
+          end
+        end
+
+        #
+        # Returns a byte slice of the memory at the given offset and for the 
+        # remainder of the memory.
+        #
+        # @param [Integer] offset
+        #   The offset for the byte slice within the memory.
+        #
+        # @return [ByteSlice]
+        #   The new byte slice.
+        #
+        # @example
+        #   memory+10
+        #
+        # @example Create a buffer starting at offset 10:
+        #   buffer = Buffer.new(memory+10)
+        #
+        # @example Create an Array starting at offset 10:
+        #   array = Binary::Array.new(:int32_le, memory+10)
+        #
+        def +(offset)
+          ByteSlice.new(@string, offset: offset, length: size - offset)
+        end
+
+        #
+        # Creates a new byte slice within the memory.
+        #
+        # @param [Integer] offset
+        #   The offset of the new byte slice.
+        #
+        # @param [Integer] length
+        #   The length of the new byte slice.
+        #
+        # @return [ByteSlice]
+        #   The new byte slice.
+        #
+        def byteslice(offset,length=1)
+          ByteSlice.new(@string, offset: offset, length: length)
+        end
+
+        #
+        # Clears the memory by setting each byte to 0.
+        #
+        # @return [self]
+        #
+        def clear
+          (0...@string.bytesize).each do |index|
+            @string.setbyte(index,0)
+          end
+
+          return self
+        end
+
+        #
+        # Copies data from this memory object into another memory object.
+        #
+        # @param [Memory] dest
+        #   The destination memory object to copy the data to.
+        #
+        # @param [Integer] count
+        #   The number of bytes to copy.
+        #
+        def copy_to(dest,count=size)
+          dest[0,count] = @string
+        end
+
+        #
+        # Copies data from the other memory object into this memory object.
+        #
+        # @param [Memory] src
+        #   The source memory object to copy the data from.
+        #
+        # @param [Integer] count
+        #   The number of bytes to copy.
+        #
+        def copy_from(src,count=size)
+          @string[0,count] = src[0,count]
+        end
+
+        #
+        # Reads {#size} bytes from the given IO stream.
+        #
+        # @param [IO] io
+        #   The IO stream to read from.
+        #
+        # @return [self]
+        #
+        def read_from(io)
+          data = io.read(size)
+
+          @string[0,data.bytesize] = data
+          return self
+        end
+
+        #
+        # Converts the buffer to a String.
+        #
+        # @return [String]
+        #   The raw binary buffer.
+        #
+        def pack
+          @string.to_s
+        end
+
+        alias to_s pack
+        alias to_str pack
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# 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
+      class Packet < Binary::Struct
+
+        platform endian: :net
+        align 1
+        padding false
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,256 @@
+# 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'
+
+module Ronin
+  module Support
+    module Binary
+      #
+      # Represents a stack that can have binary data pushed to or popped from
+      # it.
+      #
+      # ## Features
+      #
+      # * Supports configurable endianness and architecture.
+      # * Can dump out a formatting binary string for new a stack.
+      # * Can parse an existing stack dump string.
+      # * Supports negative indexing.
+      #
+      # ## Examples
+      #
+      # Creating a new stack:
+      #
+      #     stack = Stack.new
+      #     # => #<Ronin::Support::Binary::Stack: "">
+      #     stack.push 0x41414141
+      #     # => #<Ronin::Support::Binary::Stack: "AAAA\x00\x00\x00\x00">
+      #     stack.push 0x7fffffffdde0
+      #     # => #<Ronin::Support::Binary::Stack: "\xE0\xDD\xFF\xFF\xFF\x7F\x00\x00AAAA\x00\x00\x00\x00">
+      #     stack.push -1
+      #     # => #<Ronin::Support::Binary::Stack: "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xE0\xDD\xFF\xFF\xFF\x7F\x00\x00AAAA\x00\x00\x00\x00">
+      #     stack.to_s
+      #     # => => "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xE0\xDD\xFF\xFF\xFF\x7F\x00\x00AAAA\x00\x00\x00\x00"
+      #
+      # Creating a stack from an existing String:
+      #
+      #     stack = Stack.new("\x41\x00\x00\x00\x00\x00\x00\x00\x42\x00\x00\x00\x00\x00\x00\x00")
+      #     stack[0]
+      #     # => 65
+      #     stack[8]
+      #     # => 66
+      #
+      # Negative indexing within the stack:
+      #
+      #     stack.push(65)
+      #     stack.push(66)
+      #     stack[-8]
+      #     # => 65
+      #     stack[-16]
+      #     # => 66
+      #
+      # **Note:** negative indexes are treated relative to the beginning of the
+      # stack, since stacks grow downward in the address space.
+      #
+      # @api public
+      #
+      # @since 1.0.0
+      #
+      class Stack
+
+        include CTypes::Mixin
+
+        # The "machine word" from the {#type_system}.
+        #
+        # @return [CTypes::UInt32Type, CTypes::UInt64Type]
+        attr_reader :machine_word
+
+        # The number of machine words on the stack.
+        #
+        # @return [Integer]
+        attr_reader :length
+
+        # The size of the stack in bytes.
+        #
+        # @return [Integer]
+        attr_reader :size
+
+        # The underlying buffer for the stack.
+        #
+        # @return [String]
+        attr_reader :string
+
+        #
+        # Initializes the stack.
+        #
+        # @param [String, nil] string
+        #   Optional existing stack contents.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments.
+        #
+        # @option kwargs [:little, :big, :net, nil] :endian
+        #   The desired endianness of the values within the stack.
+        #
+        # @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 stack.
+        #
+        def initialize(string=nil, **kwargs)
+          initialize_type_system(**kwargs)
+
+          @machine_word = @type_system::MACHINE_WORD
+
+          if string
+            @string = string
+            @size   = @string.bytesize
+            @length = @size / @machine_word.size
+          else
+            @string = String.new("", encoding: Encoding::ASCII_8BIT)
+            @size   = 0
+            @length = 0
+          end
+        end
+
+        #
+        # Accesses a machine word at the given index within the stack.
+        #
+        # @param [Integer] index
+        #   The byte offset within the stack to read from.
+        #
+        # @return [Integer]
+        #   The value at the index within the stack.
+        #
+        # @raise [IndexError]
+        #
+        # @note
+        #   negative offsets are treated as relative to the bottom or the
+        #   beginning of the stack, since stack grow downward in the address
+        #   space.
+        #
+        def [](index)
+          offset = if index < 0 then @size + index
+                   else              index
+                   end
+
+          if offset+@machine_word.size > @size
+            raise(IndexError,"index #{index} is out of bounds: 0...#{@size}")
+          end
+
+          data = @string[offset,@machine_word.size]
+          return @machine_word.unpack(data)
+        end
+
+        #
+        # Sets a machine word at the given index within the stack.
+        #
+        # @param [Integer] index
+        #   The byte offset within the stack to write to.
+        #
+        # @param [Integer] value
+        #   The value to write at the index within the stack.
+        #
+        # @return [Integer]
+        #   The written value.
+        #
+        # @raise [IndexError]
+        #
+        # @note
+        #   negative offsets are treated as relative to the bottom or the
+        #   beginning of the stack, since stacks grow downward in the address
+        #   space.
+        #
+        def []=(index,value)
+          offset = if index < 0 then @size + index
+                   else              index
+                   end
+
+          if offset+@machine_word.size > @size
+            raise(IndexError,"index #{index} is out of bounds: 0...#{@size}")
+          end
+
+          data = @machine_word.pack(value)
+          @string[offset,@machine_word.size] = data
+          return value
+        end
+
+        #
+        # Pushes a value onto the top of the stack (or to the end of the
+        # underlying buffer).
+        #
+        # @param [Integer] value
+        #   The value to push onto the stack.
+        #
+        # @return [self]
+        #
+        def push(value)
+          data = @machine_word.pack(value)
+
+          @string.insert(0,data)
+          @length += 1
+          @size   += @machine_word.size
+          return self
+        end
+
+        #
+        # Pops a value off the top of the stack (or to the end of the underlying
+        # buffer).
+        #
+        # @return [Integer]
+        #   The value popped from the stack.
+        #
+        def pop
+          data  = @string.byteslice(0,@machine_word.size)
+          value = @machine_word.unpack(data)
+
+          @length -= 1
+          @size   -= @machine_word.size
+
+          @string = @string.byteslice(@machine_word.size,@size)
+          return value
+        end
+
+        #
+        # Cnnverts the stack into a String.
+        #
+        # @return [String]
+        #   The underlying buffer for the stack.
+        #
+        def to_s
+          @string
+        end
+
+        alias to_str to_s
+
+        #
+        # Inspects the stack object.
+        #
+        # @return [String]
+        #
+        def inspect
+          "#<#{self.class}: #{@string.inspect}>"
+        end
+
+      end
+    end
+  end
+end