HT Editor
=========

   This is HT 0.4.5, including HT-analyser 0.5.9; please note that this
is a beta version of the program.  Therefore HT is incomplete and
sometimes buggy. Enjoy anyway...

About
=====

This program is a file viewer, editor and analyzer (mostly) for text,
binary, and especially executable files.

     This program comes with ABSOLUTELY NO WARRANTY This is free
     software, and you are welcome to redistribute it under certain
     conditions For more information please read the GNU General Public
     License, contained in the file "copying" If you do not have
     received a copy of this file along with this program, please write
     to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
     02139, USA.

Key bindings
============

   * General key bindings

     Space             follow link (if applicable)
     Backspace         undo "follow link"
     Enter             choose view mode
     Alt+[1-9]         select window
     Alt+0             select window list
     Ctrl+Left/Right   scroll left/right
     Cursor keys       move around
     Page Up/Down      next/prev page

   * Window key bindings

     Alt+F3            close window
     Ctrl+F5           toggle resize/move mode
                       (in resize/move mode only:)
     Cursor keys       move window
     Ctrl+Cursor keys  move window quickly
     Shift+Cursor keys resize window

   * Analyser key bindings

     c                 continue code analysis at cursor
     f                 follow dword ptr at address
     n                 name current address (empty string to delete)
     x                 show xrefs (search for xrefs)
     #                 edit comments
     Ctrl+A            call assembler
     Ctrl+F            goto start of current function
                       (indicated in the 2nd line)
     Ctrl+L            goto previous label
     Ctrl+T            show recursive function references

   * Help viewer key bindings

     Cursor keys       move around
     Space, Enter      follow topic link
     Backspace, Alt-F1 previous topic



Note: Some versions of HT (linux for now :-) don't support some of
these functions or use different settings (try substituting Ctrl with
Alt, etc...)

Authors
=======

   Stefan Weyergraf (<stefan@weyergraf.de>)

   Sebastian Biallas (<sb@biallas.net>)

Features
========

   At the moment HT lacks a lot of features which would make it a
perfect binary file editor (e.g. search with replace), but therefore
contains some very advanced and useful features that are sometimes not
noticed at a first glance:

Known file formats
==================

  1. Supported file formats
        * common object file format (COFF)
               - header

        * executable and linkable format (ELF)
               - header
               - section headers
               - program headers
               - symbol tables
               - image with code/data analyser (x86)

        * linear executables (LE)
               - header
               - object table
               - page table
               - image (disassembly only)

        * standard dos executables (MZ)
               - header
               - relocations
               - image (disassembly only)

        * new executables (NE)
               - header
               - segments
               - names
               - entrypoints

        * portable executables (PE)
               - header
               - import section
               - delay-import section
               - export section
               - resources
               - image with code/data analyser (x86 & alpha)

        * Still some to be implemented (M$-OBJ, ARCH, LX)

  2. Code & Data Analyser
          - finds branch sources and destinations recursively
          - finds procedure entries
          - creates labels based on this information
          - creates xref information
          - allows to interactively analyse unexplored code (press 'c')
          - allows to create/rename/delete labels (press 'n')

  3. Target systems
          - DJGPP
          - GNU/Linux
          - FreeBSD
          - Win32

Configuration files
===================

   HT automatically creates a file to store its store its configuration.
It is called `~/.htcfg' on Unices and `ht.cfg' (in ht.exe's directory)
on Windows. More specifically it contains HT's registry and the *Note
Global history::.

Clipboard
=========

   All open files and dialogs are sharing one common clipboard, where
all copied and cut text or binary data is stored. Clipboard operations
are normally binary safe, that means you can copy some binary data out
of a file and paste it into an input line. Exceptions are only the \0
character (binary null), it will be converted to a space in places
where it would not make sense (e.g. file open).

   Although the clipboard won't be saved between different HT sessions
(ie. you will loose it when exiting HT), you can either save and load
it manually (via Edit->save/load Clipboard) or rely on the input lines'
*Note history: Global history, which is stored and retrieved from the
config file automatically.

Global history
==============

   HTs history system is global, which means that you can use it for
all open files. Histories are also grouped by their meaning. I.e.
file-related and regex-search-related dialogs have their own history
(who would want to open "[0-9][0-9a-z]*" anyway ?).

   History entries are stored within the *Note Configuration files::,
