Message Digests
***************

Message digests, or one-way hash functions, generate fixed-sized signatures from variable-sized texts, in such a way that it is computationally infeasible to determine the source text from the signature or to find a different text that hashes to the same signature. Hash functions in GNU Crypto are in the gnu.crypto.hash package, and are:

  * MD2. MD2 is an early-generation hash function with an 128 bit output size, developed by Ron Rivest at RSA Data Security, Inc., and described by Burton Kaliski in RFC 1319 [Kal92]. No significant cryptanalysis has been published about MD2, but it is still recommended that new applications use a different message digest algorithm.

  * MD4. MD4 was also developed by Ron Rivest at RSA Data Security, Inc. and is described by Rivest in RFC 1320 [Riv92a]. MD4 has a 128 bit output size. It is not recommended that MD4 be used in new applications.

  * MD5. MD5 is a successor to MD4, developed by Ron Rivest and described in RFC 1321 [Riv92b], and has a 128 bit output size. MD5 is not widely considered secure any longer, and using other message digests with longer output sizes is recommended.

  * RIPEMD. RIPEMD-128 and RIPEMD-160 have 128 bit and 160 bit output sizes, and were developed by Hans Dobbertin, Antoon Bosselaers, and Bart Preneel as successors to the RIPEMD hash.

  * The Secure Hash Algorithm, SHA-1. The secure hash algorithm was developed by the National Institute for Standards and Technology, published in FIPS 180-1. SHA-1 has a 160 bit output length. FIPS 180-2, dated August 2002, added the specifications for three additional SHA implementations for output sizes of 256-, 384- and 512-bit respectively. These three algorithms are referred to as SHA-256, SHA-384 and SHA-512.

  * Tiger is a hash function created by Lars Anderson and Eli Biham, optimized for 64-bit architectures. It can produce a 192, 160, or 128 bit hash. [AnB96]

  * Whirlpool. Whirlpool was designed by Paulo S. L. M. Barreto and Vincent Rijmen, and has a 512 bit output length.

IMessageDigest Interface
========================

Figure 8: Message Digest class diagram

 -- Function: void update (byte B)
     Updates the hash being computed with a single byte.

 -- Function: void update (byte[] BUF, int OFFSET, int LENGTH)
     Update the hash being computed with LENGTH of the bytes in BUF starting at OFFSET. The programmer should ensure that BUF is at least offset + length bytes long.

 -- Function: byte[] digest ( )
     Finishes the computation of the hash and returns the result as a byte array. The input read thusfar may be padded first (depending on the algorithm), and the instance is reset.

 -- Function: java.lang.String name ( )
     Returns the canonical name of this message digest.

 -- Function: int hashSize ( )
     Returns the size of the final hash (the byte array returned by digest()) in bytes.

 -- Function: int blockSize ( )
     Returns the algorithm's internal block size, in bytes.

 -- Function: void reset ( )
     Resets the internal state of the hash, making its state equivalent to that of a newly-created instance.

 -- Function: boolean selfTest ( )
     Performs a simple conformance test of the underlying implementation, to guard against implementation or environment errors. Returns true if the test succeeds, false if it fails.

 -- Function: java.lang.Object clone ( )
     Copies the state of this instance into a new instance, returning the copy. This copy can then be used in the same way as the original instance.

HashFactory Class
=================

Message digest instances are created with the static factory method:

 -- Function: IMessageDigest getInstance (java.lang.String NAME)
     Creates a message digest instance for the algorithm NAME, or null if there is no such algorithm.

The HashFactory class also defines the method:

 -- Function: java.util.Set getNames ( )
     Returns a set of the names (strings) of all available message digest implementations.

Example
=======

     IMessageDigest md = HashFactory.getInstance("SHA-1");
     md.update(input, 0, input.length);

     byte[] digest = md.digest();