/---------------------------------------------------------------------------\ | | | SEXDOC.TXT the README for SEX.EXE SUPER-EXE-HEADER | | | | Alan Cobb's Super-Exe-Header V1.00 | | Copyright (c) 1988-91, Alan S. Cobb | | | | Alan Cobb & Associates | | 510 Shannon Way, Suite 2201 | | Redwood City, CA 94065 | | | | CIS/Internet: 73170.3543@CompuServe.COM | | Bix/MCI:AlanCobb, Tel:415-593-7158 | | | \---------------------------------------------------------------------------/ SUMMARY: -------- Super-Exe-Header ( SEX ) is a program that expands on some of the capabilities of Microsoft's EXEHDR.EXE utility. It allows you to find and decode all the exports and imports made by most OS/2 and Windows EXEs, DLLs and device drivers. This is often a prelude to deeper reverse engineering such as disassembly and runtime tracing analysis with a debugger. While it CURRENTLY ONLY _RUNS_ UNDER OS/2 (a Windows version is coming), it will _analyze_ Windows files in addition to OS/2 1.X EXEs and DLLs, since the format is almost identical. PAPER/BOOK AND PROGRAM OFFER: ----------------------------- SEX is part of my preliminary development of full disassemblers for both Windows and OS/2 ( WINDIS.EXE and OS2DIS.EXE (tm) ). For $40 ($35 + $5 shipping and handling) you will get the OS/2 version of SEX (and a free copy of the Windows version of SEX when it comes out). In addition you get a copy of my 90 page paper "Reverse Engineering Windows and OS/2 Software" which was delivered at Software Development Spring '91. See more below. PRINTING THIS README.TXT FILE: ------------------------------ Some of the lines in this file are longer than 80 characters. If you want to print it out, you should probably do it with compressed (>80 character) mode. WHERE ARE THE INTERESTING PARTS? -------------------------------- The SEX report you may find most interesting is the one generated with the "-sex" command. See the details below. TABLE OF CONTENTS: ------------------ Summary: Paper/Book and Program Offer: Printing This README.TXT File: Where are the Interesting Parts: Table of Contents: Why You Need SEX: Legal Warning: How SEX is Better Than EXEHDR: The Origins of SEX: About the Author (Consulting Available): Paper/Book and Program Offer: Steps in Using SEX: Summary of SEX Commands: Creating the Ordinal-To-Export-Function-Name Translation Database: Which Exported Functions Are Undocumented? Understanding the -undoc and -headers Switches: Detailed Discussion of Commands: -exp command: -imp command: -sex command: -dat command: rlib.exe: Known Problems / Caveats: Differences With My Paper Delivered At Software Development '91: Only runs on OS/2 Currently: Beta Level Product: Uses a Lot of Memory: Files SEX Doesn't Work On: You'll Still Need EXEHDR: Abstract Of Paper/Book: Table of Contents For Paper/Book: WHY YOU NEED SEX: ----------------- Suppose there is a function exported by Windows or OS/2 that you want to learn more about. One way to do this is to look at examples of how it is used by existing programs. SEX will help you find all the programs and DLLs that are using the function. It will also show you where, in a program, the calls are being made from. That is often a prelude to further reverse engineering such as disassembly or runtime tracing with a debugger. LEGAL WARNING: -------------- This SEX may not be entirely safe. If you are using SEX as the first step in a deeper reverse engineering effort, you should remember that reverse engineering of software is legally controversial. Examine your license argeement or other relevant contracts and speak with an attorney before doing any in-depth reverse engineering. HOW SEX IS BETTER THAN EXEHDR: ------------------------------ EXEHDR does NOT show exhaustively _all_ the imports and other relocations for a file. It only shows the first one in the "chain" for each segment. A segment could make 20 calls to a single import, but only the first in the chain of relocations will be shown. On the other hand, SEX shows them all, sorted by offset. It also creates a database for translating the cryptic numeric ordinals normally shown by EXEHDR into the full ASCII names for those exported points. For example, instead of just showing a far call to "DOSCALLS . 38", SEX will show it as "DOSCALLS . 38 : DOSREALLOCSEG". THE ORIGINS OF SEX: ------------------- This program is part of the preliminary work I have done on a full commercial disassembler for Windows and OS/2. The full product will be completed and published by me sometime in the future. ABOUT THE AUTHOR (CONSULTING AVAILABLE): ----------------------------------------- I, Alan Cobb, am a consultant and software developer specializing in Windows and OS/2. I have been involved in OS/2 PM and Windows consulting since 1987. I have been published in Microsoft Systems Journal and spoken at Windows and OS/2 conferences. I have a B.S. in Finance from U.C.Berkeley (Phi Beta Kappa) and an M.S. in Electronics Engineering from C.S.U.Sacramento. PAPER/BOOK AND PROGRAM OFFER: ----------------------------- Although this SEX is cheap, it is NEITHER FREE, NOR SHAREWARE, NOR IN THE PUBLIC DOMAIN. For the price of $40 ($35 plus $5 shipping and handling), I will send you a copy of the OS/2 version (you'll also get a free Windows version when it is ready) of SEX and a copy of my 90 page paper titled "Reverse Engineering Windows and OS/2 Software". I delivered this paper at Software Development 1991 in Santa Clara on February 14, 1991. It will probably be expanded eventually into a full length book. At the end of this readme file there is an abstract and abbreviated table of contents for the paper. It will give you more background to help you understand how and why to use SEX. If you're not satisfied with the paper and program, return them in 60 days for a full refund. You can get the full program and paper by sending a check for $40 to my address: Alan Cobb Alan Cobb & Associates 510 Shannon Way, Suite 2201 Redwood City, CA 94065 ************************************************************************* STEPS IN USING SEX: ------------------- This brief usage summary will get you started quickly. These commands are discussed in greater detail later in this file. 1) Copy SEX.ZIP onto your hard disk. It is about 170k in size. 2) Uncompress SEX.ZIP. You should end up with the following files: SEX.EXE 320k The main SEX program. RLIB.EXE 67k Reads import libraries (mainly for OS2.LIB). README.TXT 50k The documentation file you are reading now. 3) Although it is optional, you will probably want to build the ordinal-to-function-name translation database, EXPORTS.DAT. It only takes about 3 minutes on a 386/25. If you do build it, this database will be used to translate any module.ordinal pairs into full ASCII function names for the various reports. Do not be worried by the numerous messages scrolling up your screen during the -exp command, that is normal. 3.1) If you are just interested in looking at Windows files: SEX -exp -noapps \windows\*.* \windows\system\*.* > exports.dat At this point EXPORTS.DAT will be about 230k 3.2) If you are just interesting in looking at OS/2 files: SEX -exp -noapps \os2\*.* \os2\dll\*.* > exports.dat RLIB \pmsdk12\lib\os2.lib >> exports.dat At this point EXPORTS.DAT will be about 180k. The RLIB program reads the ordinals and function names from the DOSCALLS module entries in os2.lib. 3.3) If you are interesting in looking at both Windows and OS/2 files: SEX -exp -noapps \windows\*.* \windows\system\*.* > exports.dat SEX -exp -noapps \os2\*.* \os2\dll\*.* >> exports.dat RLIB \pmsdk12\lib\os2.lib >> exports.dat At this point EXPORTS.DAT will be about 410k. 4) Run the reports you are interested in: 4.1) List exports: List all exports of the Windows GDI Dynamic Link Library: Also check the Windows header files and mark those exports which appear to be documented there. SEX -exp -human \windows\system\gdi.exe -headers \windev\include\*.* List only the undocumented exports of the Windows Kernel: SEX -exp -human -undoc \windows\system\kernel.exe -headers \windev\include\*.* > report.txt Look at the resultant report.txt with any ASCII editor. 4.2) List imports: List all imports to a Windows application: SEX -imp \mywin\winapp.exe -headers \windev\include\*.* List only the undocumented imports to a Windows application: SEX -imp -undoc \mywin\winapp.exe -headers \windev\include\*.* 4.3) List exhaustively all imports and, optionally, other relocations: List all imports, but no other relocations, made by a Windows application. SEX -sex winapp.exe > winapp.sex List all imports and relocations made by a Windows DLL: SEX -sex -allrel windll.exe > report.txt List all imports and relocations made by a Windows DLL, and mark the ones documented in include files. SEX -sex -allrel windll.exe -headers \windev\include\*.* 4.4) List out the contents of the ordinal-to-function-name translation database, EXPORTS.DAT: List all entries. Do NOT attempt to see which ones are documented. SEX -dat List all entries. DO check the header files and mark those exports which are apparently documented. SEX -dat -headers \windev\include\*.* ************************************************************************* SUMMARY OF SEX COMMANDS: ------------------------ Usage: SEX -command [-options] [filename(s)] [-headers filenames] Commands: Show list of exports for file(s): -exp [-human ] [-noapps] [-undoc] file(s) [-headers file(s)] Show list of imports for file: -imp [-undoc] file [-headers file(s)] Show a Super-Exe-Header report: -sex [-allrel] file [-headers file(s)] Show ordinal-to-func name database (exports.dat): -dat [-headers file(s)] Show this command summary: -? Options: -human : Output as an export report for human readers. -noapps : Do NOT read applications (non-DLLs) for exports. -allrel : Show all relocations, not just imports. -undoc : Show only undocumented imports or exports. -headers filename(s) : Search files, such as *.H or *.INC, for possible documentation of export or import names. Examples: SEX -exp -noapps \win3\system\*.* -headers \win\include\*.* >> exports.dat SEX -exp -human -undoc winapp.exe -headers \win\include\*.* SEX -exp winapp.exe SEX -imp os2serv.dll -headers \pmsdk12\include\*.h SEX -imp -undoc os2appl.exe -headers \pmsdk12\include\*.h SEX -sex win3prog.exe SEX -sex -allrel os2prog.exe -headers \pmsdk12\include\*.h SEX -dat -headers \windev\include\*.* ************************************************************************ CREATING THE ORDINAL-TO-EXPORT-FUNCTION-NAME TRANSLATION DATABASE: ------------------------------------------------------------------ SEX looks for a file called EXPORTS.DAT in the current directory when doing the -imp, -sex or -dat reports. EXPORTS.DAT is created with the -exp command and with RLIB.EXE. You can still run all of SEX's reports even if you have not built the EXPORTS.DAT database, but you will only be able to see imports expressed as MODULE . ORDINAL, rather than MODULE . ORDINAL : ASCII NAME. For example, without the database, USER.33 : GETCLIENTRECT, will be shown as the more cryptic USER.33. WHICH EXPORTED FUNCTIONS ARE UNDOCUMENTED? UNDERSTANDING THE -undoc AND -headers SWITCHES: -------------------------------------------------------------------- It is often interesting to know which functions exported by a DLL, or imported by an EXE file, are documented or undocumented. For example, the Windows GDI function CreateDC and most other functions of interest are documented in the Windows Programmer's Reference manual. But the more internal GDI function PixToLine is not. There are two switches used by SEX that relate to undocumented functions. They are -headers and -undoc. The -headers switch is followed by a list of header files to search, such as "\windev\include\*.*". SEX will read through all those files looking for ASCII strings. Many of these strings will indeed be function names declared in function prototypes, but also of course, there will be other strings which are just type names or parameter names. So this is only a rough test of undocumentedness. There are some exported functions which appear to be undocumented, but which in fact _are_ documented. For example, the export _WSPRINTF from USER.EXE is documented in windows.h, but without the leading underscore. The WNET... functions exported by USER.EXE are not documented in the SDK's include files, but they are in the DDK's include files. The import and export lines used in SEX's reports have a field with the label " '*' If apparently documented". This field is set to '*' if the -headers switch was specified, and if the import or export name can be found in the list of "name" strings read in from the header files. If the -headers switch was not specified, then this field will always be blank, since SEX must assume that none of the exports or imports are documented. The -undoc switch can be used with the -exp and -imp reports to cause SEX to only display export or import lines which appear to be undocumented. This is helpful if you want to enumerate how many undocumented imports are being made to a program, or how many undocumented exports are being made from a DLL. Currently the -undoc switch does not effect the -sex and -dat reports. DETAILED DISCUSSION OF COMMANDS: -------------------------------- As shown in the summary above, SEX has four main commands: 1) -exp Shows a list of exports for given file(s). 2) -imp Shows a list of imports for a given file. 3) -sex Shows an exhaustive list of all imports and relocations for a given file. 4) -dat Shows the content of the ordinal-to-function-name translation database file used by SEX (exports.dat). 1) -exp COMMAND: ------------------ This command creates a list of exports for one or more, Windows or OS/2 files. By using wild cards in the specified filenames it can examine multiple files in multiple directories. It has two purposes. 1) To create a machine readable ordinal-to-function- name translation database, and 2) to display a more human readable version of that database. 1.1) The default behavior of the -exp command is to create a MACHINE READABLE database (exports.dat) for translating MODULE.ORDINAL pairs into their equivalent exported ASCII function names. Use the -human switch described below to make reports more suitable for human reading. For example, the following -exp command will fill the exports.dat database with Windows DLL and device driver exports: sex -exp -noapps \windows\*.* \windows\system\*.* > exports.dat Do not be worried by the numerous messages scrolling up your screen during the -exp command, that is normal. Here is what the resultant machine readable output file, exports.dat looks like. This is only a few small sections of the complete file. RECORDER 1 JRHOOK DLL/Driver \win3\RECORDER.DLL RECORDER 2 STARTRECORD DLL/Driver \win3\RECORDER.DLL RECORDER 3 STOPRECORD DLL/Driver \win3\RECORDER.DLL RECORDER 4 STARTPLAYBACK DLL/Driver \win3\RECORDER.DLL RECORDER 5 STOPPLAYBACK DLL/Driver \win3\RECORDER.DLL RECORDER 6 JPHOOK DLL/Driver \win3\RECORDER.DLL RECORDER 7 KHOOK DLL/Driver \win3\RECORDER.DLL (... some detail removed... ) GRABBER 1 PAINTSCREEN DLL/Driver \win3\system\EGA.GR3 GRABBER 2 SCREENFREE DLL/Driver \win3\system\EGA.GR3 GRABBER 3 BEGINSELECTION DLL/Driver \win3\system\EGA.GR3 GRABBER 4 KEYSELECTION DLL/Driver \win3\system\EGA.GR3 GRABBER 5 MAKESELCTRECT DLL/Driver \win3\system\EGA.GR3 (... some detail removed... ) GDI 1 SETBKCOLOR DLL/Driver \win3\system\GDIN.EXE GDI 2 SETBKMODE DLL/Driver \win3\system\GDIN.EXE GDI 3 SETMAPMODE DLL/Driver \win3\system\GDIN.EXE GDI 4 SETROP2 DLL/Driver \win3\system\GDIN.EXE GDI 5 SETRELABS DLL/Driver \win3\system\GDIN.EXE GDI 6 SETPOLYFILLMODE DLL/Driver \win3\system\GDIN.EXE (... some detail removed... ) KERNEL 1 FATALEXIT DLL/Driver \win3\system\KERNEL.EXE KERNEL 2 EXITKERNEL DLL/Driver \win3\system\KERNEL.EXE KERNEL 3 GETVERSION DLL/Driver \win3\system\KERNEL.EXE KERNEL 4 LOCALINIT DLL/Driver \win3\system\KERNEL.EXE KERNEL 5 LOCALALLOC DLL/Driver \win3\system\KERNEL.EXE KERNEL 6 LOCALREALLOC DLL/Driver \win3\system\KERNEL.EXE KERNEL 7 LOCALFREE DLL/Driver \win3\system\KERNEL.EXE Related switch options: 1.1.1) -noapps : When this switch is specified, SEX will not examine and list the exports of any applications in the list of filenames specified. This is useful when you specify a pathname with wild cards such as "\windows\system\*.*", when building the ordinal-to-function- name translation database. Normally, you want a list of all the exports from the dynamic link libraries in \windows\system (like KERNEL.EXE), but not from any applications there. The reason is, of course, that no other application can import the exports of another application, it can only import the exports of dynamic link libraries. If you want to also look at exports from applications you should use the -human switch below. You can also manually delete, add or modify entries directly in the exports.dat file with any ASCII editor. 1.2) To create HUMAN READABLE reports of the same type use the -human switch. Below is the report displayed for this command: sex -exp -human \win3\system\user.exe +----------------------------------------------------------------------------+ | List of all exports from file: | +----------------------------------------------------------------------------+ | File name: [ \win3\system\user.exe ] | | DLL or Application? [ DLL/Driver ] | | | | +-- Module Name | | | +-- Export Ordinal | | | | +-- '*' If apparently documented | | | | | +-------------- Export Name | |-v------------v-v-v---------------------------------------------------------| USER . 1 MESSAGEBOX USER . 2 OLDEXITWINDOWS USER . 3 ENABLEOEMLAYER USER . 4 DISABLEOEMLAYER USER . 5 INITAPP USER . 6 POSTQUITMESSAGE USER . 7 EXITWINDOWS USER . 10 SETTIMER USER . 11 SETSYSTEMTIMER USER . 12 KILLTIMER USER . 13 GETTICKCOUNT USER . 14 GETTIMERRESOLUTION (... rest of report cut off... ) The command below adds the -headers switch and produces the report that follows. Notice the added '*' flags. sex -exp -human \win3\system\user.exe -headers \windev\include\*.* +----------------------------------------------------------------------------+ | List of all exports from file: | +----------------------------------------------------------------------------+ | File name: [ \win3\system\user.exe ] | | DLL or Application? [ DLL/Driver ] | | | | +-- Module Name | | | +-- Export Ordinal | | | | +-- '*' If apparently documented | | | | | +-------------- Export Name | |-v------------v-v-v---------------------------------------------------------| USER . 1 * MESSAGEBOX USER . 2 OLDEXITWINDOWS USER . 3 ENABLEOEMLAYER USER . 4 DISABLEOEMLAYER USER . 5 INITAPP USER . 6 * POSTQUITMESSAGE USER . 7 * EXITWINDOWS USER . 10 * SETTIMER USER . 11 SETSYSTEMTIMER USER . 12 * KILLTIMER USER . 13 * GETTICKCOUNT USER . 14 GETTIMERRESOLUTION (... rest of report cut off... ) Related switch options: 1.2.1) -noapps : See discussion above. 1.2.2) -undoc : You can use the -undoc switch if you only want to show the exports which are NOT documented in a given list of header include files. If you use the -undoc switch you should use the -headers switch at the same time. If you omit the -headers switch, SEX will think that all the exports are undocumented, and hence display them all. 2) -imp COMMAND: ------------------ This command will create a SUMMARY of imports for OS/2 or Windows, DLL or EXE files. This allows you to find which programs are importing functions you are interested in. The imports are sorted by module and ordinal, and include a count of total calls made to them. For example, the command below will create the report which is partially shown following it. Since the -headers switch was not specified, SEX thinks all the imports are undocumented. sex -imp \windev\samples\icon\icon.exe +----------------------------------------------------------------------------+ | List of all functions imported by: | |----------------------------------------------------------------------------| File name: [ \windev\samples\icon\icon.exe ] |----------------------------------------------------------------------------| | Calls | Ordinal | Module |Ord.| +-- '*' If apparently documented | | | or Name | | | | +-- Name of imported function | |-------+---------+--------+----+-v-v----------------------------------------| 1 Imp.Ord.[ GDI . 87] GETSTOCKOBJECT 1 Imp.Ord.[ KERNEL . 1] FATALEXIT 1 Imp.Ord.[ KERNEL . 5] LOCALALLOC 1 Imp.Ord.[ KERNEL . 6] LOCALREALLOC 1 Imp.Ord.[ KERNEL . 7] LOCALFREE 1 Imp.Ord.[ KERNEL . 15] GLOBALALLOC 1 Imp.Ord.[ KERNEL . 16] GLOBALREALLOC 1 Imp.Ord.[ KERNEL . 17] GLOBALFREE 2 Imp.Ord.[ KERNEL . 23] LOCKSEGMENT (... rest of report cut off... ) The command below adds the -undoc and -headers switches and produces the report that follows. sex -imp -undoc \windev\samples\icon\icon.exe -headers \windev\include\*.* +----------------------------------------------------------------------------+ | List of all functions imported by: | |----------------------------------------------------------------------------| File name: [ \windev\samples\icon\icon.exe ] |----------------------------------------------------------------------------| | Calls | Ordinal | Module |Ord.| +-- '*' If apparently documented | | | or Name | | | | +-- Name of imported function | |-------+---------+--------+----+-v-v----------------------------------------| 1 Imp.Ord.[ KERNEL . 30] WAITEVENT 1 Imp.Ord.[ KERNEL . 91] INITTASK 1 Imp.Ord.[ KERNEL . 137] FATALAPPEXIT 1 Imp.Ord.[ USER . 5] INITAPP Number of unique functions imported: [ 30 ] Total calls to these imports: [ 33 ] Related switch options: -noapps : See the discussion of the -exp command above. 3) -sex COMMAND: ------------------ This command will create an exhaustive list of _all_ calls to imports, and optionally all other relocatable internal references (relocations), for all segments of an OS/2 or Windows, EXE or DLL file, sorted by segment and offset. The absolute offset in the file for each relocation is shown at the left to allow you to find, and possibly disassemble with a debugger, the section of code making the call or other reference. In addition to the relocations, the -sex report also shows several other important addresses, each sorted into offset order amongst the relocations. These other addresses include the first and last bytes of each segment, all exports, the initial SS:SP (stack start) and initial CS:IP (entry point). For example, the following command will create the report below. sex -sex -allrel \windev\samples\showfont\showfont.exe -headers \windev\include\*.* +----------------------------------------------------------------------------+ | List of all segments, exports, imports [and other relocations] for file: | |----------------------------------------------------------------------------| File name: [ \windev\samples\showfont\showfont.exe ] |----------------------------------------------------------------------------| | File | Seg:Offet | Description | | Offset| | +-- '*' If apparently documented| |-------+-----------+------------------------v-------------------------------| *** Segment No. [ 0 ] *** Type:[ ZERO_SEG ] ************* 000000 000:0000 Segment start Segment length zero 000000 000:0000 Last byte in segment *** Segment No. [ 1 ] *** Type:[ CODE_SEG ] ************* 000800 001:0000 Segment start 000800 001:0000 Intern.Ref.Target ST:2:SEGMENT TT:0:INTRNRF Refs:12 000870 001:0070 Imp.Ord.[ USER . 41] CREATEWINDOW 000880 001:0080 Imp.Ord.[ USER . 42] SHOWWINDOW 000888 001:0088 Imp.Ord.[ USER . 124] UPDATEWINDOW 000894 001:0094 Imp.Ord.[ USER . 113] TRANSLATEMESSAGE (... some detail removed... ) 000932 001:0132 Intern.Ref.Source ST:5:OFFS16 Targ:001:0c9a TT:0:INTRNRF Refs:1 000937 001:0137 Intern.Ref.Source ST:2:SEGMENT Targ:001:0000 TT:0:INTRNRF Refs:1 00093c 001:013c Imp.Ord.[ USER . 57] REGISTERCLASS 000947 001:0147 Imp.Ord.[ KERNEL . 9] LOCALUNLOCK 00094f 001:014f Imp.Ord.[ KERNEL . 7] LOCALFREE 000965 001:0165 Imp.Ord.[ GDI . 2] SETBKMODE 000975 001:0175 Imp.Ord.[ GDI . 1] SETBKCOLOR (... some detail removed... ) 00111c 001:091c Export [ ShowFont . 6] ENUMFUNC 00111c 001:091c Intern.Ref.Target ST:5:OFFS16 TT:0:INTRNRF Refs:2 0011b8 001:09b8 Imp.Ord.[ USER . 66] GETDC 0011c0 001:09c0 Intern.Ref.Source ST:5:OFFS16 Targ:001:091c TT:0:INTRNRF Refs:1 0011c3 001:09c3 Intern.Ref.Source ST:2:SEGMENT Targ:001:0000 TT:0:INTRNRF Refs:1 (... some detail removed... ) 002bb1 001:23b1 Imp.Ord.[ USER . 96] CHECKRADIOBUTTON 002bce 001:23ce Imp.Ord.[ USER . 96] CHECKRADIOBUTTON 002c01 001:2401 Initial CS:IP (Entry Point) <**** 002c05 001:2405 Imp.Ord.[ KERNEL . 91] INITTASK (... some detail removed... ) *** Segment No. [ 2 ] *** Type:[ INITIALIZED_DATA_SEG_DGROUP ] ************* 004000 002:0000 Segment start 004000 002:0000 Initial SS:SP (Stack Start) <**** 005b63 002:1b63 Last byte in segment Related switch options: -allrel : When this switch is specified, the report will show all relocatable references made by the program, not just the imports. These non-import relocations are things like far calls between segments within the program, or inter-segment data access within the program. If the -allrel switch is not specified the report will only show the import relocations. -undoc : This switch is not supported for the -sex command. 4) -dat COMMAND: ---------------- This report gives you a way to verify that your EXPORTS.DAT ordinal-to-function-name translation database is being successfully read in, and that it contains no corrupted entries. EXPORTS.DAT is just an ASCII text file. Each line is either blank or has five ASCII fields separated by spaces. Below are two lines from the EXPORTS.DAT file shown previously. DISPLAY 1 BITBLT DLL/Driver \win3\system\CGA.DRV DISPLAY 2 COLORINFO DLL/Driver \win3\system\CGA.DRV You can manipulate EXPORTS.DAT directly with an ASCII editor. For example, you might want to manually add, change or delete some entries in it. The -dat report contains two more fields that do not appear directly in EXPORTS.DAT. These fields are shown in the report header below. The first added field is "Number of times defined". For most exports this will be 1, but for some it will be greater than 1. For example the video display device export, DISPLAY . 1 (BITBLT) was found in three separate driver files when the -exp command was used to create EXPORTS.DAT. Hence, it appears three times in EXPORTS.DAT, once from each of these files: \win3\system\CGA.DRV \win3\system\EGA.DRV \win3\system\VGA.DRV The second additional field is labeled " * if documented". This field is discussed in the topic "WHICH EXPORTED FUNCTIONS ARE UNDOCUMENTED?" earlier in this readme file. For example, the following command will create the report below. In this example the exports.dat database only contains Windows related exports, but it could simultaneously hold OS/2 exports as well. sex -dat -headers \windev\include\*.* +----------------------------------------------------------------------------+ | List of all entries in ordinal-to-function-name translation database | +----------------------------------------------------------------------------+ | +-- Number of times defined | | | +-- Module name +-- Application or DLL/Driver | | | | +-- Ordinal | +-- File of origin | | | | | +-- '*' If apparently documented | | | | | | | +-- Export name for this ordinal| | | | | | | | | | | |-v-v------------v-v-v-------------------------v-----v-----------------------| 1 ATM . 1 _DllInit DLL \win3\system\ATM.DLL 1 ATM . 2 * WEP DLL \win3\system\ATM.DLL 1 ATM . 3 ___ExportedStub DLL \win3\system\ATM.DLL 1 ATM . 100 ATMXYSHOWTEXT DLL \win3\system\ATM.DLL 1 ATM . 101 ATMGETOUTLINE DLL \win3\system\ATM.DLL (... some detail removed... ) 3 DISPLAY . 1 * BITBLT DLL \win3\system\CGA.DRV 3 DISPLAY . 2 COLORINFO DLL \win3\system\CGA.DRV 3 DISPLAY . 3 * CONTROL DLL \win3\system\CGA.DRV 3 DISPLAY . 4 DISABLE DLL \win3\system\CGA.DRV 3 DISPLAY . 5 * ENABLE DLL \win3\system\CGA.DRV 3 DISPLAY . 6 ENUMDFONTS DLL \win3\system\CGA.DRV (... some detail removed... ) 2 GDI . 1 * SETBKCOLOR DLL \win3\system\GDI.EXE 2 GDI . 2 * SETBKMODE DLL \win3\system\GDI.EXE 2 GDI . 3 * SETMAPMODE DLL \win3\system\GDI.EXE 2 GDI . 4 * SETROP2 DLL \win3\system\GDI.EXE 2 GDI . 5 SETRELABS DLL \win3\system\GDI.EXE 2 GDI . 6 * SETPOLYFILLMODE DLL \win3\system\GDI.EXE 2 GDI . 7 * SETSTRETCHBLTMODE DLL \win3\system\GDI.EXE 2 GDI . 8 * SETTEXTCHARACTEREXTRA DLL \win3\system\GDI.EXE (... some detail removed... ) 6 KERNEL . 163 * GLOBALLRUOLDEST DLL \win3\system\KERNEL.EXE 6 KERNEL . 164 * GLOBALLRUNEWEST DLL \win3\system\KERNEL.EXE 6 KERNEL . 165 A20PROC DLL \win3\system\KERNEL.EXE 6 KERNEL . 166 * WINEXEC DLL \win3\system\KERNEL.EXE 6 KERNEL . 167 GETEXPWINVER DLL \win3\system\KERNEL.EXE 6 KERNEL . 168 DIRECTRESALLOC DLL \win3\system\KERNEL.EXE 6 KERNEL . 169 * GETFREESPACE DLL \win3\system\KERNEL.EXE 6 KERNEL . 170 ALLOCCSTODSALIAS DLL \win3\system\KERNEL.EXE (... rest of report cut off... ) RLIB.EXE: --------- This separate program reads *.LIB files and displays any import library records it finds there. These can then be added to the ordinal-to-export-function-name translation database, exports.dat. You really only need this program to get the translation information for the DOSCALLS functions in the OS/2 kernel. Since there are no explicit exports from the OS/2 kernel that we can read with the -exp command, we have to use RLIB to get them instead, from os2.lib. Use RLIB.EXE like this: RLIB \pmsdk12\lib\os2.lib > os2lib.dat. Then append os2lib.dat to any other *.DAT files you have generated to make the overall database file exports.dat. The generated ASCII file os2lib.dat should end up being about 83K. Only about 15K of that 83K are the 208 DOSCALLS entry points that we are really interested in, such as those shown below. DOSCALLS 1 DOSICREATETHREAD DLL-from-LIB \pmsdk12\lib\os2.lib ... DOSCALLS 208 DOSFREERESOURCE DLL-from-LIB \pmsdk12\lib\os2.lib The rest are from modules like: KBDCALLS, VIOCALLS, PMWIN, PMGPI, HELPMGR. We will already be picking up explicit exports for these entry points by reading the corresponding DLLs directly with the -exp command. To save disk space you could chop these duplicate entries out. This would reduce the size of exports.dat by 83-15K = 68K. There may be other duplications that can be weeded out of your exports.dat with an editor, if disk space is tight. For example, the GDI functions will appear twice in exports.dat if you have both GDI.EXE and GDIN.EXE in \windows\system and have used \windows\system\*.* with the -exp command when building exports.dat. ********************************************************************** KNOWN PROBLEMS / CAVEATS: ------------------------- DIFFERENCES WITH MY PAPER DELIVERED AT SOFTWARE DEVELOPMENT '91: ---------------------------------------------------------------- My paper, whose abstract is shown below, used an older version of SEX whose reports used a field titled "undocumented", for exports and imports. Today that field has been changed to the inverse. That is, now it is set to '*' for "documented" exports and imports. ONLY RUNS ON OS/2 CURRENTLY: ---------------------------- These SEX tools should be of as much interest to Windows programmers as to OS/2 programmers. Unfortuately they only run under OS/2 at this time. I have written it using, and tested it with, OS/2 1.2. If you have problems running it, let me know. A Windows version is on my agenda. BETA LEVEL PRODUCT: ------------------- I've done a fair amount of testing to SEX, but you may find some bugs. Please let me know about them. Also tell me what you think of the product in general. USES A LOT OF MEMORY: --------------------- You'll need upwards of 1MB free memory in order to run the program. If you use wild cards to process multiple files or directories the memory requirements will increase. If you've got 2MB free memory you should be able to do just about anything. (I've got a 9MB system). This is memory hungry OOP technology folks! FILES SEX DOESN'T WORK ON: -------------------------- There are at least two types of files that SEX does not currently work on. Firstly, some Windows programs use a method of COMPRESSING THEIR RELOCATION RECORDS which is undocumented. EXEHDR itself can not show them either. Both SEX and EXEHDR will give a warning when they encounter one of these files. SEX'S WARNING: Yipes! Probable compressed relocations records!! Quitting. EXEHDR'S WARNING: Error U1108: Cannot display compressed relocation records. Secondly there are some EXE files like Windows 3.0's WINDEBUG.386 that SEX can not currently read. Apparently they are in the same page based, rather than segment based, linear exe format used by 32 bit flat model OS/2 2.0. EXEHDR itself _can_ do a report for these files. The EXEHDR flat model report looks a lot different from the conventional one it generates for 16 bit OS/2 and Windows files. YOU'LL STILL NEED EXEHDR: ------------------------- SEX compliments EXEHDR rather than replacing it. SEX does not try to show the full detail of the headers, since EXEHDR already does a good job of that. **************************************************************************** ABSTRACT OF PAPER/BOOK: ----------------------- This paper discusses some of the tools, techniques, motivations and legal/technical limits to reverse engineering Windows and OS/2 software. Reverse engineering is often the only way to obtain critical information about new, complex or undocumented features of operating systems and programs. This paper will discuss how to disassemble and analyze the operation of EXE, DLL and SYS files for Windows and OS/2. This paper will answer the questions: Why disassemble? How difficult is it? Examples will be presented including the relevant legal and ethical limits. What is the layout of the segmented executable file? How do you read and interpret its internal tables? How do you decompile from ASM back to C? TABLE OF CONTENTS FOR PAPER/BOOK: --------------------------------- 1. What is Reverse Engineering? 1-1 1.1. General Definition: 1-1 1.2. Applied to Windows and OS/2 Software: 1-1 1.2.1. Static disassembly of programs: 1-1 1.2.2. Runtime analysis of programs: 1-2 1.2.3. Decoding of file formats: 1-2 2. Reverse Engineering: Why and Why Not? 2-1 2.1. Why? 2-1 2.1.1. Getting Information: 2-1 2.1.2. Patching - Making Modifications: 2-1 2.2. Why NOT? 2-2 2.3. Legal, Moral and Philosophical Questions: 2-2 3. Law of Reverse Engineering and Patching Software 3-1 3.1. Introduction: 3-1 3.1.1. The Anti-Reverse Engineering Camp: 3-2 3.1.2. The Pro-Reverse Engineering Camp: 3-2 3.1.3. Does It Matter Who is Right? 3-2 3.2. The Context of General Intellectual Property Law: 3-2 3.2.1. Patent Law: 3-2 3.2.2. Trade Secret Law: 3-2 3.2.3. Copyright Law: 3-3 3.2.3.1. Reverse Engineering as a Violation of Copyright: 3-3 3.2.3.2. Counter Arguments: 3-4 3.2.4. Semiconductor Chip Protection Act: What is its Significance? 3-4 3.3. Diagram: Legal and Illegal Sources of Information: 3-4 3.4. The Shrink Wrap License Issue: 3-7 3.5. The Law of Software Patching: 3-7 3.6. Two Scales of Legal Risk: 3-8 3.6.1. What Can Be Safely Reverse-Engineered? The Scale of Purpose: 3-8 3.6.2. What Can Be Safely Imitated? The Scale of Idea Versus Expression: 3-9 3.7. How to Stay Within the Law: 3-10 3.7.1. Get a Good Attorney that Knows Reverse Engineering Law: 3-10 3.7.2. Keep a Written Statement of Goals and Sources: 3-10 3.7.3. Don't Sign Anything: 3-10 3.7.4. Buy from a Mass Market Retailer: 3-11 3.7.5. Avoid Improper Sources: 3-11 3.7.6. Clean Room: 3-11 3.7.7. Avoid Unnecessary Similarity: 3-11 3.8. References: 3-12 4. Technical Basics 4-1 4.1. The Simple COM File: 4-1 4.2. The Simple Old Exe File: 4-1 4.3. The Segmented Exe File: 4-2 4.4. The Linear Executable EXE File Format: 32 Bit Flat Model: 4-6 4.5. A Network of Segmented Exe Files: 4-10 4.6. Differences Between Windows and OS/2 EXE Formats: 4-13 4.7. For More Information: 4-13 4.8. Advantages and Disadvantages of the New Executable in Terms of Reverse Engineering: 4-14 5. Tools of the Trade 5-1 5.1. Introduction: 5-1 5.2. Debuggers / Disassemblers: 5-1 5.2.1. Windows: 5-1 5.2.2. OS/2: 5-1 5.3. EXEHDR: Segmented EXE Analysis: 5-1 5.4. SEX: Super Exe Header. An Enhanced Viewer of Segmented EXE Files: 5-3 5.4.1. Summary of Imports: 5-3 5.4.2. List of Exports for Multiple Files: 5-4 5.4.3. Exhaustive List of All Imports and Relocations in a File: 5-4 5.5. GDT: A Descriptor Table Viewer and Disassembler: 5-5 5.6. THESEUS: An OS/2 Memory Use Tool: 5-5 5.7. DENTIST: An OS/2 Resource Decompiler/Extractor: 5-5 5.8. Zortech's OBJTOASM 5-6 6. File Format Decoding 6-1 6.1. Introduction: 6-1 6.2. General Analysis Techniques: 6-1 6.2.1. Creating a Hex Dump: 6-1 6.2.2. Looking for patterns: 6-2 6.2.2.1. The Fundamental Particles: 6-2 6.2.2.1.1. The ASCII String: 6-2 6.2.2.1.2. The Byte, Word and Long Word: 6-2 6.2.3. From the Obvious to the More Complex: 6-2 6.2.4. The Cycle: Alter and Test... 6-3 6.2.5. Making an Intelligent Dump Program: 6-3 6.3. Example: Decoding the Codeview Format for EXE Files: 6-3 6.3.1. Where is the Codeview Information? 6-3 7. Sources of Information (Bibliography) 7-1 7.1. Microsoft "Open Tools Strategy": 7-1 7.1.1. Microsoft C "Developer's Toolkit Reference": 7-1 7.1.1.1. Introduction: 7-1 7.1.1.2. Part 1 in Detail. File Formats for EXE, OBJ, LIB, ILK, SYM Files: 7-2 7.1.1.2.1. Chapter 1: Object Module Format for Symbolic Debugging: 7-2 7.1.1.2.2. Chapter 2: Object Module Format Extensions: 7-2 7.1.1.2.3. Chapter 3: Extended .EXE Format for Debug Information: 7-2 7.1.1.2.4. Chapter 4: .ILK and .SYM Binary File Formats: 7-2 7.1.1.2.5. Chapter 5: Library Format: 7-2 7.1.2. Microsoft "Windows Developer's Notes": 7-3 7.1.2.1. Developing Network Applications for Windows 3.0: 7-3 7.1.2.2. Executable-File Header Format: 7-3 7.1.2.3. Font-File Format: 7-3 7.1.2.4. Setup Sources: 7-3 7.1.2.5. Windows Accessories Binary File Formats: 7-3 7.1.2.5.1. Windows Write Binary File Format: 7-3 7.1.2.5.2. Windows Calendar File Format: 7-4 7.1.2.6. Windows INT 21H and NetBIOS Support for DPMI: 7-4 7.1.2.7. Writing International Applications for Windows 3.0: 7-4 7.1.2.8. Topics Not Yet Covered: 7-4 7.2. Microsoft Windows Device Development Kit: 7-4 7.3. More Books and Articles: 7-4 7.3.1. Books: 7-4 7.3.1.1. "Undocumented DOS", 1990. Chief editor: Andrew Schulman: 7-4 8. Raw Disassembly of ICON.EXE with Symdeb and Preliminary Commenting 8-1 8.1. Introduction: 8-1 8.2. Raw Disassembly: 8-1 8.3. Disassembly of ICON.EXE with Preliminary Commenting Added: 8-3 9. Correlating the Reports of Super-Exe-Header, the Application's MAP File, and Disassembly of Portions of the Runtime Library 9-1 9.1. Introduction: 9-1 9.2. Super Exe Header Report: 9-1 9.3. Application Linker Map File: 9-2 9.4. Combining Linker Map File and Super-Exe-Header Reports: 9-3 9.5. Disassembly of C Runtime Library Winstart OBJ Module: 9-4 10. Runtime Analysis of Example Program 10-1 10.1. Introduction: 10-1 10.2. Setting Up The Debugger: 10-1 10.3. The Application Calls Windows: 10-1 10.3.1. API Prototype from Programmer's Reference: 10-1 10.3.2. Application's C Source Code for Call: 10-2 10.4. Inside the Windows Kernel: 10-2 10.4.1. EXEHDR's List of the Kernel's Exports: 10-2 11. Sample Program ICON.C in Original C Source and Mixed Source and Object Form 11-1 11.1. In Original C Source: 11-1 11.2. In Mixed Source and Object Form: 11-3 12. Documented and Undocumented Exports from Windows 3.0 USER.EXE, KERNEL.EXE and GDI.EXE 12-1 12.1. Introduction: 12-1 12.2. Summary of Export "Undocumentedness": 12-1 12.3. Exports from USER.EXE: 12-2 12.4. Exports From KERNEL.EXE 12-8 12.5. Exports From GDI.EXE: 12-11 12.6. Comparing What is Defined in SDK vs. DDK: 12-15 13. Undocumented Imports to Windows 3.0 Applications 13-1 13.1. Introduction: 13-1 13.2. TASKMAN.EXE: 13-2 13.3. MSDOS.EXE: 13-2 13.4. PROGMAN.EXE: 13-3 13.5. WINFILE.EXE: 13-3 13.6. CONTROL.EXE: 13-4