binpatch [doc]

binpatch release 1.0 (december 1999)

IN THIS FILE

WHAT IS BINPATCH?

Welcome to release 1.0 of binpatch. Binpatch, simply put, is a program designed for the automated patching of binary files. I designed binpatch while working on a project that required the repeated, unattended modification of binary executables, and I'm releasing it now to the general public in hopes that someone else may find it useful.

USING BINPATCH

To use binpatch you'll need three things: The binpatch executable, (binpatch.exe), the binary file you planning on "patching", and a binpatch script file (.bps). I'll assume that you already know what file it is so you want to patch, so I'll only explain how to use the other two elements. :-)

Using the executable will be explained under "binpatch syntax", below, and the bps language will be explained under "binpatch scripts", also below.

BINPATCH SYNTAX

The binpatch executable has three modes it can be invoked in:

Run a binpatch script on some file
Return only the binpatch-checksum of some file
Return only the size of some file

The first requires two parameters on the command line, a binpatch script and the name of the file you want to "run" the binpatch script on. Example:

c:\temp> binpatch myscript.bps myfile.exe

This will "run" myscript.bps on myfile.exe. (Note: binpatch scripts don't have to have the extension .bps, you can make it anything you want). If you want to backup the file myfile.exe before you "binpatch it," type:

c:\temp> binpatch /b myscript.bps myfile.exe

Backing up the file will save a backup as myfile.old in the current directory.

The last two modes require only a switch specifying which mode you want to be in and the name of the file you want to run the mode on. For example, to find out the size, in bytes, of a file:

c:\temp> binpatch /s myfile.exe

Or, to find out the binpatch-checksum of myfile.exe:

c:\temp> binpatch /c myfile.exe

BINPATCH SCRIPTS

Binpatch scripts are stored in binpatch script files, (.bps). They consist of command-arguement pairs on seperate lines. Here is an example binpatch script file (myscript.bps):

	BEGIN binpatch 1.0 script file
	%
	% These are printed comments.
	% If you want to print a message out to the user when
	% they run your script, put "%" at the beginning of
	% the line.
	%

	REQD BINPATCH_1.0
	
	SIZE 1234ABCD
	CSUM ABCD1234
	FIND AAFFAAFF:00001111
	FIND AB:01
	ADDR ABCD:0123

	CSUM ABCD5678

	END

Binpatch interprets this file from the top down. There is NO pre-processing.

The first thing binpatch does when it reads this file is print out the comments at the top to the user, (the % symbol is not printed). Later binpatch reaches the command-arguement pairs:

	REQD BINPATCH_1.0

The REQD command stands for "required." The arguement is the version string for the version of binpatch that is required to run this script. If the version is required is greater than the version of binpatch running the script, binpatch will abort.

	SIZE 1234ABCD

The SIZE command takes one arguement, the size, (in bytes), that the file we're patching must be in order to continue. If the arguement does not match, exactly, the size of the file, binpatch aborts.

	CSUM ABCD1234

The CSUM command also takes one arguement, the binpatch- checksum that the file we're patching must have in order to continue. Again, if the checksum doesn't match binpatch will abort. (See "binpatch syntax" for how to obtain the binpatch-checksum).

	FIND AAFFAAFF:00001111

The FIND commands takes two arguements, colon delimited. The FIND command is kind of like a "find-replace," like you'd encounter in a text editor. The first arguement is the hexadecimal "string" you're searching for, and the other is the "string" you want to replace it with. The string can be anywhere up to 4 bytes long:

	FIND AB:01

FIND isn't the most efficient way to patch files, but can come in handy if the string you're searching for appears in different places in different versions of the same file. If the string is in the same place everytime, you probably want to use ADDR.

	ADDR ABCD:0123

ADDR is an address patch that takes two arguements. The first arguement is the address in the file you want to patch, followed by the string you want to patch with.

	CSUM ABCD5678

Sometimes you might want to check the binpatch-checksum at the end of patching to make sure the patches went as expected. It can't hurt.. :-)