dstruct 0.0.1

data/lib/rex/ole.rb

@@ -0,0 +1,202 @@
+# -*- coding: binary -*-
+
+##
+# Rex::OLE - an OLE implementation
+# written in 2010 by Joshua J. Drake <jduck [at] metasploit.com>
+#
+# License: MSF_LICENSE
+#
+#
+# This module implements Object-Linking-and-Embedding otherwise known as
+# Compound File Binary File Format or Windows Compound Binary File Format.
+# OLE is the container format for modern Excel, Word, PowerPoint, and many
+# other file formats.
+#
+# NOTE: This implementation is almost fully compliant with [MS-CFB] v1.1
+#
+#
+# SUPPORTS:
+#
+#  1. R/W v3 OLE files (v4 may work, but wasn't tested)
+#  2. RO double-indirect fat sectors
+#  3. RO fat sectors (including those in double-indirect parts)
+#  4. WO support for less than 109 fat sectors :)
+#  5. R/W minifat sectors
+#  6. R/W ministream
+#  7. R/W normal streams
+#  8. R/W substorages (including nesting)
+#  9. full directory support (hierarchal and flattened access)
+# 10. big and little endian files (although only little endian was tested)
+# 11. PropertySet streams (except .to_s)
+#
+#
+# TODO (in order of priority):
+#
+#  1. support deleting storages/streams
+#  2. create copyto and other typical interface functions
+#  3. support writing DIF sectors > 109
+#     - may lead to allocating more fat sectors :-/
+#  4. properly support mode params for open_stream/open_storage/etc
+#  5. optimize to prevent unecessary loading/writing
+#  6. support non-committal editing (open, change, close w/o save)
+#  7. support timestamps
+#  8. provide interface to change paramters (endian, etc)
+#
+#
+# TO INVESTIGATE:
+#
+#  1. moving storage interface functions into something used by both
+#     the main storage and substorages (unifying the code) (mixin?)
+#  2. eliminating flattening the directory prior to writing it out
+#
+##
+
+require 'rex'
+
+module Rex
+module OLE
+
+# misc util
+# NOTE: the v1.1 spec says that everything "MUST be stored in little-endian byte order"
+BIG_ENDIAN     = 0xfeff
+LITTLE_ENDIAN  = 0xfffe
+# defines Util class
+require 'rex/ole/util'
+require 'rex/ole/clsid'
+
+
+# constants for dealing with the header
+HDR_SZ  = 512
+# signatures
+SIG       = "\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"
+SIG_BETA  = "\x0e\x11\xfc\x0d\xd0\xcf\x11\xe0"
+# defines Header class
+require 'rex/ole/header'
+
+
+# sector types
+SECT_MAX   = 0xfffffffa
+SECT_DIF   = 0xfffffffc
+SECT_FAT   = 0xfffffffd
+SECT_END   = 0xfffffffe
+SECT_FREE  = 0xffffffff
+# defines DIFAT class
+require 'rex/ole/difat'
+# defines FAT class
+require 'rex/ole/fat'
+# defines MiniFAT class
+require 'rex/ole/minifat'
+
+
+# directory entries
+DIRENTRY_SZ      = 128
+DIR_NOSTREAM     = 0xffffffff
+DIR_MAXREGSID    = 0xfffffffa
+# defines Directory class
+require 'rex/ole/directory'
+
+# types
+STGTY_INVALID    = 0
+STGTY_STORAGE    = 1
+STGTY_STREAM     = 2
+STGTY_LOCKBYTES  = 3
+STGTY_PROPERTY   = 4
+STGTY_ROOT       = 5
+# for red/black tree
+COLOR_RED   = 0
+COLOR_BLACK = 1
+# defines DirEntry base class
+require 'rex/ole/direntry'
+
+
+# constants for storages
+STGM_READ       = 0
+STGM_WRITE      = 1
+STGM_READWRITE  = 2
+# defines Storage class
+require 'rex/ole/storage'
+# defines SubStorage class
+require 'rex/ole/substorage'
+# defines Stream class
+require 'rex/ole/stream'
+
+
+# constants for property sets
+# PropertyIds
+PID_DICTIONARY  = 0x00000000
+PID_CODEPAGE    = 0x00000001
+PID_LOCALE      = 0x80000000
+PID_BEHAVIOR    = 0x80000003
+# Well-known PropertyIds
+PIDSI_TITLE        = 0x02
+PIDSI_SUBJECT      = 0x03
+PIDSI_AUTHOR       = 0x04
+PIDSI_KEYWORDS     = 0x05
+PIDSI_COMMENTS     = 0x06
+PIDSI_TEMPLATE     = 0x07
+PIDSI_LASTAUTHOR   = 0x08
+PIDSI_REVNUMBER    = 0x09
+PIDSI_EDITTIME     = 0x0a
+PIDSI_LASTPRINTED  = 0x0b
+PIDSI_CREATE_DTM   = 0x0c
+PIDSI_LASTSAVE_DTM = 0x0d
+PIDSI_PAGECOUNT    = 0x0e
+PIDSI_WORDCOUNT    = 0x0f
+PIDSI_CHARCOUNT    = 0x10
+PIDSI_THUMBNAIL    = 0x11
+PIDSI_APPNAME      = 0x12
+PIDSI_DOC_SECURITY = 0x13
+# PropertyTypes
+VT_EMPTY        = 0x00
+VT_NULL         = 0x01
+VT_I2           = 0x02
+VT_I4           = 0x03
+VT_R4           = 0x04
+VT_R8           = 0x05
+VT_CY           = 0x06
+VT_DATE         = 0x07
+VT_BSTR         = 0x08
+VT_ERROR        = 0x0a
+VT_BOOL         = 0x0b
+VT_VARIANT      = 0x0c # used with VT_VECTOR
+# 0xd
+VT_DECIMAL      = 0x0e
+# 0xf
+VT_I1           = 0x10
+VT_UI1          = 0x11
+VT_UI2          = 0x12
+VT_UI4          = 0x13
+VT_I8           = 0x14
+VT_UI8          = 0x15
+VT_INT          = 0x16
+VT_UINT         = 0x17
+VT_LPSTR        = 0x1e
+VT_LPWSTR       = 0x1f
+# 0x20-0x3f
+VT_FILETIME     = 0x40
+VT_BLOB         = 0x41
+VT_STREAM       = 0x42
+VT_STORAGE      = 0x43
+VT_STREAMED_OBJ = 0x44
+VT_STORED_OBJ   = 0x45
+VT_BLOB_OBJ     = 0x46
+VT_CF           = 0x47 # Clipboard Format
+VT_CLSID        = 0x48
+VT_VERSIONED_STREAM = 0x49
+# Flags
+VT_VECTOR       = 0x1000
+VT_ARRAY        = 0x2000 # Requires OLE version >= 1
+# Format IDs
+FMTID_SummaryInformation    = "\xe0\x85\x9f\xf2\xf9\x4f\x68\x10\xab\x91\x08\x00\x2b\x27\xb3\xd9"
+FMTID_DocSummaryInformation = "\x02\xd5\xcd\xd5\x9c\x2e\x1b\x10\x93\x97\x08\x00\x2b\x2c\xf9\xae"
+FMTID_UserDefinedProperties = "\x05\xd5\xcd\xd5\x9c\x2e\x1b\x10\x93\x97\x08\x00\x2b\x2c\xf9\xae"
+FMTID_GlobalInfo            = "\x00\x6f\x61\x56\x54\xc1\xce\x11\x85\x53\x00\xaa\x00\xa1\xf9\x5b"
+FMTID_ImageContents         = "\x00\x64\x61\x56\x54\xc1\xce\x11\x85\x53\x00\xaa\x00\xa1\xf9\x5b"
+FMTID_ImageInfo             = "\x00\x65\x61\x56\x54\xc1\xce\x11\x85\x53\x00\xaa\x00\xa1\xf9\x5b"
+FMTID_PropertyBag           = "\x01\x18\x00\x20\xe6\x5d\xd1\x11\x8e\x38\x00\xc0\x4f\xb9\x38\x6d"
+# defines PropertySet class
+require 'rex/ole/propset'
+
+
+end
+end

