elftools 0.1.0

data/lib/elftools/elf_file.rb

@@ -0,0 +1,277 @@
+require 'elftools/constants'
+require 'elftools/exceptions'
+require 'elftools/lazy_array'
+require 'elftools/sections/sections'
+require 'elftools/segments/segments'
+require 'elftools/structures'
+
+module ELFTools
+  # The main class for using elftools.
+  class ELFFile
+    attr_reader :stream # @return [File] The +File+ object.
+    attr_reader :elf_class # @return [Integer] 32 or 64.
+    attr_reader :endian # @return [Symbol] +:little+ or +:big+.
+
+    # Instantiate an {ELFFile} object.
+    #
+    # @param [File] stream
+    #   The +File+ object to be fetch information from.
+    # @example
+    #   ELFFile.new(File.open('/bin/cat'))
+    #   #=> #<ELFTools::ELFFile:0x00564b106c32a0 @elf_class=64, @endian=:little, @stream=#<File:/bin/cat>>
+    def initialize(stream)
+      @stream = stream
+      identify # fetch the most basic information
+    end
+
+    # Return the file header.
+    #
+    # Lazy loading.
+    # @retrn [ELFTools::ELF_Ehdr] The header.
+    def header
+      return @header if @header
+      stream.pos = 0
+      @header = ELF_Ehdr.new(endian: endian)
+      @header.elf_class = elf_class
+      @header.read(stream)
+    end
+
+    # Return the BuildID of ELF.
+    # @return [String, NilClass]
+    #   BuildID in hex form will be returned.
+    #   +nil+ is returned if the .note.gnu.build-id section
+    #   is not found.
+    # @example
+    #   elf.build_id
+    #   #=> '73ab62cb7bc9959ce053c2b711322158708cdc07'
+    def build_id
+      section = section_by_name('.note.gnu.build-id')
+      return nil if section.nil?
+      note = section.notes.first
+      return nil if note.nil?
+      note.desc.unpack('H*').first
+    end
+
+    # Get Machine architecture.
+    #
+    # Mappings of architecture can be found
+    # in {ELFTools::Constants::EM.mapping}.
+    # @return [String]
+    #   Name of architecture.
+    # @example
+    #   elf.machine
+    #   #=> 'Advanced Micro Devices X86-64'
+    def machine
+      ELFTools::Constants::EM.mapping(header.e_machine)
+    end
+
+    #========= method about sections
+
+    # Number of sections in this file.
+    # @return [Integer] The desired number.
+    # @example
+    #   elf.num_sections
+    #   #=> 29
+    def num_sections
+      header.e_shnum
+    end
+
+    # Acquire the section named as +name+.
+    # @param [String] name The desired section name.
+    # @return [ELFTools::Sections::Section, NilClass] The target section.
+    # @example
+    #   elf.section_by_name('.note.gnu.build-id')
+    #   #=> #<ELFTools::Sections::Section:0x005647b1282428>
+    #   elf.section_by_name('')
+    #   #=> #<ELFTools::Sections::NullSection:0x005647b11da110>
+    #   elf.section_by_name('no such section')
+    #   #=> nil
+    def section_by_name(name)
+      @section_name_map ||= {}
+      return @section_name_map[name] if @section_name_map[name]
+      each_sections do |section|
+        @section_name_map[section.name] = section
+        return section if section.name == name
+      end
+      nil
+    end
+
+    # Iterate all sections.
+    #
+    # All sections are lazy loading, the section
+    # only be created whenever accessing it.
+    # This method is useful for {#section_by_name}
+    # since not all sections need to be created.
+    # @param [Block] block
+    #   Just like +Array#each+, you can give a block.
+    # @return [ Array<ELFTools::Sections::Section>]
+    #   The whole sections will be returned.
+    def each_sections
+      Array.new(num_sections) do |i|
+        sec = section_at(i)
+        block_given? ? yield(sec) : sec
+      end
+    end
+
+    # Simply use {#sections} without giving block to get all sections.
+    alias sections each_sections
+
+    # Acquire the +n+-th section, 0-based.
+    #
+    # Sections are lazy loaded.
+    # @param [Integer] n The index.
+    # @return [ELFTools::Sections::Section, NilClass]
+    #   The target section.
+    #   If +n+ is out of bound, +nil+ is returned.
+    def section_at(n)
+      @sections ||= LazyArray.new(num_sections, &method(:create_section))
+      @sections[n]
+    end
+
+    # Get the string table section.
+    #
+    # This section is acquired by using the +e_shstrndx+
+    # in ELF header.
+    # @return [ELFTools::Sections::StrTabSection] The desired section.
+    def strtab_section
+      section_at(header.e_shstrndx)
+    end
+
+    #========= method about segments
+
+    # Number of segments in this file.
+    # @return [Integer] The desited number.
+    def num_segments
+      header.e_phnum
+    end
+
+    # Iterate all segments.
+    #
+    # All segments are lazy loading, the segment
+    # only be created whenever accessing it.
+    # This method is useful for {#segment_by_type}
+    # since not all segments need to be created.
+    # @param [Block] block
+    #   Just like +Array#each+, you can give a block.
+    # @return [Array<ELFTools::Segments::Segment>]
+    #   Whole segments will be returned.
+    def each_segments
+      Array.new(num_segments) do |i|
+        seg = segment_at(i)
+        block_given? ? yield(seg) : seg
+      end
+    end
+
+    # Simply use {#segments} without giving block to get all segments.
+    alias segments each_segments
+
+    # Get the first segment with +p_type=type+.
+    # The available types are listed in {ELFTools::Constants},
+    # starts with +PT_+.
+    #
+    # Notice: this method will return the first segment found,
+    # to found all segments with specific type you can use {#segments_by_type}.
+    # @param [Integer, Symbol, String] type
+    #   See examples for clear usage.
+    # @return [ELFTools::Segments::Segment] The target segment.
+    # @example
+    #   # type as an integer
+    #   elf.segment_by_type(ELFTools::Constants::PT_NOTE)
+    #   #=>  #<ELFTools::Segments::NoteSegment:0x005629dda1e4f8>
+    #
+    #   elf.segment_by_type(4) # PT_NOTE
+    #   #=>  #<ELFTools::Segments::NoteSegment:0x005629dda1e4f8>
+    #
+    #   # type as a symbol
+    #   elf.segment_by_type(:PT_NOTE)
+    #   #=>  #<ELFTools::Segments::NoteSegment:0x005629dda1e4f8>
+    #
+    #   # you can do this
+    #   elf.segment_by_type(:note) # will be transformed into `PT_NOTE`
+    #   #=>  #<ELFTools::Segments::NoteSegment:0x005629dda1e4f8>
+    #
+    #   # type as a string
+    #   elf.segment_by_type('PT_NOTE')
+    #   #=>  #<ELFTools::Segments::NoteSegment:0x005629dda1e4f8>
+    #
+    #   # this is ok
+    #   elf.segment_by_type('note') # will be tranformed into `PT_NOTE`
+    #   #=>  #<ELFTools::Segments::NoteSegment:0x005629dda1e4f8>
+    # @example
+    #   elf.segment_by_type(1337)
+    #   # ArgumentError: No constants in Constants::PT is 1337
+    #
+    #   elf.segment_by_type('oao')
+    #   # ArgumentError: No constants in Constants::PT named "PT_OAO"
+    # @example
+    #   elf.segment_by_type(0)
+    #   #=> nil # no such segment exists
+    def segment_by_type(type)
+      type = Util.to_constant(Constants::PT, type)
+      each_segments do |seg|
+        return seg if seg.header.p_type == type
+      end
+      nil
+    end
+
+    # Fetch all segments with specific type.
+    # If you want to find only one segment,
+    # use {#segment_by_type} instead.
+    # @param [Integer, Symbol, String] type
+    #   The type needed, same format as {#segment_by_type}.
+    # @return [Array<ELFTools::Segments::Segment>] The target segments.
+    def segments_by_type(type)
+      type = Util.to_constant(Constants::PT, type)
+      segments.select { |segment| segment.header.p_type == type }
+    end
+
+    # Acquire the +n+-th segment, 0-based.
+    #
+    # Segments are lazy loaded.
+    # @param [Integer] n The index.
+    # @return [ELFTools::Segments::Segment, NilClass]
+    #   The target segment.
+    #   If +n+ is out of bound, +nil+ is returned.
+    def segment_at(n)
+      @segments ||= LazyArray.new(num_segments, &method(:create_segment))
+      @segments[n]
+    end
+
+    private
+
+    def identify
+      stream.pos = 0
+      magic = stream.read(4)
+      raise ELFError, "Invalid magic number #{magic.inspect}" unless magic == Constants::ELFMAG
+      ei_class = stream.read(1).ord
+      @elf_class = {
+        1 => 32,
+        2 => 64
+      }[ei_class]
+      raise ELFError, format('Invalid EI_CLASS "\x%02x"', ei_class) if elf_class.nil?
+      ei_data = stream.read(1).ord
+      @endian = {
+        1 => :little,
+        2 => :big
+      }[ei_data]
+      raise ELFError, format('Invalid EI_DATA "\x%02x"', ei_data) if endian.nil?
+    end
+
+    def create_section(n)
+      stream.pos = header.e_shoff + n * header.e_shentsize
+      shdr = ELF_Shdr.new(endian: endian)
+      shdr.elf_class = elf_class
+      shdr.read(stream)
+      Sections::Section.create(shdr, stream,
+                               strtab: method(:strtab_section),
+                               section_at: method(:section_at))
+    end
+
+    def create_segment(n)
+      stream.pos = header.e_phoff + n * header.e_phentsize
+      phdr = ELF_Phdr[elf_class].new(endian: endian)
+      phdr.elf_class = elf_class
+      Segments::Segment.create(phdr.read(stream), stream)
+    end
+  end
+end

