elftools 1.3.1 → 2.1.0

data/lib/elftools/dynamic/hash_table.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require 'elftools/structs'
+
+module ELFTools
+  module Dynamic
+    # A table of names the loader looks a symbol up in, instead of searching
+    # the symbol table for it.
+    #
+    # A file records one of two kinds, or both of them. Both answer the same
+    # two questions, how far the symbol table they index reaches and which
+    # index a name sits at, and differ in how they are laid out, in how they
+    # hash a name, and in which symbols they index at all.
+    class HashTable
+      # Instantiate a {ELFTools::Dynamic::HashTable} object.
+      # @param [#pos=, #read] stream Streaming object.
+      # @param [Integer] offset The file offset the table starts at.
+      # @param [Integer] elf_class 32 or 64, the width of a mask of the table.
+      # @param [Symbol] endian +:little+ or +:big+.
+      def initialize(stream, offset, elf_class:, endian:)
+        @stream = stream
+        @offset = offset
+        @elf_class = elf_class
+        @endian = endian
+      end
+
+      # Whether the table is built over every symbol rather than over a subset
+      # of them.
+      #
+      # Two things follow where it is. How many symbols it is built over is how
+      # many there are, rather than how far it reaches. And a name it does not
+      # lead to is not one the file records, so nothing is left to search.
+      # @return [Boolean] The answer.
+      def covers_every_symbol?
+        false
+      end
+
+      private
+
+      # The header the table starts with.
+      # @return [ELFTools::Structs::ELFStruct] The header.
+      def header
+        @header ||= begin
+          @stream.pos = @offset
+          self.class::HEADER.new(endian: @endian).read(@stream)
+        end
+      end
+
+      # Reads the four-byte word at an offset into the table, the unit buckets
+      # and chains are laid out in.
+      # @param [Integer] offset The offset into the table.
+      # @return [Integer] The word.
+      def word_at(offset)
+        read_at(offset, 4)
+      end
+
+      # Reads an unsigned integer at an offset into the table.
+      # @param [Integer] offset The offset into the table.
+      # @param [Integer] bytes How many bytes it takes, 4 or 8.
+      # @return [Integer] The integer.
+      def read_at(offset, bytes)
+        @stream.pos = @offset + offset
+        @stream.read(bytes).unpack1("#{bytes == 4 ? 'L' : 'Q'}#{@endian == :big ? '>' : '<'}")
+      end
+
+      # The table +DT_HASH+ points at, which the System V ABI defines.
+      #
+      # A chain of it belongs to every symbol, so it is the one table that
+      # records how many there are.
+      class SysV < HashTable
+        # The header the table starts with.
+        HEADER = Structs::ELF_Hash
+
+        # How many symbols the table is built over, which it records outright.
+        # @return [Integer] The number.
+        def num_symbols
+          header.nchain.to_i
+        end
+
+        # (see ELFTools::Dynamic::HashTable#covers_every_symbol?)
+        def covers_every_symbol?
+          true
+        end
+
+        # The index a name sits at.
+        #
+        # A bucket leads to a chain of the indices whose names hash alike, so
+        # the block is what tells them apart.
+        # @param [String] name The name.
+        # @yieldparam [Integer] index An index whose name hashes like +name+.
+        # @yieldreturn [Boolean] Whether the symbol there is the one wanted.
+        # @return [Integer, nil]
+        #   The index, +nil+ if the table does not lead to the name.
+        def index_of(name)
+          return if header.nbucket.to_i.zero?
+
+          n = word_at(buckets + ((hash_of(name) % header.nbucket.to_i) * 4))
+          # Index zero is the undefined symbol, so it ends a chain instead of
+          # belonging to one.
+          while n.positive? && n < num_symbols
+            return n if yield(n)
+
+            n = word_at(chain + (n * 4))
+          end
+        end
+
+        private
+
+        # Where the buckets start, as an offset into the table.
+        # @return [Integer] The offset.
+        def buckets
+          header.num_bytes
+        end
+
+        # Where the chains start, as an offset into the table.
+        # @return [Integer] The offset.
+        def chain
+          buckets + (header.nbucket.to_i * 4)
+        end
+
+        # The hash the System V ABI defines, which keeps a name in 28 bits.
+        # @param [String] name The name.
+        # @return [Integer] The hash.
+        def hash_of(name)
+          name.each_byte.reduce(0) do |h, c|
+            h = (h << 4) + c
+            top = h & 0xf000_0000
+            (h ^ (top >> 24)) & ~top
+          end
+        end
+      end
+
+      # The table +DT_GNU_HASH+ points at.
+      #
+      # It only indexes the defined symbols a file exports under a name, and
+      # the symbols before {#symndx} are by construction not among them, so a
+      # name it does not lead to may still be in the symbol table.
+      class Gnu < HashTable
+        # The header the table starts with.
+        HEADER = Structs::ELF_GnuHash
+
+        # How far the table reaches, i.e. the highest index it indexes plus one.
+        # @return [Integer] The number.
+        def num_symbols
+          last = Array.new(header.nbuckets.to_i) { |i| word_at(buckets + (i * 4)) }.max || 0
+          return symndx if last < symndx
+
+          n = last - symndx
+          n += 1 while word_at(chain + (n * 4)).even?
+          symndx + n + 1
+        end
+
+        # The index a name sits at.
+        #
+        # A bucket leads to a chain of the indices whose names hash alike, so
+        # the block is what tells them apart.
+        # @param [String] name The name.
+        # @yieldparam [Integer] index An index whose name hashes like +name+.
+        # @yieldreturn [Boolean] Whether the symbol there is the one wanted.
+        # @return [Integer, nil]
+        #   The index, +nil+ if the table does not lead to the name.
+        def index_of(name, &block)
+          return if header.nbuckets.to_i.zero? || header.maskwords.to_i.zero?
+
+          h = hash_of(name)
+          return unless may_index?(h)
+
+          n = word_at(buckets + ((h % header.nbuckets.to_i) * 4))
+          return if n.zero? || n < symndx
+
+          walk(n, h, &block)
+        end
+
+        private
+
+        # The first symbol index the table indexes.
+        # @return [Integer] The index.
+        def symndx
+          header.symndx.to_i
+        end
+
+        # Where the buckets start, as an offset into the table.
+        # @return [Integer] The offset.
+        def buckets
+          header.num_bytes + (header.maskwords.to_i * @elf_class / 8)
+        end
+
+        # Where the chains start, as an offset into the table.
+        # @return [Integer] The offset.
+        def chain
+          buckets + (header.nbuckets.to_i * 4)
+        end
+
+        # Walks the chain a bucket leads to, whose entries are the hashes of
+        # the names it holds, with the lowest bit marking the last of them.
+        # @param [Integer] index The index the bucket leads to.
+        # @param [Integer] hash The hash of the name wanted.
+        # @return [Integer, nil] The index, +nil+ if the chain ends without it.
+        def walk(index, hash)
+          loop do
+            # The lowest bit belongs to the chain rather than to the hash.
+            value = word_at(chain + ((index - symndx) * 4))
+            return index if (value | 1) == (hash | 1) && yield(index)
+            break if value.odd?
+
+            index += 1
+          end
+        end
+
+        # Whether the filter in front of the table rules a hash out, which it
+        # answers for a name the file does not export without the table being
+        # read at all. Looking a name up across a chain of files is what it is
+        # there for.
+        # @param [Integer] hash The hash.
+        # @return [Boolean] Whether the name may be indexed.
+        def may_index?(hash)
+          width = @elf_class / 8
+          word = read_at(header.num_bytes + (((hash / @elf_class) % header.maskwords.to_i) * width), width)
+          mask = (1 << (hash % @elf_class)) | (1 << ((hash >> header.shift2.to_i) % @elf_class))
+          word & mask == mask
+        end
+
+        # The hash GNU defines, which is djb2.
+        # @param [String] name The name.
+        # @return [Integer] The hash.
+        def hash_of(name)
+          name.each_byte.reduce(5381) { |h, c| ((h * 33) + c) & 0xffff_ffff }
+        end
+      end
+    end
+  end
+end

