/**

	@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.

*/