so they can be reused when you relaunch.

   You can delete any history entry by pressing DEL inside the history
popup.

Expression evaluation
=====================

   HT contains a very powerful expression evaluator which is used in
all dialogs where expressions are expected. These are mainly
blockoperation, goto, search and of course evaluate itself
(Edit->Evaluate).

   You can use all standard math operators (+ - / * % **), logical
operators (! && || ^^), relational operators (== != < > <= >=), bit
operators (~ & | ^), string operators (. for concatenation),
parenthesis, the ternary operator (a?b:c), functions and symbols (both
depending on context).

   The evaluator uses integer, string and float types depending on
context. You can always convert a result via the `int()', `string()'
and `float()' functions to appropriate type. Try Edit->Evaluate to see
how it works...

Functions and symbols
---------------------

   You can always use the standard buildin math (`round', `sin',
`random', etc.) and string (`strcmp', `strchr', `sprintf', etc.)
functions, they work more or less like the corresponding C functions
(they ARE more or less wrapper for them); see `eval/eval.y' for details
(sorry but a detailed help would get outdated rather soon).  When using
*Note Block operations::, or searching you have some context depending
functions and symbols; see these sections for explanation.

Block operations
================

   Block operation (Blockop) is a very powerful tool to perform
modifications on binary files. It is available in hex viewer only.

   Blockop takes four parameters: `start', `end', `mode' and
`expression'. Blockop works as follows:

   * START: Start at the offset specified by `start'

   * REPEAT: Evaluate `expression' and store n bytes (1 - byte, 2 -
     word, 4 - dword, variable - string) at the current offset.
     Increment current offset by n. Stop if `end' has been reached.

Special variables/functions that can be used in `expression':

`readbyte(ofs)'
     read a byte from offset `ofs', returns a number

`readstring(ofs, size)'
     read `size' bytes from offset `ofs', returns a string

`i'
     contains the iteration count/index starting with 0

`o'
     contains the current offset

Search and its different modes
==============================

   The search function is one of the most advanced functions of HT.
Depending on context (ie. file type and mode) the following modes are
enabled:

bin: ASCII / Hex
----------------

   Enter an exact search string either via ascii characters or via
hexadecimal interpretation. This is the fastest search mode. You can
specify a case-insensitive search, and continue the search with
Shift-F7; this applies also to the other search modes.

bin: eval str
-------------

   Enter an expression, it will be evaluated ONCE (this differs to the
4th mode), and HT will then search for the result-string. This is
pretty useful when searching for intermixed text and
control-chars/binary, e.g. `"hello world\n\0"'

display: regex
--------------

   As the prefix indicates, this search doesn't search in the binary
file but in the display on screen. HT searches for a regular expression
so this can be very powerful, e.g. in PE/Image you can search for
`(add|sub).*?, *?[78]'.  This will find all add or sub instructions
with second parameter 7 or 8.

expr nonzero
------------

   This is the slowest but also most advanced search mode. Enter an
expression and the search stops if this expression evaluates to
non-zero (it will be evaluated on every byte). In this mode there are
two predefined symbols and some functions: `i' is always the number of
current iteration and `o' stands for current offset in file. With the
functions `readbyte(ofs)' and `readstring(ofs, size)' you get the
content of the file.

   It's easier to understand with these two examples:

  1. Searching for patterns:

       a. Enter `readbyte(o) == readbyte(o+1)'
          This will search for two equal bytes ("AA", "55", "!!", etc.).

       b. Enter `(readbyte(o) == readbyte(o+1)+1) &&
          (readbyte(o)==readbyte(o+2)+2'
          This will search for three ascending bytes ("ABC", "123",
          etc).

  2. Search with special functions:

     With HT you can easily detect the RSA key in the `ADVAPI32.DLL':
     Search for `entropy(readstring(o, 64)) > 82' in expr!=0 mode, and
     you will directly find it. How does it work? `readstring(o, 64)'
     reads a 64 byte string from current offset and entropy calculates
     the entropy ("randomness") of a string (result is 0..100).  So
     this expression stops if a entropy greater than 82% (guessed value)
     is encountered, this normally indicates packed or encryted data.

     Note: the `entropy()' function is not the best, if you know of a
     better one please let us know!


Where to download ?
===================

The HT homepage is at `http://hte.sourceforge.net'

Downloads are available from the 'download' section.  Please also take
a look at `http://sourceforge.net/projects/hte'

