ronin-support 0.5.1 → 1.0.0.beta1

data/lib/ronin/support/binary/ctypes/unbounded_array_type.rb

@@ -0,0 +1,258 @@
+# 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/aggregate_type'
+require 'ronin/support/binary/ctypes/scalar_type'
+
+module Ronin
+  module Support
+    module Binary
+      module CTypes
+        #
+        # Represents an unbounded array type.
+        #
+        # @api private
+        #
+        # @since 1.0.0
+        #
+        class UnboundedArrayType < AggregateType
+
+          # The type of each element in the unbounded array type.
+          #
+          # @return [Type]
+          attr_reader :type
+
+          #
+          # Initializes the unbounded array type.
+          #
+          # @param [Type] type
+          #   The type of each element in the unbounded array type.
+          #
+          # @raise [ArgumentError]
+          #   Cannot initialize a nested {UnboundedArrayType}.
+          #
+          def initialize(type, alignment: nil)
+            if type.class == UnboundedArrayType
+              raise(ArgumentError,"cannot initialize a nested #{UnboundedArrayType}")
+            end
+
+            @type      = type
+            @alignment = alignment
+
+            super(
+              # "T*" syntax only works on individual pack-string codes,
+              # so we only set #pack_string for scalar types that also have
+              # a #pack_string.
+              pack_string: if @type.kind_of?(ScalarType) && @type.pack_string
+                             "#{@type.pack_string}*"
+                           end
+            )
+          end
+
+          #
+          # The "size" in bytes of the unbounded array type.
+          #
+          # @return [Float::INFINITY]
+          #
+          def size
+            Float::INFINITY
+          end
+
+          #
+          # The alignment, in bytes, for the unbounded array.
+          #
+          # @return [Integer]
+          #
+          def alignment
+            @alignment || @type.alignment
+          end
+
+          #
+          # Creates a copy of the unbounded array type with a different
+          # {#alignment}.
+          #
+          # @param [Integer] new_alignment
+          #   The new alignment for the new unbounded array type.
+          #
+          # @return [ScalarType]
+          #   The new unbounded array type.
+          #
+          def align(new_alignment)
+            self.class.new(@type, alignment: new_alignment)
+          end
+
+          #
+          # The "length" of the unbounded array type.
+          #
+          # @return [Float::INFINITY]
+          #
+          def length
+            Float::INFINITY
+          end
+
+          #
+          # The endianness of each element in the unbounded array.
+          #
+          # @return [:little, :big, nil]
+          #   Indicates whether each element is little-endian, big-endian,
+          #   or `nil` if each element has no endianness.
+          #
+          def endian
+            @type.endian
+          end
+
+          #
+          # Indicates whether each element is signed.
+          #
+          # @return [Boolean]
+          #
+          def signed?
+            @type.signed?
+          end
+
+          #
+          # Indicates whether each element is unsigned.
+          #
+          # @return [Boolean]
+          #
+          def unsigned?
+            @type.unsigned?
+          end
+
+          #
+          # Packs an array of values into the type's binary format.
+          #
+          # @param [Array<Integer, Float, String>] array
+          #   The array to pack.
+          #
+          # @return [String]
+          #   The packed binary data.
+          #
+          # @api public
+          #
+          def pack(array)
+            if @pack_string
+              super(array)
+            else
+              buffer = String.new('', encoding: Encoding::ASCII_8BIT)
+
+              array.each do |element|
+                buffer << @type.pack(element)
+              end
+
+              return buffer
+            end
+          end
+
+          #
+          # Unpacks an array of binary data.
+          #
+          # @param [String] data
+          #   The binary data to unpack.
+          #
+          # @return [Array<Integer, Float, String, nil>]
+          #   The unpacked array.
+          #
+          # @api public
+          #
+          def unpack(data)
+            if @pack_string
+              super(data)
+            else
+              case @type
+              when StringType
+                unpack_strings(data)
+              else
+                type_size = @type.size
+
+                (0...data.bytesize).step(type_size).map do |offset|
+                  @type.unpack(data.byteslice(offset,type_size))
+                end
+              end
+            end
+          end
+
+          #
+          # Enqueues an array of values onto the flat list of values.
+          #
+          # @param [Array] values
+          #   The flat array of values.
+          #
+          # @param [Array] array
+          #   The array to enqueue.
+          #
+          # @api private
+          #
+          def enqueue_value(values,array)
+            array.each do |element|
+              @type.enqueue_value(values,element)
+            end
+          end
+
+          #
+          # Dequeues an array from the flat list of values.
+          #
+          # @param [Array] values
+          #   The flat array of values.
+          #
+          # @return [Array]
+          #   The dequeued array.
+          #
+          # @api private
+          #
+          def dequeue_value(values)
+            array = []
+
+            until values.empty?
+              array << @type.dequeue_value(values)
+            end
+
+            return array
+          end
+
+          private
+
+          #
+          # Unpacks an arbitrary number of null-terminated C Strings.
+          #
+          # @param [String] data
+          #   The binary encoded data.
+          #
+          # @return [Array<String>]
+          #   The unpacked Strings.
+          #
+          def unpack_strings(data)
+            array  = []
+            length = data.bytesize
+            offset = 0
+
+            while offset < length
+              string = @type.unpack(data[offset..])
+              array  << string
+
+              offset += string.bytesize + 1
+            end
+
+            return array
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/binary/ctypes/union_object_type.rb

