--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/crypto/weakcrypto/docs/hash.dox	Wed Jul 08 11:25:26 2009 +0100
@@ -0,0 +1,65 @@
+/**
+	@page cryptographic_hash Cryptographic Hash Functions
+	
+	- @ref hashWhat
+	- @ref hashHow
+	- @ref hashWhich
+	- @ref hashHmac
+
+	@section hashWhat What is a cryptograhpic hash?  
+	
+A cryptographic hash (also known as a message digest, a one-way function, or
+simply a hash) maps messages of arbitrary finite length to a message of a fixed
+known length.  It is often useful to think of the resulting output as a
+representation, or fingerprint, of the original input.
+
+Two properties are important to cryptographic hashes:
+- that it is highly unlikely that two distinct strings will hash to the same
+  output.
+- that is is extremely difficult to determine the original input given only the
+  output.
+
+These properties make hash functions useful in cryptography and other
+applications as they allow the representation of objects in a known fixed size.
+
+	@section hashHow How do I use the hash framework?
+
+There are a couple of ways to interact with the hash framework.  The following example 
+is probably the most common: 
+
+@code 
+_LIT(messagePart1, "Hello ");
+_LIT(messagePart2, "My "); 
+_LIT(messagePart3, "Name "); 
+_LIT(messagePart4, "is Fred"); 
+TBuf8<20> hash;
+
+CSHA1* sha1 = CSHA1::NewL(); 
+sha1->Update(messagePart1);
+sha1->Update(messagePart2); 
+sha1->Update(messagePart3);
+hash.Copy(sha1->Final(messagePart4)); 
+@endcode
+
+Note that \c Final() has a version that takes no data parameter which may be
+useful in certain situations.
+
+A few pointers:
+	- You can reuse a hash object by calling \c Reset().  
+	- Both versions of \c Final() call \c Reset() at the end of their function automatically.
+	- Be aware that the returned \c TPtrC8 from \c Final() points to an internal
+	  buffer.  Calling \c Update() or \c Final() again changes the contents of this
+	  buffer and will destroy your previously computed hash.  As in the example
+	  above, make sure you copy the data out if you need it.
+
+	@section hashWhich Which hash should I use?
+
+Unless you have a specific need to support certain hashes, use @ref SHA "SHA-1".
+
+	@section hashHmac What is an HMAC?
+
+HMAC (Hashed Message Authentication Code) is a key dependant hash.  It allows
+one to specify a key at creation of the HMAC.  Only persons with that key can
+verify the hash.  HMACs are useful when authentication but not secrecy of a
+message is required.
+*/