ronin-support 0.4.1 → 0.5.2

data/lib/ronin/formatting/extensions/binary/float.rb

@@ -0,0 +1,65 @@
+#
+# Copyright (c) 2006-2021 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This file is part of ronin-support.
+#
+# 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/binary/template'
+
+class Float
+
+  #
+  # Packs the Float into a String.
+  #
+  # @param [String, Symbol] argument
+  #   The `Array#pack` String code or {Ronin::Binary::Template} type.
+  #
+  # @return [String]
+  #   The packed float.
+  #
+  # @raise [ArgumentError]
+  #   The given Symbol could not be found in
+  #   {Ronin::Binary::Template::FLOAT_TYPES}.
+  #
+  # @example using `Array#pack` template:
+  #   0.42.pack('F')
+  #   # => =\n\xD7>"
+  #
+  # @example using {Ronin::Binary::Template} types:
+  #   0x42.pack(:float_be)
+  #   # => ">\xD7\n="
+  #
+  # @see https://rubydoc.info/stdlib/core/Array:pack
+  # @see Ronin::Binary::Template
+  #
+  # @since 0.5.0
+  #
+  # @api public
+  #
+  def pack(argument)
+    case argument
+    when String
+      [self].pack(argument)
+    else
+      unless Ronin::Binary::Template::FLOAT_TYPES.include?(argument)
+        raise(ArgumentError,"unsupported integer type: #{argument}")
+      end
+
+      [self].pack(Ronin::Binary::Template::TYPES[argument])
+    end
+  end
+
+end

data/lib/ronin/formatting/extensions/binary/integer.rb

@@ -1,37 +1,39 @@
 #
-# Copyright (c) 2006-2012 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2021 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
-# This file is part of Ronin Support.
+# This file is part of ronin-support.
 #
-# Ronin Support is free software: you can redistribute it and/or modify
+# 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,
+# 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 <http://www.gnu.org/licenses/>.
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
 #
 
+require 'ronin/binary/template'
+
 class Integer
 
   #
   # Extracts a sequence of bytes which represent the Integer.
   #
-  # @param [Integer] address_length
+  # @param [Integer] length
   #   The number of bytes to decode from the Integer.
   #
   # @param [Symbol, String] endian
   #   The endianness to use while decoding the bytes of the Integer.
   #   May be one of:
   #
-  #   * `:big` / `"big"`
-  #   * `:little` / `"little"`
-  #   * `:net` / `"net"`
+  #   * `big`
+  #   * `little`
+  #   * `net`
   #
   # @return [Array]
   #   The bytes decoded from the Integer.
@@ -39,9 +41,9 @@ class Integer
   # @raise [ArgumentError]
   #   The given `endian` was not one of:
   #
-  #   * `:little` / `"little"`
-  #   * `:net` / `"net"`
-  #   * `:big` / `"big"`
+  #   * `little`
+  #   * `net`
+  #   * `big`
   #
   # @example
   #   0xff41.bytes(2)
@@ -53,26 +55,26 @@ class Integer
   #
   # @api public
   #
-  def bytes(address_length,endian=:little)
+  def bytes(length,endian=:little)
     endian = endian.to_sym
     buffer = []
 
     case endian
-    when :little, :net
+    when :little
       mask  = 0xff
       shift = 0
 
-      address_length.times do |i|
+      length.times do |i|
         buffer << ((self & mask) >> shift)
 
         mask <<= 8
         shift += 8
       end
-    when :big
-      shift = ((address_length - 1) * 8)
+    when :big, :net
+      shift = ((length - 1) * 8)
       mask  = (0xff << shift)
 
-      address_length.times do |i|
+      length.times do |i|
         buffer << ((self & mask) >> shift)
 
         mask >>= 8
@@ -86,63 +88,77 @@ class Integer
   end
 
   #
-  # Packs the Integer into a String, for a specific architecture and
-  # address-length.
-  #
-  # @param [Ronin::Arch, #endian, #address_length, String] arch
-  #   The architecture to pack the Integer for.
+  # Packs the Integer into a String.
   #
-  # @param [Integer] address_length
-  #   The number of bytes to pack.
+  # @param [String, Symbol, arch] arguments
+  #   The `Array#pack` code, {Ronin::Binary::Template} type or Architecture
+  #   object with `#endian` and `#address_length` methods.
   #
   # @return [String]
   #   The packed Integer.
   #
   # @raise [ArgumentError]
-  #   The given `arch` does not respond to the `endian` or
-  #   `address_length` methods.
+  #   The given Symbol could not be found in
+  #   {Ronin::Binary::Template::INT_TYPES}.
+  #
+  # @example using a `Array#pack` template:
+  #   0x41.pack('V')
+  #   # => "A\0\0\0"
+  #
+  # @example using {Ronin::Binary::Template} types:
+  #   0x41.pack(:uint32_le)
   #