@@ -0,0 +1,173 @@
+# 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/object_type'
+require 'ronin/support/binary/ctypes/union_type'
+
+module Ronin
+  module Support
+    module Binary
+      module CTypes
+        #
+        # Represents a {Binary::Union} type.
+        #
+        # @api private
+        #
+        # @since 1.0.0
+        #
+        class UnionObjectType < ObjectType
+
+          # The {Union} class.
+          #
+          # @return [Union.class]
+          attr_reader :union_class
+
+          # The type used for packing literal `Hash` values.
+          #
+          # @return [UnionType]
+          attr_reader :union_type
+
+          #
+          # Initializes the memory-mapped union type.
+          #
+          # @param [Union.class] union_class
+          #   The {Union} class.
+          #
+          # @param [UnionType] union_type
+          #   The union type for the union class.
+          #
+          def initialize(union_class,union_type)
+            @union_class = union_class
+            @union_type  = union_type
+
+            super(@union_type.size)
+          end
+
+          #
+          # The size of the union type.
+          #
+          # @return [Integer, Float::INFINITY]
+          #
+          def size
+            @union_type.size
+          end
+
+          #
+          # The alignment, in bytes, of the memory-mapped {Union}.
+          #
+          # @return [Integer]
+          #
+          def alignment
+            @union_type.alignment
+          end
+
+          #
+          # Creates a copy of the union object type with a different
+          # {#alignment}.
+          #
+          # @param [Integer] new_alignment
+          #   The new alignment for the new union object type.
+          #
+          # @return [ScalarType]
+          #   The new union object type.
+          #
+          def align(new_alignment)
+            self.class.new(@union_class,@union_type.align(new_alignment))
+          end
+
+          #
+          # The members of the union type.
+          #
+          # @return [Hash{Symbol => UnionType::Member}]
+          #
+          def members
+            @union_type.members
+          end
+
+          #
+          # Packs the memory-mapped {Union}.
+          #
+          # @param [Binary::Union, Hash] union
+          #   The memory-mapped {Union} object.
+          #
+          # @return [String]
+          #   The underlying binary data for the memory object.
+          #
+          # @raise [ArgumentError]
+          #   The given value was not a {Binary::Union} or `Hash`.
+          #
+          def pack(union)
+            case union
+            when Binary::Union
+              union.to_s
+            when Hash
+              @union_type.pack(union)
+            else
+              raise(ArgumentError,"value must be either a #{Binary::Union} or an #{Hash}: #{union.inspect}")
+            end
+          end
+
+          #
+          # Unpacks the memory-mapped {Union}.
+          #
+          # @param [String] data
+          #   The raw binary data to unpack.
+          #
+          # @return [Binary::Union]
+          #   the unpacked {Union} object.
+          #
+          def unpack(data)
+            @union_class.unpack(data)
+          end
+
+          #
+          # Enqueues the memory-mapped {Union} into the list of values.
+          #
+          # @param [Array] values
+          #   The flat array of values.
+          #
+          # @param [Binary::Union, Hash] union
+          #   The {Union} object to enqueue.
+          #
+          def enqueue_value(values,union)
+            case union
+            when Binary::Union
+              values.push(union.to_s)
+            when Hash
+              values.push(@union_type.pack(union))
+            end
+          end
+
+          #
+          # Dequeues a memory object from the flat list of values.
+          #
+          # @param [Array] values
+          #   The flat array of values.
+          #
+          # @return [Union]
+          #   The dequued {Union} object.
+          #
+          def dequeue_value(values)
+            @union_class.new(values.shift)
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/binary/ctypes/union_type.rb