data/lib/elftools/dynamic/string_table.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'elftools/util'
+
+module ELFTools
+  module Dynamic
+    # The names a file records, which the tags point at rather than a section.
+    #
+    # Answers what {ELFTools::Sections::StrTabSection} answers, so that what is
+    # read from the tags names itself the way what is read from the sections
+    # does.
+    class StringTable
+      # Instantiate a {ELFTools::Dynamic::StringTable} object.
+      # @param [#pos=, #read] stream Streaming object.
+      # @param [Method] offset
+      #   Call this method to get the file offset the table starts at.
+      def initialize(stream, offset)
+        @stream = stream
+        @offset = offset
+      end
+
+      # Return the name recorded at an offset into the table.
+      # @param [Integer] offset Usually from +tag.d_val+ or +sym.st_name+.
+      # @return [String] The name without null bytes.
+      def name_at(offset)
+        Util.cstring(@stream, @offset.call + offset)
+      end
+    end
+  end
+end

data/lib/elftools/dynamic/symbols.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'elftools/dynamic/hash_table'
+require 'elftools/exceptions'
+require 'elftools/sections/symbol'
+require 'elftools/structs'
+
+module ELFTools
+  module Dynamic
+    # The symbols a file is loaded by, which the tags point at.
+    #
+    # @note
+    #   This module is included by {ELFTools::Dynamic} and reads through the
+    #   methods there, so it cannot be included on its own.
+    module Symbols
+      # Get the +n+-th symbol.
+      #
+      # Symbols are lazy loaded.
+      # @note
+      #   We cannot do bound checking of +n+ here, because nothing records how
+      #   many symbols there are. {#num_symbols} is a lower bound rather than a
+      #   bound, so checking against it would hide symbols this method reads
+      #   correctly.
+      # @param [Integer] n The index.
+      # @return [ELFTools::Sections::Symbol] The desired symbol.
+      # @raise [ELFTools::ELFError]
+      #   If +DT_SYMTAB+ is absent, or its address is not in any loadable segment.
+      def symbol_at(n)
+        return if n.negative?
+
+        @symbol_at_map ||= {}
+        @symbol_at_map[n] ||= begin
+          sym = read_struct(Structs::ELF_sym[header.elf_class], sym_offset + (n * sym_entsize))
+          Sections::Symbol.new(sym, stream, symstr: method(:string_table), machine: @machine,
+                                            version: -> { version_at(n) })
+        end
+      end
+
+      # How many symbols the tags reach.
+      #
+      # A hash table that records the number outright is answered with, because
+      # nothing a file records can reach further than the table it counts.
+      #
+      # Where the file records no such table, nothing records how large its
+      # symbol table is. The loader never enumerates it: it looks a name up
+      # through a hash table and jumps straight to an index, so where the table
+      # ends is none of its business. Two things bound it instead, the hash
+      # table that indexes the names a file exports and the relocations that
+      # name a symbol by index, and the answer is how far the further of the two
+      # reaches.
+      #
+      # That answer is a lower bound. A symbol that is neither indexed by the
+      # hash table nor named by a relocation is invisible to both, and is
+      # missing from the count. {#symbol_at} is exact for any index.
+      # @return [Integer] The number.
+      # @example
+      #   elf.dynamic.num_symbols
+      #   #=> 9
+      def num_symbols
+        @num_symbols ||= counted_num_symbols || bounded_num_symbols
+      end
+
+      # Iterate all symbols.
+      #
+      # Symbols are lazy loaded, so {#symbol_by_name} only creates the symbols
+      # it has to look at.
+      # @yieldparam [ELFTools::Sections::Symbol] symbol A symbol object.
+      # @yieldreturn [void]
+      # @return [Enumerator<ELFTools::Sections::Symbol>, Array<ELFTools::Sections::Symbol>]
+      #   If block is not given, an enumerator will be returned.
+      #   Otherwise, return array of symbols.
+      def each_symbol(&block)
+        return enum_for(:each_symbol) unless block_given?
+
+        Array.new(num_symbols) { |i| symbol_at(i).tap(&block) }
+      end
+
+      # The name this used to go by, kept so that it keeps working.
+      alias each_symbols each_symbol
+
+      # The symbols the tags point at, which is where a file that has been
+      # stripped of its sections still records them.
+      #
+      # As many of them as {#num_symbols} reaches.
+      # @return [Array<ELFTools::Sections::Symbol>] The symbols.
+      # @example
+      #   elf.dynamic.symbols.map(&:name)
+      #   #=> ['', 'puts', '__stack_chk_fail', 'printf', '__libc_start_main']
+      def symbols
+        each_symbol.to_a
+      end
+
+      # Get symbol by its name.
+      #
+      # The hash tables answer first, which is the lookup the loader itself
+      # performs and takes no scanning. Where one of them is built over every
+      # symbol its answer is the whole answer, and a name it does not lead to
+      # is not one the file records. Otherwise the name is searched for among
+      # the symbols {#symbols} reaches, because a table need only index the
+      # names a file exports and a file need not record one at all.
+      # @param [String] name The name of symbol.
+      # @return [ELFTools::Sections::Symbol, nil] The desired symbol.
+      # @example
+      #   elf.dynamic.symbol_by_name('__libc_start_main').type_name
+      #   #=> 'STT_FUNC'
+      def symbol_by_name(name)
+        # Lazily, so that a table is only read when the ones before it have
+        # not led anywhere.
+        index = hash_tables.lazy.filter_map { |table| table.index_of(name) { |i| symbol_at(i).name == name } }.first
+        return symbol_at(index) if index
+        # A symbol with no name is the one thing such a table leaves out,
+        # having nothing to be indexed by, so it is still searched for.
+        return if !name.empty? && hash_tables.any?(&:covers_every_symbol?)
+
+        each_symbol.find { |symbol| symbol.name == name }
+      end
+
+      private
+
+      # The tables the file records the names it exports in, of whichever kinds
+      # it records.
+      # @return [Array<ELFTools::Dynamic::HashTable>] The tables.
+      def hash_tables
+        @hash_tables ||= { hash: HashTable::SysV, gnu_hash: HashTable::Gnu }.filter_map do |type, klass|
+          tag = tag_by_type(type)
+          klass.new(stream, offset_of(tag), elf_class: header.elf_class, endian:) if tag
+        end
+      end
+
+      # How many symbols a table that counts them says there are.
+      # @return [Integer, nil] The number, +nil+ if the file records no such table.
+      def counted_num_symbols
+        hash_tables.find(&:covers_every_symbol?)&.num_symbols
+      end
+
+      # How far what the file records reaches, for a file that counts its
+      # symbols nowhere. Reading the relocations is what costs, so it is only
+      # done for such a file.
+      # @return [Integer] The number, zero if nothing reaches a symbol.
+      def bounded_num_symbols
+        (hash_tables.map(&:num_symbols) + [count_from_relocations]).compact.max || 0
+      end
+
+      # How far the relocations reach, i.e. the highest index they name plus one.
+      # They only ever name the symbols something in the file refers to.
+      # @return [Integer, nil] The number, +nil+ if none names a symbol.
+      def count_from_relocations
+        highest = relocations.map(&:symbol_index).max
+        highest && highest + 1
+      end
+
+      # How many bytes an entry of the symbol table takes, which is what its
+      # structure takes, which is also what +DT_SYMENT+ records and what a file
+      # has no way of disagreeing with.
+      # @return [Integer] The number.
+      def sym_entsize
+        @sym_entsize ||= struct(Structs::ELF_sym[header.elf_class]).num_bytes
+      end
+
+      # Get the +DT_SYMTAB+'s +d_val+ offset related to file.
+      # @return [Integer] The file offset.
+      # @raise [ELFTools::ELFError]
+      #   If +DT_SYMTAB+ is absent, or its address is not in any loadable segment.
+      def sym_offset
+        @sym_offset ||= begin
+          symtab = tag_by_type(:symtab)
+          raise ELFError, 'DT_SYMTAB not found' if symtab.nil?
+
+          offset_of(symtab)
+        end
+      end
+    end
+  end
+end