-  # @example using archs other than `Ronin::Arch`.
+  # @example using archs other than `Ronin::Arch` (**deprecated**):
   #   arch = OpenStruct.new(:endian => :little, :address_length => 4)
-  #   
+  #
   #   0x41.pack(arch)
   #   # => "A\0\0\0"
   #
-  # @example using a `Ronin::Arch` arch.
+  # @example using a `Ronin::Arch` arch (**deprecated**):
   #   0x41.pack(Arch.i686)
   #   # => "A\0\0\0"
   #
-  # @example specifying a custom address-length.
+  # @example specifying a custom address-length (**deprecated**):
   #   0x41.pack(Arch.ppc,2)
   #   # => "\0A"
   #
-  # @example using a `Array#pack` template String for the arch.
-  #   0x41.pack('L')
-  #   # => "A\0\0\0"
-  #
-  # @see http://ruby-doc.org/core/classes/Array.html#M002222
+  # @see https://rubydoc.info/stdlib/core/Array:pack
+  # @see Ronin::Binary::Template
   #
   # @api public
   #
-  def pack(arch,address_length=nil)
-    if arch.kind_of?(String)
-      return [self].pack(arch)
-    end
+  def pack(*arguments)
+    if (arguments.length == 1 && arguments.first.kind_of?(String))
+      [self].pack(arguments.first)
+    elsif (arguments.length == 1 && arguments.first.kind_of?(Symbol))
+      type = arguments.first
 
-    unless arch.respond_to?(:address_length)
-      raise(ArgumentError,"first argument to Ineger#pack must respond to address_length")
-    end
+      unless Ronin::Binary::Template::INT_TYPES.include?(type)
+        raise(ArgumentError,"unsupported integer type: #{type}")
+      end
 
-    unless arch.respond_to?(:endian)
-      raise(ArgumentError,"first argument to Ineger#pack must respond to endian")
-    end
+      [self].pack(Ronin::Binary::Template::TYPES[type])
+    elsif (arguments.length == 1 || arguments.length == 2)
+      # TODO: deprecate this calling convention
+      arch, address_length = arguments
 
-    address_length ||= arch.address_length
+      unless arch.respond_to?(:address_length)
+        raise(ArgumentError,"first argument to Ineger#pack must respond to address_length")
+      end
 
-    integer_bytes = bytes(address_length,arch.endian)
-    integer_bytes.map! { |b| b.chr }
+      unless arch.respond_to?(:endian)
+        raise(ArgumentError,"first argument to Ineger#pack must respond to endian")
+      end
 
-    return integer_bytes.join
+      address_length ||= arch.address_length
+
+      integer_bytes = bytes(address_length,arch.endian)
+      integer_bytes.map! { |b| b.chr }
+
+      return integer_bytes.join
+    else
+      raise(ArgumentError,"wrong number of arguments (#{arguments.length} for 1..2)")
+    end
   end
 
   #

data/lib/ronin/formatting/extensions/binary/string.rb

@@ -1,27 +1,27 @@
 #
-# Copyright (c) 2006-2012 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2021 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
-# This file is part of Ronin Support.
+# This file is part of ronin-support.
 #
-# Ronin Support is free software: you can redistribute it and/or modify
+# 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,
+# 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 <http://www.gnu.org/licenses/>.
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
 #
 
+require 'ronin/formatting/extensions/binary/base64'
 require 'ronin/formatting/extensions/binary/integer'
-require 'ronin/formatting/extensions/text'
-
-require 'base64'
-require 'enumerator'
+require 'ronin/formatting/extensions/text/string'
+require 'ronin/binary/hexdump/parser'
+require 'ronin/binary/template'
 
 begin
   require 'zlib'
@@ -31,9 +31,45 @@ end
 
 class String
 
+  alias unpack_original unpack
+
+  #
+  # Unpacks the String.
+  #
+  # @param [String, Array<Symbol, (Symbol, Integer)>] arguments
+  #   The `String#unpack` template or a list of {Ronin::Binary::Template} types.
+  #
+  # @return [Array]
+  #   The values unpacked from the String.
+  #
+  # @raise [ArgumentError]
+  #   One of the arguments was not a known {Ronin::Binary::Template} type.
+  #
+  # @example using {Ronin::Binary::Template} types:
+  #   "A\0\0\0hello\0".unpack(:uint32_le, :string)
+  #   # => [10, "hello"]
+  #
+  # @example using a `String#unpack` template:
+  #   "A\0\0\0".unpack('V')
+  #   # => 65
+  #
+  # @see https://rubydoc.info/stdlib/core/String:unpack
+  # @see Ronin::Binary::Template
+  #
+  # @since 0.5.0
+  #
+  # @api public
+  #
+  def unpack(*arguments)
+    if (arguments.length == 1 && arguments.first.kind_of?(String))
+      unpack_original(arguments.first)
+    else
+      unpack_original(Ronin::Binary::Template.compile(arguments))
+    end
+  end
+
   #
