| SYMBOL RETRIEVER SHELL EXTENSION (with source code) |
SYMBOL RETRIEVER SHELL EXTENSION
Symbol Retriever is a shell extension for Windows Explorer written with ATL that allows to retrieve symbols for images belonging to a Microsoft Operating System installation simply right-clicking on one or more module (*.sys; *.exe; *.dll etc.) in Explorer and selecting the program option in the displayed context menu. The beauty of Symbol Retriever is that it doesn't use or require SymSrv.Dll from the "Debugging Tools for Windows"...
This is a screenshot of the extension dialog:
This is a screenshot of the same feature of the extension as implemented in the BugChecker Symbol Loader (not provided for download from this page):
(In this screenshot, you may notice the HTMLDDX feature described later)
WHAT THIS EXAMPLE SHOWS
Please consider that the working code of this example application was stripped from the original implementation of the Symbol Retriever feature of my kernel debugger: BugChecker. So it uses the proprietary BCSTRANS.DLL module for retrieving informations about the submitted module images and uses a Windows messaging mechanism that may be considered unnecessary in this specific case (in the original application the Symbol Retriever feature is presented to the user as an HTML form, through my HTMLDDX technology, so I couldn't make operations on a WebBrowser DOM from an arbitrary thread: the messaging mechanism is a result of that architecture).
These are the features of the code presented in this article:
 |
Example of proprietary code for downloading symbols of operating system images from the Microsoft Symbol Store site at http://msdl.microsoft.com/download/symbols without requiring SymSrv dll from "Debugging Tools for Windows". |
 |
| |
Example of how to write an Explorer Shell Extension with ATL and how to present to the user a dialog derived from CDialogImpl<>. |
|
| |
Example of the use of the File Decompression Interface (FDI) from CABINET.DLL for decompressing files downloaded from the Microsoft Symbol Store site. |
|
| |
Example of the use of the "URLDownloadToCacheFile" API for downloading from the internet. |
|
| |
Example of implementation of the "IBindStatusCallback" interface for managing download interruption and download progress status showing. |
INTRODUCTION
I will not talk here about the importance of OS symbols when debugging an application or a driver or in post-mortem debugging situations (internal symbols, FPO and call stack trace accuracy, OS internal types etc.) but I will focus on the little application in hand. In my specific case, when I need to reverse engineer something or when I need to figure out how a specific operating system feature or function works, the correct symbols for the specific OS modules I am dissecting are even more important. So I decided to develop this little ATL Explorer extension for two main reasons:
| |
because it is useful, mainly when you are debugging with SoftICE or with an old user-mode debugger (like VS6). Yeah, I know that with SoftICE you can use the provided "Symbol Retriever" application (it uses internally the SymSrv dll and so even preserves the correct symbol store format when saving PDB and DBG files on disk) but I guess that a simple select-and-click operation is more desirable when downloading symbols for many modules. |
|
| |
to show how the Microsoft published symbols for major OS releases are organized inside their SymSrv symbol store (http://msdl.microsoft.com/download/symbols). |
I have always been fascinated by the whole Microsoft public symbol store initiative. Some time ago, when developing the Symbol Retriever feature of my BugChecker Symbol Loader application, I had to decide whether to use the Microsoft provided SymSrv.Dll module (that is redistributable) to do the job or to figure out the format of the Microsoft symbol store tree and then implement a proprietary solution for downloading the desired files. Guess which I chose... So, this could be an unique occasion to go even deeper in my understanding of how the SymSrv module works.
TWO WORDS ABOUT SYMSRV
SymSrv is a dll module that is called by DbgHelp when there is the need to obtain a symbol file (.PDB and even .DBG files in the case of earlier operating systems such as Windows 2000 or NT4) from one or more centralized or local symbol stores. The main public symbol store is at the address: http://msdl.microsoft.com/download/symbols. The symbol path that can be specified for addressing a specific store can contain more than one URL or UNC/local path; these informations are useful for locating the correct symbol file(s) for a specified executable in a kind of multi-level cache search fashion: if you are interested in this specific topic (the format of symbol paths and the downstream stores), I advise to take a look at the MSDN library for further details (follow the link at the bottom of this page).
The SymSrv feature is particularly useful because it is integrated in WinDbg: after specifying the correct symbol path either adding the _NT_SYMBOL_PATH environment variable or adding the symbol path in the File->Symbol File Path dialog, the debugger will download and cache automatically the required symbol files on the fly, when needed. A tipical symbol path looks like this:
srv*c:\locsymstore*http://msdl.microsoft.com/download/symbols
The SymStore.Exe on the contrary can be used to create and manage local and network symbol stores of any type; it includes the possibility of creating a "custom" symbol store, allowing to leverage the whole symbol store idea for managing and making public the binaries and symbols of your own projects and applications in an ordered and neat structure (as Microsoft does for its IIS published symbol store that happens to work perfectly for several giant application projects such as Windows 2000 and Windows XP, proving the effectiveness of the technology)...!! Take a look at the MSDN Library for further informations about this.
Additionally, the SymChk utility provided with the "Debugging Tools for Windows" installation can be used to download symbol files directly, without relying on WinDbg to do it automatically when needed: this can be useful in the case of unavailable or slow internet connections that may hang your WinDbg. In my WinNT directory you can find a file named "retrieve.bat" created as follows:
symchk.exe /r %1 /s srv* c:\locsymstore*http://msdl.microsoft.com/download/symbols /v
When typing at a command prompt something like this:
retrieve win32k.sys
The SymChk utility will download the win32k module symbol files (they are two: a .PDB file and a .DBG file: the tests were conducted on a Windows 2000 Server machine, as explained before) and will store them in my local symbol store at the paths:
C:\locsymstore\win32k.pdb\402ACE641\win32k.pdb
C:\locsymstore\win32k.dbg\4047DCD61a3f20\win32k.dbg
These files happen to have been published at the following URLs (however in a compressed format, for obvious reasons, in spite of the local versions):
http://msdl.microsoft.com/download/symbols/win32k.pdb/402ACE641/win32k.pd_
http://msdl.microsoft.com/download/symbols/win32k.dbg/4047DCD61a3f20/win32k.db_
So, what is the meaning of that numbers that make unique each URL? The answer is in the next section.
SYM STORE TREE FORMAT
Part of my research activity when writing the aforemetioned code for the BugChecker Symbol Retriever application was dedicated to discovering how the URLs shown above are composed.
The HEX number that appears in each URL is calculate as follows:
| |
For PDB files it is the "signature" and "age" numbers, where the former is simply appended as a string to the latter. A .PDB signature is simply an HEX number that is unique for each instance of a PDB. It is actually a unique ID (GUID) for PDBs. The .PDB age is the "version" of a specific instance of a .PDB file. For files compiled with the Microsoft compilers shipped with Visual Studio's versions previous to .NET (5 and 6) that signature number is actually a DWORD number (32-bit) contained in an "NB10" header structure. For the next versions of Visual Studio that number is contained in a "RSDS" structure and has been expanded to a full 128-bit wide GUID. This choice was made, I believe, for ensuring a true uniqueness of that number and for conforming to the Windows de facto standard of unique ID numbers (that are 128-bit rather than only 32-bit wide). These structures (NB10 and RSDS) are specified in the CodeView Debug Directory in the case of an executable image compiled with the debug info and in an special Debug Directory in the case of a .DBG file. |
|
| |
For DBG files it is the time stamp and the size of the image, expressed as HEX numbers, where the former is appended as a string to the latter. |
USEFUL LINKS
Symbol Servers and Symbol Stores documentation from MSDN site: link.
INSTALLATION
Unzip the archive and then register the Extension dll with RegSvr32. Open an instance of Windows Explorer, go to the Windows directory, pick one file with an .exe or .dll extension, right-click on it, select "Retrieve Symbols for x image(s)..." and then wait while the download completes. The .PDB and eventually the .DBG files are stored in the same directory as the source image.
DOWNLOAD
Download the Symbol Retriever Shell Extension (binaries only) from here (434KB).
Download the Symbol Retriever Shell Extension (plus source code) from here (475KB).
|
|
|
|
|
|
|
|
|
|
|
Photos |
Various images from italian conferences and events (keep the mouse
on a thumbnail for a short description):
|
 |
 |
 |
 |
|
|
|
|
|
| Site
login |
| NOTE: Actually the login feature is used only for
administrative and content management purposes.
|
|
|
|
|
|
|
|
Everything here (code, binaries, text, graphics, design, html) is © 2010 Vito
Plantamura and VPC Technologies SRL (VATID: IT06203700965).
If you download something (compilable or not) from the site, you should read
the license policy file.
If you want to contact me via email, write at this
address. |
|
|