data/lib/elftools/exceptions.rb

@@ -0,0 +1,3 @@
+module ELFTools
+  class ELFError < StandardError; end
+end

data/lib/elftools/lazy_array.rb

@@ -0,0 +1,43 @@
+module ELFTools
+  # A helper class for {ELFTools} easy to implement
+  # 'lazy loading' objects.
+  # Mainly used when loading sections, segments, and
+  # symbols.
+  class LazyArray
+    # Instantiate a {LazyArray} object.
+    # @param [Integer] size
+    #   The size of array.
+    # @param [Block] block
+    #   At first time accessing +i+-th element,
+    #   block will be called as +block.call(i)+.
+    # @example
+    #   arr = LazyArray.new(10) { |i| p i; i * i }
+    #   p arr[2]
+    #   # 2
+    #   # 4
+    #
+    #   p arr[3]
+    #   # 3
+    #   # 9
+    #
+    #   p arr[3]
+    #   # 9
+    def initialize(size, &block)
+      @internal = Array.new(size)
+      @block = block
+    end
+
+    # To access elements like a normal array.
+    #
+    # Elements are lazy loaded at the first time
+    # access it.
+    # @return [Object]
+    #   The element, returned type is the
+    #   return type of block given in {#initialize}.
+    def [](i)
+      # XXX: support negative index?
+      return nil if i < 0 || i >= @internal.size
+      @internal[i] ||= @block.call(i)
+    end
+  end
+end