-  # Packs an Integer from a String, which was originally packed for
-  # a specific architecture and address-length.
+  # Unpacks the String into an Integer.
   #
   # @param [Ronin::Arch, #endian, #address_length, String] arch
   #   The architecture that the Integer was originally packed with.
@@ -45,34 +81,35 @@ class String
   #   The depacked Integer.
   #
   # @raise [ArgumentError]
-  #   The given `arch` does not respond to the `endian` or
-  #   `address_length` methods.
+  #   The given `arch` does not respond to the `endian` or `address_length`
+  #   methods.
   #
-  # @example using archs other than `Ronin::Arch`.
+  # @example using archs other than `Ronin::Arch`:
   #   arch = OpenStruct.new(:endian => :little, :address_length => 4)
   #   
   #   "A\0\0\0".depack(arch)
   #   # => 65
   #
-  # @example using a `Ronin::Arch` arch.
+  # @example using a `Ronin::Arch` arch:
   #   "A\0\0\0".depack(Arch.i386)
   #   # => 65
   #
-  # @example specifying a custom address-length.
+  # @example specifying a custom address-length:
   #   "A\0".depack(Arch.ppc,2)
   #   # => 65
   #
-  # @example using a `String#unpack` template String as the arch.
-  #   "A\0\0\0".depack('L')
+  # @example using a `String#unpack` template:
+  #   "A\0\0\0".depack('V')
   #   # => 65
   #
-  # @see http://ruby-doc.org/core/classes/String.html#M000760
+  # @deprecated
+  #   Deprecated as of 0.5.0, use {#unpack} instead.
   #
   # @api public
-  #
+  #   
   def depack(arch,address_length=nil)
     if arch.kind_of?(String)
-      return self.unpack(arch)
+      return unpack(arch)
     end
 
     unless arch.respond_to?(:address_length)
@@ -86,7 +123,7 @@ class String
     endian           = arch.endian.to_sym
     address_length ||= arch.address_length
 
-    integer = 0x0
+    integer    = 0x0
     byte_index = 0
 
     case endian
@@ -128,66 +165,7 @@ class String
     format_bytes(options) { |b| b.hex_escape }
   end
 
-  #
-  # Unescapes the hex-escaped String.
-  #
-  # @return [String]
-  #   The unescaped version of the hex escaped String.
-  #
-  # @example
-  #   "\\x68\\x65\\x6c\\x6c\\x6f".hex_unescape
-  #   # => "hello"
-  #
-  # @api public
-  #
-  def hex_unescape
-    buffer = ''
-    hex_index = 0
-    hex_length = length
-
-    while (hex_index < hex_length)
-      hex_substring = self[hex_index..-1]
-
-      if hex_substring =~ /^\\[0-7]{3}/
-        buffer << hex_substring[0..3].to_i(8)
-        hex_index += 3
-      elsif hex_substring =~ /^\\x[0-9a-fA-F]{1,2}/
-        hex_substring[2..-1].scan(/^[0-9a-fA-F]{1,2}/) do |hex_byte|
-          buffer << hex_byte.to_i(16)
-          hex_index += (2 + hex_byte.length)
-        end
-      elsif hex_substring =~ /^\\./
-        escaped_char = hex_substring[1..1]
-
-        buffer << case escaped_char
-                  when '0'
-                    "\0"
-                  when 'a'
-                    "\a"
-                  when 'b'
-                    "\b"
-                  when 't'
-                    "\t"
-                  when 'n'
-                    "\n"
-                  when 'v'
-                    "\v"
-                  when 'f'
-                    "\f"
-                  when 'r'
-                    "\r"
-                  else
-                    escaped_char
-                  end
-        hex_index += 2
-      else
-        buffer << hex_substring[0]
-        hex_index += 1
-      end
-    end
-
-    return buffer
-  end
+  alias hex_unescape unescape
 
   #
   # XOR encodes the String.
@@ -210,12 +188,9 @@ class String
   #
   def xor(key)
     key = case key
-          when Integer
-            [key]
-          when String
-            key.bytes
-          else
-            key
+          when Integer then [key]
+          when String  then key.bytes
+          else              key
           end
 
     key    = key.cycle
@@ -249,22 +224,9 @@ class String
   #
   def base64_encode(mode=nil)
     case mode
