MD5SUM.TXT -- Documentation for MD5SUM.EXE


WHAT IS THIS?

MD5SUM is a GPLed program used for computing and checking
cryptographic message digests (or check values) of files.  It was written
with the Unix philosophy of reading from standard input and writing to
standard output, and options can be preluded with "-" or "/".  To get a
rather terse help message, type

md5sum /?

at the DOS prompt.  Md5sum.exe will respond with its help prompt.

When checking files, MD5SUM generates no output if the files match their
fingerprints, unless you also specify the -v switch.  If there is a problem,
it will generate one or more of the following messages:

can't open filename
error reading filename
check failed for filename
_ of _ file(s) failed check
no files checked


WHY WOULD I WANT TO DO THAT?

If the MD5 message digest "fingerprint" of a file has not changed, this is a
VERY good indication that the contents of the file has not changed.  Even if
you wanted to change a file in such a way that it still had the same MD5
"fingerprint," you probably couldn't do it without a lot of supercomputer
time (and neither could a bad guy).  This makes it useful for detection of
forgeries, viruses, and just plain transmission errors.  Note that this is
much more powerful than a normal CRC, which is good at detecting some kinds
of transmission errors, but can easily be forged.  This is also useful for
signing a collection of files with a digital signature (using PGP, a PEM
implementation, or some kind of DSA implementation, for example), without
having to individually sign each file.  Simply create a text file with the
"fingerprints" of each file you wish to sign, then sign that text file.

COMPUTING FILE MD5 FINGERPRINTS

To compute the MD5 fingerprint of a text file, simply type

MD5SUM filename(s)

Wildcards are supported in the filenames, and file lists can be used with @
in front of the filename containing the list.  To use a digest mode other
than MD5, you may specify the /M: parameter with SHA, SHA2, CRC32, or MD5
as the ending of the parameter.

MD5SUM filename(s)

To see the file names displayed while computing "fingerprints," include the
/V option, like:

MD5SUM /V filename(s)

To write the output to a file instead of just displaying it on the screen,
use redirection with the ">" character, like:

MD5SUM /V filename(s) > md5file

To append the output to an existing file, use two > characters, like:

MD5SUM /V filename(s) >> md5file


ADDING COMMENTS TO CHECK FILES

Sometimes it is nice to add comments to files containing MD5 fingerprints. To
do this, just edit the files made using the above instructions to add in what
you want to say.  Lines that do not start with valid hexadecimal digits are
ignored as comments.


CHECKING FILES AGAINST STORED FINGERPRINTS

To check all of the files listed in check files as generated above to see if
they have changed:

MD5SUM /C md5file

For a more verbose listing of results (listing file names followed by "OK" or
"FAILED"), type:

MD5SUM /CV md5file


DETECTING MODIFICATION OR FORGERY OF FINGERPRINT FILES

One way to prevent alteration of fingerprint files is to store several copies
in different secure places, then compare them from time to time.  Another way
is to use a digital signature produced by PGP, some PEM implementation, or a
DSS implementation.  PGP is the most widely used digital signature program in
the public sector right now.


SOURCE CODE

The source code I used to compile MD5SUM.EXE is available in the file
MD5SUM.ZIP (available on the Colorado Catacombs BBS at 303-772-1062).  I did
some minor edits to the source code as distributed with the Pretty Good
Privacy program (PGP) to make the compile completely free of warning messages
with my compiler, but made no functional changes to the code.  I checked to
make sure that the result was compatible with the "pure" code from the PGP
distribution.  I resisted temptation to make the command line and user
interface more like a DOS program, so this works exactly like the PGP
distribution compiled for other platforms.  Source code is supplied so that
you can see how this works and see for yourself that there is no "monkey
business" in the code.  You may also have an opportunity to make use of some
of it for other applications.

I, Blair Campbell, have modified the source code to remove getopt, add
support for wildcards, add support for on-the-fly translation, and several
other minor enhancements, such as adding support for both '-' and '/'
switches.  Since GPLed code has been used, MD5SUM is now under the GPL.

These are the commands used with OpenWatcom and UPX to compile MD5SUM.EXE:

build release

If you do not have OpenWatcom but have Pacific C or Turbo C, the same
command should find out what compilers you have and use the most
appropriate one.  Ports to other compilers are welcome, and Borland C will
likely also work without any source code changes, though the above
command will not work.

LEGAL NOTICES AND CREDITS

This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

The idea for the command-line parsing part of MD5SUM came from Free XDEL,
and the IO95 library was slightly modified to compile on OpenWatcom without
warning or error.
