librex 0.0.1

data/lib/rex/ole.rb

@@ -0,0 +1,128 @@
+##
+# $Id: ole.rb 8457 2010-02-11 18:36:38Z jduck $
+# Version: $Revision: 8457 $
+##
+
+##
+# 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)
+#
+#
+# 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 for auxillary streams (DocumentSummaryInformation and SummaryInformation)
+#  7. support non-committal editing (open, change, close w/o save)
+#  8. support timestamps
+#  9. 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'
+
+
+end
+end

data/lib/rex/ole/clsid.rb

@@ -0,0 +1,47 @@
+##
+# $Id: clsid.rb 8457 2010-02-11 18:36:38Z jduck $
+# Version: $Revision: 8457 $
+##
+
+##
+# 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,141 @@
+##
+# $Id: difat.rb 8457 2010-02-11 18:36:38Z jduck $
+# Version: $Revision: 8457 $
+##
+
+##
+# 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,230 @@
+##
+# $Id: directory.rb 8457 2010-02-11 18:36:38Z jduck $
+# Version: $Revision: 8457 $
+##
+
+##
+# 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
+			}
+			raise RuntimeError, 'Unable to find a sibling to link to in the directory'
+		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