data/lib/elftools/note.rb

@@ -0,0 +1,112 @@
+require 'elftools/structures'
+require 'elftools/util'
+
+module ELFTools
+  # Since both note sections and note segments
+  # refer to notes, this module defines common
+  # methods for {ELFTools::Sections::NoteSection} and {ELFTools::Segments::NoteSegment}.
+  #
+  # Notice: this module can only be included in {ELFTools::Sections::NoteSection} and
+  # {ELFTools::Segments::NoteSegment} since some methods assume some attributes already
+  # exist.
+  module Note
+    # Since size of {ELFTools::ELF_Nhdr} will not change no
+    # matter what endian and what arch, we can do this here.
+    # This value should equal to 12.
+    SIZE_OF_NHDR = ELF_Nhdr.new(endian: :little).num_bytes
+
+    # Iterate all notes in a note section or segment.
+    #
+    # Structure of notes are:
+    #   +---------------+
+    #   | Note 1 header |
+    #   +---------------+
+    #   |  Note 1 name  |
+    #   +---------------+
+    #   |  Note 1 desc  |
+    #   +---------------+
+    #   | Note 2 header |
+    #   +---------------+
+    #   |      ...      |
+    #   +---------------+
+    #
+    # Notice: This method assume following methods exist:
+    #   stream
+    #   note_start
+    #   note_total_size
+    # @return [Array<ELFTools::Note::Note>]
+    #   The array of notes will be returned.
+    def each_notes
+      @notes_offset_map ||= {}
+      cur = note_start
+      notes = []
+      while cur < note_start + note_total_size
+        stream.pos = cur
+        @notes_offset_map[cur] ||= create_note(cur)
+        note = @notes_offset_map[cur]
+        # name and desc size needs to be 4-bytes align
+        name_size = Util.align(note.header.n_namesz, 2)
+        desc_size = Util.align(note.header.n_descsz, 2)
+        cur += SIZE_OF_NHDR + name_size + desc_size
+        notes << note
+        yield note if block_given?
+      end
+      notes
+    end
+
+    # Simply +#notes+ to get all notes.
+    alias notes each_notes
+
+    private
+
+    # Get the endian.
+    #
+    # Notice: This method assume method +header+ exists.
+    # @return [Symbol] +:little+ or +:big+.
+    def endian
+      header.class.self_endian
+    end
+
+    def create_note(cur)
+      nhdr = ELF_Nhdr.new(endian: endian).read(stream)
+      ELFTools::Note::Note.new(nhdr, stream, cur)
+    end
+
+    # Class of a note.
+    class Note
+      attr_reader :header # @return [ELFTools::ELF_Nhdr] Note header.
+      attr_reader :stream # @return [File] Streaming object.
+      attr_reader :offset # @return [Integer] Address of this note start, includes note header.
+
+      # Instantiate a {ELFTools::Note::Note} object.
+      # @param [ELF_Nhdr] header The note header.
+      # @param [File] stream Streaming object.
+      # @param [Integer] offset
+      #   Start address of this note, includes the header.
+      def initialize(header, stream, offset)
+        @header = header
+        @stream = stream
+        @offset = offset
+      end
+
+      # Name of this note.
+      # @return [String] The name.
+      def name
+        return @name if @name
+        stream.pos = @offset + SIZE_OF_NHDR
+        @name = stream.read(header.n_namesz)[0..-2]
+      end
+
+      # Description of this note.
+      # @return [String] The description.
+      def desc
+        return @desc if @desc
+        stream.pos = @offset + SIZE_OF_NHDR + Util.align(header.n_namesz, 2)
+        @desc = stream.read(header.n_descsz)
+      end
+
+      # If someone likes to use full name.
+      alias description desc
+    end
+  end
+end