data/lib/rex/ole/clsid.rb

@@ -0,0 +1,44 @@
+# -*- coding: binary -*-
+
+##
+# Rex::OLE - an OLE implementation
+# written in 2010 by Joshua J. Drake <jduck [at] metasploit.com>
+##
+
+
+module Rex
+module OLE
+
+class CLSID
+
+  def initialize(buf=nil)
+    @buf = buf
+    @buf ||= "\x00" * 16
+  end
+
+  def pack
+    @buf
+  end
+
+  def to_s
+    ret = ""
+    ret << "%08x" % Util.get32(@buf, 0)
+    ret << "-"
+    ret << "%04x" % Util.get16(@buf, 4)
+    ret << "-"
+    ret << "%04x" % Util.get16(@buf, 6)
+    ret << "-"
+    idx = 0
+    last8 = @buf[8,8]
+    last8.unpack('C*').each { |byte|
+      ret << [byte].pack('C').unpack('H*')[0]
+      ret << "-" if (idx == 1)
+      idx += 1
+    }
+    ret
+  end
+
+end
+
+end
+end

data/lib/rex/ole/difat.rb

@@ -0,0 +1,138 @@
+# -*- coding: binary -*-
+
+##
+# Rex::OLE - an OLE implementation
+# written in 2010 by Joshua J. Drake <jduck [at] metasploit.com>
+##
+
+module Rex
+module OLE
+
+class DIFAT
+
+  def initialize stg
+    @stg = stg
+    @entries = []
+  end
+
+  #
+  # convenience access to entries
+  #
+  def []=(idx,expr)
+    @entries[idx] = expr
+  end
+
+  def [](idx)
+    @entries[idx]
+  end
+
+  def +(expr)
+    @entries += expr
+    self
+  end
+
+  def <<(expr)
+    @entries << expr
+  end
+
+  def length
+    @entries.length
+  end
+
+  def slice!(start,stop)
+    @entries.slice!(start,stop)
+  end
+
+  def reset
+    @entries = []
+  end
+
+  def each
+    @entries.each { |el|
+      yield el
+    }
+  end
+
+  #
+  # woop
+  #
+  def to_s
+    ret = "{ "
+    @entries.each { |el|
+      ret << ", " if (ret.length > 2)
+      case el
+      when SECT_END
+        ret << "END"
+      when SECT_DIF
+        ret << "DIF"
+      when SECT_FAT
+        ret << "FAT"
+      when SECT_FREE
+        ret << "FREE"
+      else
+        ret << "0x%x" % el
+      end
+    }
+    ret << " }"
+    ret
+  end
+
+  #
+  # low-level functions
+  #
+  def read
+    @entries = []
+
+    # start with the header part
+    @entries += @stg.header._sectFat
+
+    # double indirect fat
+    sect = @stg.header._sectDifStart
+    while (sect != SECT_END)
+      if (@entries.include?(sect))
+        raise RuntimeError, 'Sector chain loop detected (0x%08x)' % sect
+      end
+
+      @entries << sect
+      buf = @stg.read_sector(sect, @stg.header.sector_size)
+
+      # the last sect ptr in the block becomes the next entry
+      sect = Util.get32(buf, ((@stg.header.idx_per_sect)-1) * 4)
+    end
+
+    # don't need these free ones, but it doesn't hurt to keep them.
+    #@difat.delete(SECT_FREE)
+  end
+
+  def write
+    len = @entries.length
+    first109 = @entries.dup
+
+    rest = nil
+    if (len > 109)
+      rest = first109.slice!(109,len)
+    end
+
+    @stg.header._sectFat = []
+    @stg.header._sectFat += first109
+    if (len < 109)
+      need = 109 - len
+      need.times {
+        @stg.header._sectFat << SECT_FREE
+      }
+    end
+
+    if (rest and rest.length > 0)
+      raise RuntimeError, 'TODO: support writing DIF properly!'
+      # may require adding more fat sectors :-/
+      #@stg.header._csectDif = rest.length
+      #@stg.header._sectDifStart = idx
+    end
+
+    @stg.header._csectFat = len
+  end
+
+end
+
+end
+end

