project/captive/doc/Reverse.pm

   1 # $Id$
   2 # Captive project doc Reverse Engineering page Perl template.
   3 # Copyright (C) 2003-2005 Jan Kratochvil <project-www.jankratochvil.net@jankratochvil.net>
   4 #
   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
   8 #
   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.
  13 #
  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
  17
  18
  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; };
  22 our $CVS_ID=q$Id$;
  23 use strict;
  24 use warnings;
  25
  26 use My::Web;
  27 require CGI;
  28
  29
  30 sub handler
  31 {
  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',
  37                 );
  38
  39
  40 print <<"HERE";
  41
  42
  43 <h1 id="reverse">Reverse Engineering</h1>
  44
  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>
  52
  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&nbsp;File-system Cache' ]}</span>,
  65         <span class="productname">@{[ a_href 'http://www.ntfsd.org/archive/',
  66                         'NT File System Developers mailing list archives' ]}</span>
  67         including various
  68         @{[ a_href 'http://www.google.com/search?q=site%3Amicrosoft.com','fulltext searches' ]}
  69         through Internet from case to case.</p>
  70
  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>
  76         and primarily
  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>
  80         and by
  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>
  86
  87         <h2 id="dumpbin"><span class="productname">dumpbin.exe</span></h2>
  88
  89                 <p>You should use the following options for
  90                 <span class="productname">dumpbin.exe</span>:</p>
  91
  92                 <blockquote class="command">
  93                         <p>dumpbin.exe /all /rawdata:none /disasm /pdbpath:verbose FILENAME.SYS</p>
  94                 </blockquote>
  95
  96                 <p>You should see the following line in the output:</p>
  97
  98                 <blockquote class="command">
  99                         <p>PDB file found at '.\\FILENAME.pdb'</p>
 100                 </blockquote>
 101
 102         <h2 id="WinDbg"><span class="productname">WinDbg</span> Windows NT kernel debugging</h2>
 103
 104                 <p><span class="productname">WinDbg</span> is downloadable from:
 105                 @{[ a_href 'http://www.microsoft.com/whdc/ddk/debugging/installx86.mspx' ]}</p>
 106
 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> &mdash; 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>
 115
 116                 @{[ doc_img 'ntdebug-ntfs','<span class="productname">WinDbg</span> Remote NT Kernel NTFS Debugging' ]}
 117
 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>
 123
 124                 <h3 id="WinDbg_WinDbg"><span class="productname">WinDbg</span> side setup</h3>
 125
 126                         @{[ doc_img 'ntdebug-vmware-windbg',
 127                                         '<span class="productname">VMware</span> virtual serial port'
 128                                                         .' of <span class="productname">WinDbg</span> side' ]}
 129
 130                         <p>You should setup <span class="productname">WinDbg</span> according
 131                         to:</p>
 132
 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>' ]}
 135
 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>
 140                         you should use:
 141                         @{[ a_href 'http://msdl.microsoft.com/download/symbols/packages/windowsxp/xpsp1sym_x86_chk.exe' ]}</p>
 142
 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>
 146                         </blockquote>
 147
 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>
 151
 152                         <p>The resulting directory should contain at least
 153                         <span class="command">sys\\ntfs.pdb</span>
 154                         and
 155                         <span class="command">exe\\ntoskrnl.pdb</span>.</p>
 156
 157                         <p>Your successfuly connected target (after the steps described
 158                         below) should look like:</p>
 159
 160                         @{[ doc_img 'ntdebug-windbg-boot','Successfuly connected <span class="productname">WinDbg</span>' ]}
 161
 162                 <h3 id="WinDbg_kern">Setup of the side being kernel-debugged</h3>
 163
 164                         @{[ doc_img 'ntdebug-vmware-xpdebug',
 165                                         '<span class="productname">VMware</span> virtual serial port'
 166                                                         .' of the side being kernel-debugged' ]}
 167
 168                         <p>You must use the following options in your
 169                         <span class="command">c:\\boot.init</span> command-line:</p>
 170
 171                         <blockquote class="command">
 172                                 <p>/debug /debugport=COM1 /baudrate=115200</p>
 173                         </blockquote>
 174
 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>
 179
 180                         @{[ doc_img 'ntdebug-wait','Side being kernel-debugged waiting for <span class="productname">WinDbg</span>' ]}
 181
 182
 183 HERE
 184
 185
 186 project::captive::doc::Macros->footer();
 187 }
 188 1;