# $Id$
# Captive project doc Reverse Engineering page Perl template.
# Copyright (C) 2003-2005 Jan Kratochvil <project-www.jankratochvil.net@jankratochvil.net>
# 
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; exactly version 2 of June 1991 is required
# 
# This program 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 General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


package project::captive::doc::Reverse;
require 5.6.0;	# at least 'use warnings;' but we need some 5.6.0+ modules anyway
our $VERSION=do { my @r=(q$Revision$=~/\d+/g); sprintf "%d.".("%03d"x$#r),@r; };
our $CVS_ID=q$Id$;
use strict;
use warnings;

use My::Web;


sub handler
{
	BEGIN { Wuse 'project::captive::doc::Macros'; }
project::captive::doc::Macros->init(
		"title"=>'Captive NTFS Developer Documentation: Reverse Engineering',
		"rel_prev"=>'Components.pm',
		"rel_next"=>'CacheManager.pm',
		);


print <<"HERE";


<h1 id="reverse">Reverse Engineering</h1>

	<p>This project has no intentions to reverse engineer and document the
	filesystem data structures themselves since they are being encapsulated by
	the filesystem driver. For these reasons the resources available in
	projects such as $LinuxNTFS get out of any possible use. This project goal
	is to provide fully compatible API interface to the rest of the W32 system
	to persuade the filesystem driver it is running in the native
	<span class="productname">Microsoft Windows XP</span> environment.</p>

	<p>All the W32 filesystem drivers are running in the W32 kernel address
	space and this area of W32 API is not much documented by
	<span class="productname">Microsoft</span>. Some API functions are not
	documented at all and the others are documented insufficiently for a their
	possibly needed reimplementation from scratch. Documentation being
	consulted primarily consists of
	<span class="productname">@{[ a_href 'http://msdn.microsoft.com/library/default.asp?url=/library/en-us/kmarch/hh/kmarch/kmhdr_6enb.asp','MSDN (Microsoft Developer Network) Kernel-Mode Driver Architecture: Windows DDK' ]}</span>
	documentation and also various other 3rd party documentation resources such as
	<span class="productname">@{[ a_href 'http://www.osr.com/ntinsider/1996/cacheman.htm',
			'The NT Cache Manager Description' ]}</span>,
	<span class="productname">@{[ a_href 'http://www.winntmag.com/Articles/Print.cfm?ArticleID=3864',
			'Learn About NT'."'".'s&nbsp;File-system Cache' ]}</span>,
	<span class="productname">@{[ a_href 'http://www.ntfsd.org/archive/',
			'NT File System Developers mailing list archives' ]}</span>
	including various
	@{[ a_href 'http://www.google.com/search?q=site%3Amicrosoft.com','fulltext searches' ]}
	through Internet from case to case.</p>

	<p>Sometimes no sufficient documentation was found and some code behaviour
	had to be reverse engineered directly from the binaries of
	<span class="fname">ntoskrnl.exe</span>,
	<span class="fname">cdfs.sys</span>,
	<span class="fname">fastfat.sys</span>
	and primarily
	<span class="fname">ntfs.sys</span>.
	Up to now the code was disassembled by
	<span class="productname">@{[ a_href 'http://www.simtel.net/pub/pd/29498.html','IDA Freeware' ]}</span>
	and by
	<span class="productname">dumpbin.exe</span> of
	<span class="productname">Microsoft Visual Studio</span>.
	<span class="productname">dumpbin.exe</span> is fortunately able to
	interpret debug symbols from W32 <span class="fname">.PDB</span>
	(Program DataBase) debug information files.</p>

	<h2 id="dumpbin"><span class="productname">dumpbin.exe</span></h2>

		<p>You should use the following options for
		<span class="productname">dumpbin.exe</span>:</p>

		<blockquote class="command">
			<p>dumpbin.exe /all /rawdata:none /disasm /pdbpath:verbose FILENAME.SYS</p>
		</blockquote>

		<p>You should see the following line in the output:</p>

		<blockquote class="command">
			<p>PDB file found at '.\\FILENAME.pdb'</p>
		</blockquote>

	<h2 id="WinDbg"><span class="productname">WinDbg</span> Windows NT kernel debugging</h2>

		<p><span class="productname">WinDbg</span> is downloadable from:
		@{[ a_href 'http://www.microsoft.com/whdc/ddk/debugging/installx86.mspx' ]}</p>

		<p>This is (the only?) tool able to debug filesystem drivers incl.
		<span class="fname">ntfs.sys</span>. You will need two computers running
		<span class="productname">Microsoft Windows</span> &mdash; one computer will run
		<span class="productname">WinDbg</span> while the other one will be
		frozen in remote Windows NT kernel debug mode. It does not matter which
		<span class="productname">Microsoft Windows</span> version will be run
		on the <span class="productname">WinDbg</span> side. Your goal is to
		successfuly connect <span class="productname">WinDbg</span>:</p>

		@{[ doc_img 'ntdebug-ntfs.png','<span class="productname">WinDbg</span> Remote NT Kernel NTFS Debugging' ]}

		<p>The most easy way to setup two computers is to use commercial
		<span class="productname">@{[ a_href 'http://www.vmware.com/download/workstation.html','VMware Workstation' ]}</span>
		where you can run two virtual machines simultaneously on single PC
		hardware and you can connect them by a virtual serial port provided by
		<span class="productname">VMware</span>.</p>

		<h3 id="WinDbg_WinDbg"><span class="productname">WinDbg</span> side setup</h3>

			@{[ doc_img 'ntdebug-vmware-windbg.png',
					'<span class="productname">VMware</span> virtual serial port'
							.' of <span class="productname">WinDbg</span> side' ]}

			<p>You should setup <span class="productname">WinDbg</span> according
			to:</p>

			@{[ doc_img 'ntdebug-windbg-port.png','Port settings of <span class="productname">WinDbg</span>' ]}
			@{[ doc_img 'ntdebug-windbg-sym.png','Symbols files location of <span class="productname">WinDbg</span>' ]}

			<p><span class="constant">Symbols</span> should point to the directory where
			reside files extracted from the symbol archive for your version of
			<span class="productname">Microsoft Windows</span>. In the case of the
			recommended <span class="productname">Microsoft Windows XP Service Pack 1 Checked Build</span>
			you should use:
			@{[ a_href 'http://msdl.microsoft.com/download/symbols/packages/windowsxp/xpsp1sym_x86_chk.exe' ]}</p>

			<blockquote class="command">
				<p># Rename xpsp1sym_x86_chk.exe contents .pdb files for WinDbg<br />
				@{[ escapeHTML(q{for i in *.pdb*;do ext="`echo $i|sed 's/^.*\.pdb\.\(.*\)$/\1/'`";if [ "$i" = "$ext" ];then echo "BAD:$i";break;fi;base="`echo $i|sed 's/\(\.pdb\)\..*$/\1/'`";echo "md $ext";echo "move /-y $i $ext\\$base";done|sort -u|sed 's/$/'`echo -ne '\r'`'/g' >/tmp/rename.bat}) ]}</p>
			</blockquote>

			<p>The resulting <span class="command">rename.bat</span> for
			<span class="command">xpsp1sym_x86_chk.exe</span> can be found at:
			@{[ a_href 'xpsp1sym_x86_chk-rename.bat.zip' ]}</p>

			<p>The resulting directory should contain at least
			<span class="command">sys\\ntfs.pdb</span>
			and
			<span class="command">exe\\ntoskrnl.pdb</span>.</p>

			<p>Your successfuly connected target (after the steps described
			below) should look like:</p>

			@{[ doc_img 'ntdebug-windbg-boot.png','Successfuly connected <span class="productname">WinDbg</span>' ]}

		<h3 id="WinDbg_kern">Setup of the side being kernel-debugged</h3>

			@{[ doc_img 'ntdebug-vmware-xpdebug.png',
					'<span class="productname">VMware</span> virtual serial port'
							.' of the side being kernel-debugged' ]}

			<p>You must use the following options in your
			<span class="command">c:\\boot.init</span> command-line:</p>

			<blockquote class="command">
				<p>/debug /debugport=COM1 /baudrate=115200</p>
			</blockquote>

			<p>After booting this <span class="command">boot.ini</span>-entry
			should freeze at this point
			(if no <span class="productname">WinDbg</span> is waiting in the other
			virtual machine):</p>

			@{[ doc_img 'ntdebug-wait.png','Side being kernel-debugged waiting for <span class="productname">WinDbg</span>' ]}


HERE


exit;
}
1;