data/lib/rex/ole/directory.rb

@@ -0,0 +1,228 @@
+# -*- coding: binary -*-
+
+##
+# Rex::OLE - an OLE implementation
+# written in 2010 by Joshua J. Drake <jduck [at] metasploit.com>
+##
+
+module Rex
+module OLE
+
+require 'rex/ole/direntry'
+
+#
+# This class serves as the root directory entry in addition to
+# an abstraction around the concept of a directory as a whole.
+#
+class Directory < DirEntry
+
+  # XXX: num_entries is not maintained once a stream/storage is added!
+  attr_accessor :num_entries
+
+  def initialize(stg)
+    super
+
+    @num_entries = 1
+  end
+
+
+  # woop, recursive each
+  def yield_entries(de, &block)
+    block.call(de)
+    de.each { |el|
+      yield_entries(el, &block)
+    }
+  end
+  def each_entry(&block)
+    yield_entries(self, &block)
+  end
+
+
+  def set_ministream_params(start, size)
+    @_sectStart = start
+    @_ulSize = size
+  end
+
+  def link_item(parent, child)
+    # set sid, advance count
+    child.sid = @num_entries
+    @num_entries += 1
+
+    # link item to siblings and/or parent
+    if (parent._sidChild == DIR_NOSTREAM)
+      parent._sidChild = child.sid
+      dlog("Linking #{child.name} as THE child of #{parent.name} as sid #{child.sid}", 'rex', LEV_3)
+    else
+      sib = nil
+      parent.each { |el|
+        if (el._sidLeftSib == DIR_NOSTREAM)
+          sib = el
+          el._sidLeftSib = child.sid
+          dlog("Linking #{child.name} as the LEFT sibling of #{sib.name} as sid #{child.sid}", 'rex', LEV_3)
+          break
+        end
+        if (el._sidRightSib == DIR_NOSTREAM)
+          sib = el
+          el._sidRightSib = child.sid
+          dlog("Linking #{child.name} as the RIGHT sibling of #{sib.name} as sid #{child.sid}", 'rex', LEV_3)
+          break
+        end
+      }
+      if (not sib)
+        raise RuntimeError, 'Unable to find a sibling to link to in the directory'
+      end
+    end
+    parent << child
+  end
+
+
+  #
+  # low-level functions
+  #
+  def from_s(sid, buf)
+    super
+
+    if (@_sidRightSib != DIR_NOSTREAM)
+      raise RuntimeError, 'Root Entry is invalid! (has right sibling)'
+    end
+    if (@_sidLeftSib != DIR_NOSTREAM)
+      raise RuntimeError, 'Root Entry is invalid! (has left sibling)'
+    end
+  end
+
+  def read
+    @children = []
+    visited = []
+    entries = []
+    root_node = nil
+    sect = @stg.header._sectDirStart
+    while (sect != SECT_END)
+
+      if (visited.include?(sect))
+        raise RuntimeError, 'Sector chain loop detected (0x%08x)' % sect
+      end
+      visited << sect
+
+      sbuf = @stg.read_sector(sect, @stg.header.sector_size)
+      while (sbuf.length >= DIRENTRY_SZ)
+        debuf = sbuf.slice!(0, DIRENTRY_SZ)
+
+        type = Util.get8(debuf, 0x42)
+        case type
+        when STGTY_ROOT
+          if (entries.length != 0)
+            raise RuntimeError, 'Root Entry found, but not first encountered!'
+          end
+          if (root_node)
+            raise RuntimeError, 'Multiple root directory sectors detected (0x%08x)' % sect
+          end
+          de = self
+          root_node = de
+
+        when STGTY_STORAGE
+          de = SubStorage.new @stg
+
+        when STGTY_STREAM
+          de = Stream.new @stg
+
+        when STGTY_INVALID
+          # skip invalid entries
+          next
+
+        else
+          raise RuntimeError, 'Unsupported directory entry type (0x%02x)' % type
+        end
+
+        # read content
+        de.from_s(entries.length, debuf)
+        entries << de
+      end
+      sect = @stg.next_sector(sect)
+    end
+
+    @num_entries = entries.length
+
+    # sort out the tree structure, starting with the root
+    if (@_sidChild != DIR_NOSTREAM)
+      populate_children(entries, root_node, @_sidChild)
+    end
+  end
+
+
+  # recursively add entries to their proper parents :)
+  def populate_children(entries, parent, sid)
+    node = entries[sid]
+    dlog("populate_children(entries, \"#{parent.name}\", #{sid}) - node: #{node.name}", 'rex', LEV_3)
+    parent << node
+    if (node.type == STGTY_STORAGE) and (node._sidChild != DIR_NOSTREAM)
+      populate_children(entries, node, node._sidChild)
+    end
+    if (node._sidLeftSib != DIR_NOSTREAM)
+      populate_children(entries, parent, node._sidLeftSib)
+    end
+    if (node._sidRightSib != DIR_NOSTREAM)
+      populate_children(entries, parent, node._sidRightSib)
+    end
+  end
+
+  # NOTE: this may not be necessary if we were to use each_entry
+  def flatten_tree(entries, parent)
+    entries << parent
+    parent.each { |el|
+      flatten_tree(entries, el)
+    }
+  end
+
+
+  def write
+    # flatten the directory again
+    entries = []
+    flatten_tree(entries, self)
+    dlog("flattened tree has #{entries.length} entries...", 'rex', LEV_3)
+
+    # count directory sectors
+    ds_count = entries.length / 4
+    if ((entries.length % 4) > 0)
+      # one more sector to hold the rest
+      ds_count += 1
+    end
+
+    # put the root entry first
+    sbuf = self.pack
+
+    # add the rest
+    prev_sect = nil
+    dir_start = nil
+    entries.each { |de|
+      # we already got the root entry, no more!
+      next if (de.type == STGTY_ROOT)
+
+      dir = de.pack
+      dlog("writing dir entry #{de.name}", 'rex', LEV_3)
+      sbuf << dir
+
+      if (sbuf.length == @stg.header.sector_size)
+        # we have a full sector, add it!
+        sect = @stg.write_sector(sbuf, nil, prev_sect)
+        prev_sect = sect
+        dir_start ||= sect
+        # reset..
+        sbuf = ""
+      end
+    }
+
+    # still a partial sector left?
+    if (sbuf.length > 0)
+      # add it! (NOTE: it will get padded with nul bytes if its not sector sized)
+      sect = @stg.write_sector(sbuf, nil, prev_sect)
+      prev_sect = sect
+      dir_start ||= sect
+    end
+
+    @stg.header._sectDirStart = dir_start
+  end
+
+end
+
+end
+end