2 # Captive project doc Reverse Engineering page Perl template.
3 # Copyright (C) 2003-2005 Jan Kratochvil <project-www.jankratochvil.net@jankratochvil.net>
5 # This program is free software; you can redistribute it and/or modify
6 # it under the terms of the GNU General Public License as published by
7 # the Free Software Foundation; exactly version 2 of June 1991 is required
9 # This program is distributed in the hope that it will be useful,
10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 # GNU General Public License for more details.
14 # You should have received a copy of the GNU General Public License
15 # along with this program; if not, write to the Free Software
16 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 package project::captive::doc::Reverse;
20 require 5.6.0; # at least 'use warnings;' but we need some 5.6.0+ modules anyway
21 our $VERSION=do { my @r=(q$Revision$=~/\d+/g); sprintf "%d.".("%03d"x$#r),@r; };
32 BEGIN { Wuse 'project::captive::doc::Macros'; }
33 project::captive::doc::Macros->init(
34 "title"=>'Captive NTFS Developer Documentation: Reverse Engineering',
35 "rel_prev"=>'Components.pm',
36 "rel_next"=>'CacheManager.pm',
43 <h1 id="reverse">Reverse Engineering</h1>
45 <p>This project has no intentions to reverse engineer and document the
46 filesystem data structures themselves since they are being encapsulated by
47 the filesystem driver. For these reasons the resources available in
48 projects such as $LinuxNTFS get out of any possible use. This project goal
49 is to provide fully compatible API interface to the rest of the W32 system
50 to persuade the filesystem driver it is running in the native
51 <span class="productname">Microsoft Windows XP</span> environment.</p>
53 <p>All the W32 filesystem drivers are running in the W32 kernel address
54 space and this area of W32 API is not much documented by
55 <span class="productname">Microsoft</span>. Some API functions are not
56 documented at all and the others are documented insufficiently for a their
57 possibly needed reimplementation from scratch. Documentation being
58 consulted primarily consists of
59 <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>
60 documentation and also various other 3rd party documentation resources such as
61 <span class="productname">@{[ a_href 'http://www.osr.com/ntinsider/1996/cacheman.htm',
62 'The NT Cache Manager Description' ]}</span>,
63 <span class="productname">@{[ a_href 'http://www.winntmag.com/Articles/Print.cfm?ArticleID=3864',
64 'Learn About NT'."'".'s File-system Cache' ]}</span>,
65 <span class="productname">@{[ a_href 'http://www.ntfsd.org/archive/',
66 'NT File System Developers mailing list archives' ]}</span>
68 @{[ a_href 'http://www.google.com/search?q=site%3Amicrosoft.com','fulltext searches' ]}
69 through Internet from case to case.</p>
71 <p>Sometimes no sufficient documentation was found and some code behaviour
72 had to be reverse engineered directly from the binaries of
73 <span class="fname">ntoskrnl.exe</span>,
74 <span class="fname">cdfs.sys</span>,
75 <span class="fname">fastfat.sys</span>
77 <span class="fname">ntfs.sys</span>.
78 Up to now the code was disassembled by
79 <span class="productname">@{[ a_href 'http://www.simtel.net/pub/pd/29498.html','IDA Freeware' ]}</span>
81 <span class="productname">dumpbin.exe</span> of
82 <span class="productname">Microsoft Visual Studio</span>.
83 <span class="productname">dumpbin.exe</span> is fortunately able to
84 interpret debug symbols from W32 <span class="fname">.PDB</span>
85 (Program DataBase) debug information files.</p>
87 <h2 id="dumpbin"><span class="productname">dumpbin.exe</span></h2>
89 <p>You should use the following options for
90 <span class="productname">dumpbin.exe</span>:</p>
92 <blockquote class="command">
93 <p>dumpbin.exe /all /rawdata:none /disasm /pdbpath:verbose FILENAME.SYS</p>
96 <p>You should see the following line in the output:</p>
98 <blockquote class="command">
99 <p>PDB file found at '.\\FILENAME.pdb'</p>
102 <h2 id="WinDbg"><span class="productname">WinDbg</span> Windows NT kernel debugging</h2>
104 <p><span class="productname">WinDbg</span> is downloadable from:
105 @{[ a_href 'http://www.microsoft.com/whdc/ddk/debugging/installx86.mspx' ]}</p>
107 <p>This is (the only?) tool able to debug filesystem drivers incl.
108 <span class="fname">ntfs.sys</span>. You will need two computers running
109 <span class="productname">Microsoft Windows</span> — one computer will run
110 <span class="productname">WinDbg</span> while the other one will be
111 frozen in remote Windows NT kernel debug mode. It does not matter which
112 <span class="productname">Microsoft Windows</span> version will be run
113 on the <span class="productname">WinDbg</span> side. Your goal is to
114 successfuly connect <span class="productname">WinDbg</span>:</p>
116 @{[ doc_img 'ntdebug-ntfs','<span class="productname">WinDbg</span> Remote NT Kernel NTFS Debugging' ]}
118 <p>The most easy way to setup two computers is to use commercial
119 <span class="productname">@{[ a_href 'http://www.vmware.com/download/workstation.html','VMware Workstation' ]}</span>
120 where you can run two virtual machines simultaneously on single PC
121 hardware and you can connect them by a virtual serial port provided by
122 <span class="productname">VMware</span>.</p>
124 <h3 id="WinDbg_WinDbg"><span class="productname">WinDbg</span> side setup</h3>
126 @{[ doc_img 'ntdebug-vmware-windbg',
127 '<span class="productname">VMware</span> virtual serial port'
128 .' of <span class="productname">WinDbg</span> side' ]}
130 <p>You should setup <span class="productname">WinDbg</span> according
133 @{[ doc_img 'ntdebug-windbg-port','Port settings of <span class="productname">WinDbg</span>' ]}
134 @{[ doc_img 'ntdebug-windbg-sym','Symbols files location of <span class="productname">WinDbg</span>' ]}
136 <p><span class="constant">Symbols</span> should point to the directory where
137 reside files extracted from the symbol archive for your version of
138 <span class="productname">Microsoft Windows</span>. In the case of the
139 recommended <span class="productname">Microsoft Windows XP Service Pack 1 Checked Build</span>
141 @{[ a_href 'http://msdl.microsoft.com/download/symbols/packages/windowsxp/xpsp1sym_x86_chk.exe' ]}</p>
143 <blockquote class="command">
144 <p># Rename xpsp1sym_x86_chk.exe contents .pdb files for WinDbg<br />
145 @{[ CGI::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>
148 <p>The resulting <span class="command">rename.bat</span> for
149 <span class="command">xpsp1sym_x86_chk.exe</span> can be found at:
150 @{[ a_href 'xpsp1sym_x86_chk-rename.bat.zip' ]}</p>
152 <p>The resulting directory should contain at least
153 <span class="command">sys\\ntfs.pdb</span>
155 <span class="command">exe\\ntoskrnl.pdb</span>.</p>
157 <p>Your successfuly connected target (after the steps described
158 below) should look like:</p>
160 @{[ doc_img 'ntdebug-windbg-boot','Successfuly connected <span class="productname">WinDbg</span>' ]}
162 <h3 id="WinDbg_kern">Setup of the side being kernel-debugged</h3>
164 @{[ doc_img 'ntdebug-vmware-xpdebug',
165 '<span class="productname">VMware</span> virtual serial port'
166 .' of the side being kernel-debugged' ]}
168 <p>You must use the following options in your
169 <span class="command">c:\\boot.init</span> command-line:</p>
171 <blockquote class="command">
172 <p>/debug /debugport=COM1 /baudrate=115200</p>
175 <p>After booting this <span class="command">boot.ini</span>-entry
176 should freeze at this point
177 (if no <span class="productname">WinDbg</span> is waiting in the other
178 virtual machine):</p>
180 @{[ doc_img 'ntdebug-wait','Side being kernel-debugged waiting for <span class="productname">WinDbg</span>' ]}
186 project::captive::doc::Macros->footer();