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; };
31 BEGIN { Wuse 'project::captive::doc::Macros'; }
32 project::captive::doc::Macros->init(
33 "title"=>'Captive NTFS Developer Documentation: Reverse Engineering',
34 "rel_prev"=>'Components.pm',
35 "rel_next"=>'CacheManager.pm',
42 <h1 id="reverse">Reverse Engineering</h1>
44 <p>This project has no intentions to reverse engineer and document the
45 filesystem data structures themselves since they are being encapsulated by
46 the filesystem driver. For these reasons the resources available in
47 projects such as $LinuxNTFS get out of any possible use. This project goal
48 is to provide fully compatible API interface to the rest of the W32 system
49 to persuade the filesystem driver it is running in the native
50 <span class="productname">Microsoft Windows XP</span> environment.</p>
52 <p>All the W32 filesystem drivers are running in the W32 kernel address
53 space and this area of W32 API is not much documented by
54 <span class="productname">Microsoft</span>. Some API functions are not
55 documented at all and the others are documented insufficiently for a their
56 possibly needed reimplementation from scratch. Documentation being
57 consulted primarily consists of
58 <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>
59 documentation and also various other 3rd party documentation resources such as
60 <span class="productname">@{[ a_href 'http://www.osr.com/ntinsider/1996/cacheman.htm',
61 'The NT Cache Manager Description' ]}</span>,
62 <span class="productname">@{[ a_href 'http://www.winntmag.com/Articles/Print.cfm?ArticleID=3864',
63 'Learn About NT'."'".'s File-system Cache' ]}</span>,
64 <span class="productname">@{[ a_href 'http://www.ntfsd.org/archive/',
65 'NT File System Developers mailing list archives' ]}</span>
67 @{[ a_href 'http://www.google.com/search?q=site%3Amicrosoft.com','fulltext searches' ]}
68 through Internet from case to case.</p>
70 <p>Sometimes no sufficient documentation was found and some code behaviour
71 had to be reverse engineered directly from the binaries of
72 <span class="fname">ntoskrnl.exe</span>,
73 <span class="fname">cdfs.sys</span>,
74 <span class="fname">fastfat.sys</span>
76 <span class="fname">ntfs.sys</span>.
77 Up to now the code was disassembled by
78 <span class="productname">@{[ a_href 'http://www.simtel.net/pub/pd/29498.html','IDA Freeware' ]}</span>
80 <span class="productname">dumpbin.exe</span> of
81 <span class="productname">Microsoft Visual Studio</span>.
82 <span class="productname">dumpbin.exe</span> is fortunately able to
83 interpret debug symbols from W32 <span class="fname">.PDB</span>
84 (Program DataBase) debug information files.</p>
86 <h2 id="dumpbin"><span class="productname">dumpbin.exe</span></h2>
88 <p>You should use the following options for
89 <span class="productname">dumpbin.exe</span>:</p>
91 <blockquote class="command">
92 <p>dumpbin.exe /all /rawdata:none /disasm /pdbpath:verbose FILENAME.SYS</p>
95 <p>You should see the following line in the output:</p>
97 <blockquote class="command">
98 <p>PDB file found at '.\\FILENAME.pdb'</p>
101 <h2 id="WinDbg"><span class="productname">WinDbg</span> Windows NT kernel debugging</h2>
103 <p><span class="productname">WinDbg</span> is downloadable from:
104 @{[ a_href 'http://www.microsoft.com/whdc/ddk/debugging/installx86.mspx' ]}</p>
106 <p>This is (the only?) tool able to debug filesystem drivers incl.
107 <span class="fname">ntfs.sys</span>. You will need two computers running
108 <span class="productname">Microsoft Windows</span> — one computer will run
109 <span class="productname">WinDbg</span> while the other one will be
110 frozen in remote Windows NT kernel debug mode. It does not matter which
111 <span class="productname">Microsoft Windows</span> version will be run
112 on the <span class="productname">WinDbg</span> side. Your goal is to
113 successfuly connect <span class="productname">WinDbg</span>:</p>
115 @{[ doc_img 'ntdebug-ntfs.png','<span class="productname">WinDbg</span> Remote NT Kernel NTFS Debugging' ]}
117 <p>The most easy way to setup two computers is to use commercial
118 <span class="productname">@{[ a_href 'http://www.vmware.com/download/workstation.html','VMware Workstation' ]}</span>
119 where you can run two virtual machines simultaneously on single PC
120 hardware and you can connect them by a virtual serial port provided by
121 <span class="productname">VMware</span>.</p>
123 <h3 id="WinDbg_WinDbg"><span class="productname">WinDbg</span> side setup</h3>
125 @{[ doc_img 'ntdebug-vmware-windbg.png',
126 '<span class="productname">VMware</span> virtual serial port'
127 .' of <span class="productname">WinDbg</span> side' ]}
129 <p>You should setup <span class="productname">WinDbg</span> according
132 @{[ doc_img 'ntdebug-windbg-port.png','Port settings of <span class="productname">WinDbg</span>' ]}
133 @{[ doc_img 'ntdebug-windbg-sym.png','Symbols files location of <span class="productname">WinDbg</span>' ]}
135 <p><span class="constant">Symbols</span> should point to the directory where
136 reside files extracted from the symbol archive for your version of
137 <span class="productname">Microsoft Windows</span>. In the case of the
138 recommended <span class="productname">Microsoft Windows XP Service Pack 1 Checked Build</span>
140 @{[ a_href 'http://msdl.microsoft.com/download/symbols/packages/windowsxp/xpsp1sym_x86_chk.exe' ]}</p>
142 <blockquote class="command">
143 <p># Rename xpsp1sym_x86_chk.exe contents .pdb files for WinDbg<br />
144 @{[ 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>
147 <p>The resulting <span class="command">rename.bat</span> for
148 <span class="command">xpsp1sym_x86_chk.exe</span> can be found at:
149 @{[ a_href 'xpsp1sym_x86_chk-rename.bat.zip' ]}</p>
151 <p>The resulting directory should contain at least
152 <span class="command">sys\\ntfs.pdb</span>
154 <span class="command">exe\\ntoskrnl.pdb</span>.</p>
156 <p>Your successfuly connected target (after the steps described
157 below) should look like:</p>
159 @{[ doc_img 'ntdebug-windbg-boot.png','Successfuly connected <span class="productname">WinDbg</span>' ]}
161 <h3 id="WinDbg_kern">Setup of the side being kernel-debugged</h3>
163 @{[ doc_img 'ntdebug-vmware-xpdebug.png',
164 '<span class="productname">VMware</span> virtual serial port'
165 .' of the side being kernel-debugged' ]}
167 <p>You must use the following options in your
168 <span class="command">c:\\boot.init</span> command-line:</p>
170 <blockquote class="command">
171 <p>/debug /debugport=COM1 /baudrate=115200</p>
174 <p>After booting this <span class="command">boot.ini</span>-entry
175 should freeze at this point
176 (if no <span class="productname">WinDbg</span> is waiting in the other
177 virtual machine):</p>
179 @{[ doc_img 'ntdebug-wait.png','Side being kernel-debugged waiting for <span class="productname">WinDbg</span>' ]}