data/lib/elftools/dynamic/tag.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'elftools/constants'
+
+module ELFTools
+  module Dynamic
+    # A tag class.
+    class Tag
+      attr_reader :header # @return [ELFTools::Structs::ELF_Dyn] The dynamic tag header.
+      attr_reader :stream # @return [#pos=, #read] Streaming object.
+
+      # Instantiate a {ELFTools::Dynamic::Tag} object.
+      # @param [ELF_Dyn] header The dynamic tag header.
+      # @param [#pos=, #read] stream Streaming object.
+      # @param [ELFTools::Dynamic::StringTable] strtab
+      #   The string table the names of tags are recorded in.
+      def initialize(header, stream, strtab)
+        @header = header
+        @stream = stream
+        @strtab = strtab
+      end
+
+      # Some dynamic have name.
+      TYPE_WITH_NAME = [Constants::DT_NEEDED,
+                        Constants::DT_SONAME,
+                        Constants::DT_RPATH,
+                        Constants::DT_RUNPATH].freeze
+      # Return the content of this tag records.
+      #
+      # For normal tags, this method just return
+      # +header.d_val+. For tags with +header.d_val+
+      # in meaning of string offset (e.g. DT_NEEDED), this method would
+      # return the string it specified.
+      # Tags with type in {TYPE_WITH_NAME} are those tags with name.
+      # @return [Integer, String] The content this tag records.
+      # @example
+      #   dynamic = elf.segment_by_type(:dynamic)
+      #   dynamic.tag_by_type(:init).value
+      #   #=> 4195600 # 0x400510
+      #   dynamic.tag_by_type(:needed).value
+      #   #=> 'libc.so.6'
+      def value
+        name || header.d_val.to_i
+      end
+
+      # Is this tag has a name?
+      #
+      # The criteria here is if this tag's type is in {TYPE_WITH_NAME}.
+      # @return [Boolean] Is this tag has a name.
+      def name?
+        TYPE_WITH_NAME.include?(header.d_tag)
+      end
+
+      # Return the name of this tag.
+      #
+      # Only tags with name would return a name.
+      # Others would return +nil+.
+      # @return [String, nil] The name.
+      def name
+        return nil unless name?
+
+        @strtab.name_at(header.d_val.to_i)
+      end
+    end
+  end
+end