-    when :strict
-      if RUBY_VERSION < '1.9'
-        # backported from Ruby 1.9.2
-        [self].pack("m")
-      else
-        Base64.strict_encode64(self)
-      end
-    when :url, :urlsafe
-      if RUBY_VERSION < '1.9'
-        # backported from Ruby 1.9.2
-        [self].pack("m").tr("+/", "-_")
-      else
-        Base64.urlsafe_encode64(self)
-      end
-    else
-      Base64.encode64(self)
+    when :strict        then Base64.strict_encode64(self)
+    when :url, :urlsafe then Base64.urlsafe_encode64(self)
+    else                     Base64.encode64(self)
     end
   end
 
@@ -292,22 +254,9 @@ class String
   #
   def base64_decode(mode=nil)
     case mode
-    when :strict
-      if RUBY_VERSION < '1.9'
-        # backported from Ruby 1.9.2
-        unpack("m0").first
-      else
-        Base64.strict_decode64(self)
-      end
-    when :url, :urlsafe
-      if RUBY_VERSION < '1.9'
-        # backported from Ruby 1.9.2
-        tr("-_", "+/").unpack("m0").first
-      else
-        Base64.urlsafe_decode64(self)
-      end
-    else
-      Base64.decode64(self)
+    when :strict        then Base64.strict_decode64(self)
+    when :url, :urlsafe then Base64.urlsafe_decode64(self)
+    else                     Base64.decode64(self)
     end
   end
 
@@ -362,108 +311,35 @@ class String
   #   * `:octal_bytes`
   #   * `:octal_shorts`
   #   * `:octal_ints`
-  #   * `:octal_quads`
+  #   * `:octal_quads` (Ruby 1.9 only)
   #   * `:decimal`
   #   * `:decimal_bytes`
   #   * `:decimal_shorts`
   #   * `:decimal_ints`
-  #   * `:decimal_quads`
+  #   * `:decimal_quads` (Ruby 1.9 only)
   #   * `:hex`
+  #   * `:hex_chars`
   #   * `:hex_bytes`
   #   * `:hex_shorts`
   #   * `:hex_ints`
   #   * `:hex_quads`
+  #   * `:named_chars` (Ruby 1.9 only)
+  #   * `:floats`
+  #   * `:doubles`
+  #
+  # @option options [:little, :big, :network] :endian (:little)
+  #   The endianness of the words.
   #
   # @option options [Integer] :segment (16)
   #   The length in bytes of each segment in the hexdump.
   #
-  # @return [String] The raw-data from the hexdump.
+  # @return [String]
+  #   The raw-data from the hexdump.
   #
   # @api public
   #
   def unhexdump(options={})
-    case (format = options[:format])
-    when :od
-      address_base = 8
-      base         = 8
-      word_size    = 2
-    when :hexdump
-      address_base = 16
-      base         = 16
-      word_size    = 2
-    else
-      address_base = 16
-      base         = 16
-      word_size    = 1
-    end
-
-    case options[:encoding]
-    when :binary
-      base = 2
-    when :octal, :octal_bytes, :octal_shorts, :octal_ints, :octal_quads
-      base = 8
-    when :decimal, :decimal_bytes, :decimal_shorts, :decimal_ints, :decimal_quads
-      base = 10
-    when :hex, :hex_bytes, :hex_shorts, :hex_ints, :hex_quads
-      base = 16
-    end
-
-    case options[:encoding]
-    when :binary, :octal_bytes, :decimal_bytes, :hex_bytes
-      word_size = 1
-    when :octal_shorts, :decimal_shorts, :hex_shorts
-      word_size = 2
-    when :octal_ints, :decimal_ints, :hex_ints
-      word_size = 4
-    when :octal_quads, :decimal_quads, :hex_quads
-      word_size = 8
-    end
-
-    current_addr = last_addr = first_addr = nil
-    repeated = false
-
-    segment_length = (options[:segment] || 16)
-    segment = []
-    buffer = []
-
-    each_line do |line|
-      if format == :hexdump
-        line = line.gsub(/\s+\|.+\|\s*$/,'')
-      end
-
-      words = line.split
-
-      if words.first == '*'
-        repeated = true
-      elsif words.length > 0
-        current_addr = words.shift.to_i(address_base)
-        first_addr ||= current_addr
-
-        if repeated
-          (((current_addr - last_addr) / segment.length) - 1).times do
-            buffer += segment
-          end
-
-          repeated = false
-        end
-
-        segment.clear
-
-        words.each do |word|
-          if (base != 10 && word =~ /^(\\[0abtnvfr\\]|.)$/)
-            word.hex_unescape.each_byte { |b| segment << b }
-          else
-            segment += word.to_i(base).bytes(word_size)
-          end
-        end
-
-        segment = segment[0,segment_length]
-        buffer += segment
-        last_addr = current_addr
-      end
-    end
-
-    return buffer[0,(last_addr - first_addr)]
+    Ronin::Binary::Hexdump::Parser.new(options).parse(self)
   end
 
 end