data/lib/elftools/sections/dynamic_section.rb

@@ -0,0 +1,20 @@
+require 'elftools/dynamic'
+require 'elftools/sections/section'
+
+module ELFTools
+  module Sections
+    # Class for dynamic table section.
+    #
+    # This section should always be named .dynamic.
+    # This class knows how to get the list of dynamic tags.
+    class DynamicSection < Section
+      include ELFTools::Dynamic
+
+      # Get the start address of tags.
+      # @return [Integer] Start address of tags.
+      def tag_start
+        header.sh_offset
+      end
+    end
+  end
+end

data/lib/elftools/sections/note_section.rb

@@ -0,0 +1,25 @@
+require 'elftools/note'
+require 'elftools/sections/section'
+
+module ELFTools
+  module Sections
+    # Class of note section.
+    # Note section records notes
+    class NoteSection < Section
+      # Load note related methods.
+      include ELFTools::Note
+
+      # Address offset of notes start.
+      # @return [Integer] The offset.
+      def note_start
+        header.sh_offset
+      end
+
+      # The total size of notes in this section.
+      # @return [Integer] The size.
+      def note_total_size
+        header.sh_size
+      end
+    end
+  end
+end

data/lib/elftools/sections/null_section.rb

@@ -0,0 +1,16 @@
+require 'elftools/sections/section'
+
+module ELFTools
+  module Sections
+    # Class of null section.
+    # Null section is for specific the end
+    # of linked list (+sh_link+) between sections.
+    class NullSection < Section
+      # Is this a null section?
+      # @return [Boolean] Yes it is.
+      def null?
+        true
+      end
+    end
+  end
+end