data/lib/elftools/dynamic/versions.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'elftools/constants'
+require 'elftools/version_tables'
+
+module ELFTools
+  module Dynamic
+    # The versions a file binds its symbols to.
+    #
+    # Two tables record them, the versions the file needs of the files it is
+    # loaded with and the versions it defines for what it exports, and a symbol
+    # names one of either by the same index.
+    #
+    # @note
+    #   This module is included by {ELFTools::Dynamic} and reads through the
+    #   methods there, so it cannot be included on its own.
+    module Versions
+      # The versions this file needs of the files it is loaded with.
+      # @return [Array<ELFTools::VersionTables::Requirement>]
+      #   The requirements, in the order the table records them.
+      # @example
+      #   elf.dynamic.version_requirements.map { |need| [need.file, need.versions.map(&:name)] }
+      #   #=> [['libc.so.6', ['GLIBC_2.4', 'GLIBC_2.2.5']]]
+      def version_requirements
+        @version_requirements ||= read_table(:verneed, :verneednum) { |at, count| tables.requirements(at, count) }
+      end
+
+      # The versions this file defines for what it exports.
+      #
+      # The first of them is the file itself rather than a version of it, which
+      # {ELFTools::VersionTables::Definition#base?} tells apart.
+      # @return [Array<ELFTools::VersionTables::Definition>]
+      #   The definitions, in the order the table records them.
+      # @example
+      #   elf.dynamic.version_definitions.map(&:name).first(3)
+      #   #=> ['libc.so.6', 'GLIBC_2.2.5', 'GLIBC_2.2.6']
+      def version_definitions
+        @version_definitions ||= read_table(:verdef, :verdefnum) { |at, count| tables.definitions(at, count) }
+      end
+
+      private
+
+      # The version the +n+-th symbol binds to.
+      # @param [Integer] n The symbol index.
+      # @return [ELFTools::VersionTables::Version, nil]
+      #   The version, +nil+ if the file records none, or if the symbol is one
+      #   of the file's own or of no version at all.
+      def version_at(n)
+        VersionTables.version(versym_at(n), versions_by_index)
+      end
+
+      # What the +n+-th symbol records as its version.
+      # @return [Integer, nil] The index, +nil+ if the file records none.
+      def versym_at(n)
+        @versym_offset ||= begin
+          tag = tag_by_type(:versym)
+          tag && offset_of(tag)
+        end
+        return if @versym_offset.nil?
+
+        stream.pos = @versym_offset + (n * 2)
+        stream.read(2).to_s.unpack1(endian == :big ? 'S>' : 'S<')
+      end
+
+      # The tables the tags point at.
+      # @return [ELFTools::VersionTables] The tables.
+      def tables
+        @tables ||= VersionTables.new(stream, string_table, endian:)
+      end
+
+      # Reads a table the tags point at, as many entries as a tag counts.
+      # @return [Array] What the block makes of it, empty without the tags.
+      def read_table(address, count)
+        tag = tag_by_type(address)
+        return [] if tag.nil?
+
+        yield(offset_of(tag), tag_by_type(count).header.d_val.to_i)
+      end
+
+      # The name each index names, of either table.
+      # @return [Hash{Integer => String}] The names.
+      def versions_by_index
+        @versions_by_index ||= VersionTables.names(version_requirements, version_definitions)
+      end
+    end
+  end
+end