                MD5 hash algorithm DLL by Andy Brown 1994
                -----------------------------------------


Description
-----------
A hash algorithm such as MD5 is often used in cryptosystems to "reduce" a
user-supplied passphrase into a sufficient number of bits to use as a key
to the system. The following is taken from the Executive Summary section of
the Internet RFC that proposes MD5 as a standard.

The [MD5] algorithm takes as input an input message of arbitrary length and
produces as output a 128-bit "fingerprint" or "message digest" of the
input. It is conjectured that it is computationally infeasible to produce
two messages having the same message digest, or to produce any message
having a given prespecified target message digest. The MD5 algorithm is
intended for digital signature applications, where a large file must be
"compressed" in a secure manner before being encrypted with a private
(secret) key under a public-key cryptosystem such as RSA.

The MD5 algorithm is designed to be quite fast on 32-bit machines. In
addition, the MD5 algorithm does not require any large substitution tables;
the algorithm can be coded quite compactly.

The MD5 algorithm is an extension of the MD4 message digest algorithm. MD5
is slightly slower than MD4, but is more "conservative" in design. MD5 was
designed because it was felt that MD4 was perhaps being adopted for use
more quickly than justified by the existing critical review; because MD4
was designed to be exceptionally fast, it is "at the edge" in terms of
risking successful cryptanalytic attack. MD5 backs off a bit, giving up a
little in speed for a much greater likelihood of ultimate security. It
incorporates some suggestions made by various reviewers, and contains
additional optimizations.


Using MD5.DLL
-------------
For Borland C++ IDE projects, add MD5.LIB to your project. Makefile based
projects need to add MD5.LIB to the linker stage.

Include MD5.H in any of your project files that need to call the MD5
routines.

Ensure MD5.DLL is either in somewhere in your PATH environment variable, or
in your Windows SYSTEM directory.


                                   API
                                   ---


There are two ways to compute a hash. The first is totally automatic and
requires you to call only one function. The other is more general and
requires you to manually call the initialisation, update and termination
functions.

VOID FAR PASCAL MD5(LPBYTE data,int bytes,LPBYTE hash)

data    FAR pointer to the information to hash
bytes   number of bytes pointed to by `data'. Must be <=32767.
hash    FAR pointer to a a buffer to receive the 128 bit (16 byte) hash

        This function is the simplest way to interface to MD5, but relies
        on there being less than 32K of data to hash. Not so good for
        hashing files, but fine for hashing down a passphrase to get a
        cryptographic key.

VOID FAR PASCAL MD5Init(VOID)

        Initialise the internal MD5 variables. You must call this before
        using MD5Update() or MD5Final().

VOID FAR PASCAL MD5(Update(LPBYTE inBuf,WORD inLen)

inBuf   FAR pointer to buffer containing information to add to current hash
inLen   Number of bytes in `inBuf'. Note inLen must be <=64K

        This function updates the current hash with the contents of inBuf.
        If you are hashing a file then it is likely that you will call this
        many times as you read in data.

VOID FAR PASCAL MD5Final(VOID)

        Finishes off the hashing. You must call this when you are finished
        calling MD5Update().

VOID FAR PASCAL MD5GetHash(LPBYTE hash)

hash    FAR pointer to a 16 byte buffer that is to receive the hash

        After completing a hash operation that will have typically
        consisted of a call to MD5Init, many calls to MD5Update and then a
        single call to MD5Final, this function returns you the actual 16
        byte hash.
          

Comments
--------
MD5.DLL was compiled using Borland C++ v3.1 with optimizations set to
`fastest'. The API interface was designed to shield the user from exposure
to the internal MD5_CTX structure. 


Have fun,

Andy


+---------------------------+----------------------------------------------+
| Andy <asb@cs.nott.ac.uk>  | PGP key fingerprint: EC 80 9C 96 54 63 CC 97 |
|    finger for PGP key     |                    : FF 7D C5 69 0B 55 23 63 |
+---------------------------+----------------------------------------------+