data/lib/elftools/sections/section.rb

@@ -0,0 +1,44 @@
+require 'elftools/constants'
+module ELFTools
+  module Sections
+    # Base class of sections.
+    class Section
+      attr_reader :header # @return [ELFTools::ELF_Shdr] Section header.
+      attr_reader :stream # @return [File] Streaming object.
+
+      # Instantiate a {Section} object.
+      # @param [ELFTools::ELF_Shdr] header
+      #   The section header object.
+      # @param [File] stream
+      #   The streaming object for further dump.
+      # @param [ELFTools::Sections::StrTabSection, Proc] strtab
+      #   The string table object. For fetching section names.
+      #   If +Proc+ if given, it will call at the first
+      #   time access +#name+.
+      def initialize(header, stream, strtab: nil, **_kwagrs)
+        @header = header
+        @stream = stream
+        @strtab = strtab
+      end
+
+      # Get name of this section.
+      # @return [String] The name.
+      def name
+        @name ||= @strtab.call.name_at(header.sh_name)
+      end
+
+      # Fetch data of this section.
+      # @return [String] Data.
+      def data
+        stream.pos = header.sh_offset
+        stream.read(header.sh_size)
+      end
+
+      # Is this a null section?
+      # @return [Boolean] No it's not.
+      def null?
+        false
+      end
+    end
+  end
+end

data/lib/elftools/sections/sections.rb

@@ -0,0 +1,34 @@
+# Require this file to load all sections classes.
+
+require 'elftools/sections/section'
+
+require 'elftools/sections/dynamic_section'
+require 'elftools/sections/note_section'
+require 'elftools/sections/null_section'
+require 'elftools/sections/str_tab_section'
+require 'elftools/sections/sym_tab_section'
+
+module ELFTools
+  # Defines different types of sections in this module.
+  module Sections
+    # Class methods of {Sections::Section}.
+    class << Section
+      # Use different class according to +header.sh_type+.
+      # @param [ELFTools::ELF_Shdr] header Section header.
+      # @param [File] stream Streaming object.
+      # @return [ELFTools::Sections::Section]
+      #   Return object dependes on +header.sh_type+.
+      def create(header, stream, *args)
+        klass = case header.sh_type
+                when Constants::SHT_DYNAMIC then DynamicSection
+                when Constants::SHT_NULL then NullSection
+                when Constants::SHT_NOTE then NoteSection
+                when Constants::SHT_STRTAB then StrTabSection
+                when Constants::SHT_SYMTAB, Constants::SHT_DYNSYM then SymTabSection
+                else Section
+                end
+        klass.new(header, stream, *args)
+      end
+    end
+  end
+end

data/lib/elftools/sections/str_tab_section.rb

@@ -0,0 +1,27 @@
+require 'elftools/sections/section'
+
+module ELFTools
+  module Sections
+    # Class of string table section.
+    # Usually for section .strtab and .dynstr,
+    # which record names.
+    class StrTabSection < Section
+      # Return the section or symbol name.
+      # @param [Integer] offset
+      #   Usually from +shdr.sh_name+ or +sym.st_name+.
+      # @return [String] The name without null bytes.
+      def name_at(offset)
+        stream.pos = header.sh_offset + offset
+        # read until "\x00"
+        ret = ''
+        loop do
+          c = stream.read(1)
+          return nil if c.nil? # reach EOF
+          break if c == "\x00"
+          ret += c
+        end
+        ret
+      end
+    end
+  end
+end