ronin-support 0.5.2 → 1.0.0.beta1

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

@@ -0,0 +1,255 @@
+# 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/memory'
+require 'ronin/support/binary/byte_slice'
+require 'ronin/support/binary/ctypes/mixin'
+
+module Ronin
+  module Support
+    module Binary
+      #
+      # Represents an Array of binary types that can be read from and written
+      # to.
+      #
+      # @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
+      #
+      # Creating an array of `int32`s:
+      #
+      #     array = Binary::Array.new(:int32, 4)
+      #     # => #<Ronin::Support::Binary::Binary::Array: "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00">
+      #     array[0] = 0x11111111
+      #     array[1] = 0x22222222
+      #     array[2] = 0x33333333
+      #     array[3] = -1
+      #     array.to_s
+      #     # => "\x11\x11\x11\x11\"\"\"\"3333\xFF\xFF\xFF\xFF"
+      #
+      # Creating an array from an existing String:
+      #
+      #     array = Binary::Array.new(:uint32_le, "\x41\x00\x00\x00\x42\x00\x00\x00")
+      #     # => #<Ronin::Support::Binary::Binary::Array: "A\u0000\u0000\u0000B\u0000\u0000\u0000">
+      #     array[0]
+      #     # => 65
+      #     array[1]
+      #     # => 66
+      #
+      # @api public
+      #
+      # @since 1.0.0
+      #
+      class Array < Memory
+
+        include CTypes::Mixin
+        include Enumerable
+
+        # The underlying type of the data within the array buffer.
+        #
+        # @return [CTypes::Type]
+        attr_reader :type
+
+        # The number of elements in the array buffer.
+        #
+        # @return [Integer]
+        attr_reader :length
+
+        #
+        # Initializes the array buffer.
+        #
+        # @param [Symbol] type
+        #   The type of each element in the array buffer.
+        #
+        # @param [Integer, String, ByteSlice] length_or_string
+        #   The length of the buffer or an existing String which will be used
+        #   as the underlying buffer.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments.
+        #
+        # @option kwargs [:little, :big, :net, nil] :endian
+        #   The desired endianness of the values within the array buffer.
+        #
+        # @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 array buffer.
+        #
+        # @raise [ArgumentError]
+        #   Either the `length_or_string` argument was not an Integer or a
+        #   String.
+        #
+        # @example Creating a new array buffer:
+        #   array = Binary::Array.new(:uint32_le, 10)
+        #   # => #<Ronin::Support::Binary::Binary::Array: "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00">
+        #
+        # @example Creating a new array buffer from a String:
+        #   array = Binary::Array.new(:uint32_le, "\x41\x00\x00\x00\x42\x00\x00\x00")
+        #   # => #<Ronin::Support::Binary::Binary::Array: "A\u0000\u0000\u0000B\u0000\u0000\u0000">
+        #
+        def initialize(type, length_or_string, **kwargs)
+          initialize_type_system(**kwargs)
+
+          @type  = @type_resolver.resolve(type)
+          @cache = []
+
+          case length_or_string
+          when String, ByteSlice
+            super(length_or_string)
+
+            @length = size / @type.size
+          when Integer
+            @length = length_or_string
+
+            super(@type.size * @length)
+          else
+            raise(ArgumentError,"first argument must be either a length (Integer) or a buffer (String): #{length_or_string.inspect}")
+          end
+        end
+
+        #
+        # Reads the struct from the IO stream.
+        #
+        # @param [IO] io
+        #   The IO object to read from.
+        #
+        # @param [Symbol] type
+        #   The desired type of each element in the array.
+        #
+        # @param [Integer] length
+        #   The desired length of the array.
+        #
+        # @return [Binary::Struct]
+        #   The read array.
+        #
+        # @example
+        #   file  = File.new('binary.dat','b')
+        #   array = Binary::Array.read_from(file,:int32,10)
+        #
+        # @see #read_from
+        #
+        def self.read_from(io,type,length)
+          new(type,length).read_from(io)
+        end
+
+        #
+        # Reads a value from the array at the given index.
+        #
+        # @param [Integer] index
+        #   The index to read from.
+        #
+        # @return [Integer, Float, String, Binary::Array, Binary::Struct]
+        #   The integer, float, or character read from the given index.
+        #
+        # @example
+        #   array = Binary::Array.new(:uint32_le, "\x41\x00\x00\x00\x42\x00\x00\x00")
+        #   array[0]
+        #   # => 65
+        #   array[1]
+        #   # => 66
+        #
+        def [](index)
+          offset = index * @type.size
+
+          if (index < 0 || offset+@type.size > size)
+            raise(IndexError,"index #{index} is out of bounds: 0...#{@length}")
+          end
+
+          case @type
+          when CTypes::ObjectType
+            @cache[index] ||= (
+              slice = byteslice(offset,@type.size)
+              @type.unpack(slice)
+            )
+          else
+            data = super(offset,@type.size)
+            @type.unpack(data)
+          end
+        end
+
+        #
+        # Writes a value to the array at the given index.
+        #
+        # @param [Integer] index
+        #   The array index to write the value to.
+        #
+        # @param [Integer, Float, String, Binary::Array, Binary::Struct] value
+        #   The integer, float, or character value to write to the array.
+        #
+        # @return [Integer, Float, String, Binary::Array, Binary::Struct]
+        #   The integer, float, or character value that was written.
+        #
+        # @example
+        #   array = Binary::Array.new(:int32, 4)
+        #   array[0]
+        #   # => 0
+        #   array[0] = 0x11111111
+        #   array[0]
+        #   # => 286331153
+        #   
+        def []=(index,value)
+          offset = index * @type.size
+
+          if (index < 0 || offset+@type.size > size)
+            raise(IndexError,"index #{index} is out of bounds: 0...#{@length}")
+          end
+
+          data = @type.pack(value)
+          return super(offset,@type.size,data)
+        end
+
+        #
+        # Enumerates over every value within the array buffer.
+        #
+        # @yield [value]
+        #   The given block will be passed each value at each index within the
+        #   array buffer.
+        #
+        # @yieldparam [Integer, Float, String] value
+        #   The integer, float, or character read from the array buffer.
+        #
+        # @return [Enumerator]
+        #   If no block was given, an Enumerator will be returned.
+        #
+        def each
+          return enum_for(__method__) unless block_given?
+
+          (0...@length).each do |index|
+            yield self[index]
+          end
+        end
+
+        #
+        # Inspects the array buffer.
+        #
+        # @return [String]
+        #
+        def inspect
+          "#<#{self.class}: #{@string.inspect}>"
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,147 @@
+# 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/>.
+#
+
+module Ronin
+  module Support
+    module Binary
+      #
+      # Methods for performing bit-flipping.
+      #
+      # @api semipublic
+      #
+      module BitFlip
+        module Integer
+          #
+          # Enumerates over every bit flip in the integer.
+          #
+          # @param [Integer, Range(Integer)] bits
+          #   The number of bits to flip or a range of bit indexes to flip.
+          #
+          # @yield [int]
+          #   If a block is given, it will be passed each bit-flipped integer.
+          #
+          # @yieldparam [Integer] int
+          #   The integer but with one of it's bits flipped.
+          #
+          # @return [Enumerator]
+          #   If no block is given, an Enumerator object will be returned.
+          #
+          # @raise [ArgumentError]
+          #   The given bits must be either a Range or an Integer.
+          #
+          # @example bit-flip all eight bits:
+          #   Binary::BitFlip::Byte.each_bit_flip(0x41,8) { |int| puts "%.8b" % int }
+          #
+          # @example bit-flip bits 8-16:
+          #   Binary::BitFlip::Byte.each_bit_flip(0xffff,8...16) { |int| puts "%.16b" % int }
+          #
+          def self.each_bit_flip(int,bits,&block)
+            return enum_for(__method__,int,bits) unless block_given?
+
+            bits = case bits
+                   when ::Range   then bits
+                   when ::Integer then (0...bits)
+                   else
+                     raise(ArgumentError,"bits must be an Integer or a Range: #{bits.inspect}")
+                   end
+
+            bits.each do |bit_index|
+              mask = 1 << bit_index
+
+              yield int ^ mask
+            end
+          end
+
+          #
+          # Returns every bit flip in the integer.
+          #
+          # @param [Integer, Range(Integer)] bits
+          #   The number of bits to flip or a range of bit indexes to flip.
+          #
+          # @return [Array<Integer>]
+          #   The bit-flipped integers.
+          #
+          # @raise [ArgumentError]
+          #   The given bits must be either a Range or an Integer.
+          #
+          # @example bit-flip all eight bits:
+          #   0x41.bit_flips(8)
+          #
+          # @example bit-flip bits 8-16:
+          #   0xffff.bit_flips(8...16)
+          #
+          def self.bit_flips(int,bits)
+            each_bit_flip(int,bits).to_a
+          end
+        end
+
+        module String
+          #
+          # Enumerates over every bit flip of every byte in the string.
+          #
+          # @param [String] string
+          #   The string to bit flip.
+          #
+          # @yield [string]
+          #   If a block is given, it will be passed each bit-flipped string.
+          #
+          # @yieldparam [String] string
+          #   The String, but with one of it's bits flipped.
+          #
+          # @return [Enumerator]
+          #   If no block is given, an Enumerator object will be returned.
+          #
+          # @example bit-flip all bytes in the String:
+          #   Binary::BitFlip.each_bit_flip("foo") { |string| puts string }
+          #
+          def self.each_bit_flip(string)
+            return enum_for(__method__,string) unless block_given?
+
+            bits = (0...8)
+
+            string.each_byte.each_with_index do |byte,index|
+              Integer.each_bit_flip(byte,bits) do |flipped_byte|
+                new_string = string.dup
+                new_string.force_encoding(Encoding::ASCII_8BIT)
+                new_string.setbyte(index,flipped_byte)
+                yield new_string
+              end
+            end
+
+            return nil
+          end
+
+          #
+          # Returns every bit flip of every byte in the string.
+          #
+          # @return [Array<String>]
+          #   The bit-flipped strings.
+          #
+          # @example bit-flip all bytes in the String:
+          #   Binary::BitFlip.bit_flips("foo")
+          #
+          # @api public
+          #
+          def self.bit_flips(string)
+            each_bit_flip(string).to_a
+          end
+        end
+      end
+    end
+  end
+end