@@ -0,0 +1,261 @@
+# 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/aggregate_type'
+
+module Ronin
+  module Support
+    module Binary
+      module CTypes
+        #
+        # Represents a `union` type.
+        #
+        # @api private
+        #
+        # @since 1.0.0
+        #
+        class UnionType < AggregateType
+
+          #
+          # Represents a member within a union.
+          #
+          # @api private
+          #
+          # @since 1.0.0
+          #
+          class Member
+
+            # The type of the member.
+            #
+            # @return [Type]
+            attr_reader :type
+
+            #
+            # Initializes the member.
+            #
+            # @param [Type] type
+            #   The type of the member.
+            #
+            def initialize(type)
+              @type = type
+            end
+
+            #
+            # The offset of the member within the union.
+            #
+            # @return [0]
+            #
+            # @note This method is mainly for compatibility with
+            # {StructType::Member#offset}.
+            #
+            def offset
+              0
+            end
+
+            #
+            # The size, in bytes, of the member within the union.
+            #
+            # @return [Integer]
+            #
+            def size
+              @type.size
+            end
+
+            #
+            # The alignment, in bytes, of the member within the union.
+            #
+            # @return [Integer]
+            #
+            def alignment
+              @type.alignment
+            end
+
+          end
+
+          # The members of the union type.
+          #
+          # @return [Hash{Symbol => Member}]
+          attr_reader :members
+
+          # The size of the union type.
+          #
+          # @return [Integer, Float::INFINITY]
+          attr_reader :size
+
+          # The alignment, in bytes, for the union type, so that all members
+          # within the union type are themselves aligned.
+          #
+          # @return [Integer]
+          attr_reader :alignment
+
+          #
+          # Initializes the union type.
+          #
+          # @param [Hash{Symbol => Member}] members
+          #   The members for the union type.
+          #
+          # @param [Integer] size
+          #   The size of the union type.
+          #
+          # @param [Integer] alignment
+          #   The alignment of the union type.
+          #
+          def initialize(members, size: , alignment: )
+            @members   = members
+            @size      = size
+            @alignment = alignment
+
+            super(pack_string: nil)
+          end
+
+          #
+          # Builds the union type from the given fields.
+          #
+          # @param [Hash{Symbol => Type}] fields
+          #   The field names and types for the union type.
+          #
+          # @param [Integer, nil] alignment
+          #   Custom alignment to use instead of the union's alignment.
+          #
+          # @return [UnionType]
+          #   The new union type.
+          #
+          def self.build(fields, alignment: nil)
+            members       = {}
+            max_size      = 0
+            max_alignment = 0
+
+            fields.each do |name,type|
+              members[name] = Member.new(type)
+
+              # omit infinite sizes from the union size
+              if (type.size > max_size) && (type.size != Float::INFINITY)
+                max_size = type.size
+              end
+
+              max_alignment = type.alignment if type.alignment > max_alignment
+            end
+
+            return new(members, size:      max_size,
+                                alignment: alignment || max_alignment)
+          end
+
+          #
+          # Creates a new Hash of the union's uninitialized members.
+          #
+          # @return [Hash]
+          #   The uninitialized values for the new union's members.
+          #
+          def uninitialized_value
+            Hash[@members.map { |name,member|
+              [name, member.type.uninitialized_value]
+            }]
+          end
+
+          #
+          # The number of members within the union.
+          #
+          # @return [Integer]
+          #
+          def length
+            @members.length
+          end
+
+          #
+          # Creates a copy of the union type with a different {#alignment}.
+          #
+          # @param [Integer] new_alignment
+          #   The new alignment for the new union type.
+          #
+          # @return [ScalarType]
+          #   The new union type.
+          #
+          def align(new_alignment)
+            self.class.new(@members, size:        @size,
+                                     alignment:   new_alignment)
+          end
+
+          #
+          # Packs a hash of values into the member's binary layout.
+          #
+          # @param [Hash{Symbol => Integer, Float, String}] hash
+          #   The hash of values to pack.
+          #
+          # @return [String]
+          #   The packed binary data.
+          #
+          def pack(hash)
+            unknown_keys = hash.keys - @members.keys
+
+            unless unknown_keys.empty?
+              raise(ArgumentError,"unknown union members: #{unknown_keys.map(&:inspect).join(', ')}")
+            end
+
+            buffer = if @size == Float::INFINITY
+                       String.new(encoding: Encoding::ASCII_8BIT)
+                     else
+                       String.new("\0" * @size, encoding: Encoding::ASCII_8BIT)
+                     end
+
+            hash.each do |name,value|
+              member = @members.fetch(name)
+              data   = member.type.pack(value)
+
+              if data.bytesize <= @size
+                # if the packed data fits into buffer, overlay it
+                buffer[0,data.bytesize] = data
+              else
+                # otherwise replace the buffer with the larger data
+                buffer = data
+              end
+            end
+
+            return buffer
+          end
+
+          #
+          # Unpacks binary data into a Hash of values using the union's binary
+          # layout.
+          #
+          # @param [String] data
+          #   The binary data to unpack.
+          #
+          # @return [Hash{Symbol => Integer, Float, String, nil}]
+          #   The unpacked hash.
+          #
+          def unpack(data)
+            hash = {}
+
+            @members.each do |name,member|
+              slice = if member.size == Float::INFINITY
+                        data
+                      else
+                        data.byteslice(0,member.size)
+                      end
+
+              hash[name] = member.type.unpack(slice)
+            end
+
+            return hash
+          end
+
+        end
+      end
+    end
+  end
+end