1 /**

     2 	@page cryptographic_hash Cryptographic Hash Functions

     3 	

     4 	- @ref hashWhat

     5 	- @ref hashHow

     6 	- @ref hashWhich

     7 	- @ref hashHmac

     8 

     9 	@section hashWhat What is a cryptograhpic hash?  

    10 	

    11 A cryptographic hash (also known as a message digest, a one-way function, or

    12 simply a hash) maps messages of arbitrary finite length to a message of a fixed

    13 known length.  It is often useful to think of the resulting output as a

    14 representation, or fingerprint, of the original input.

    15 

    16 Two properties are important to cryptographic hashes:

    17 - that it is highly unlikely that two distinct strings will hash to the same

    18   output.

    19 - that is is extremely difficult to determine the original input given only the

    20   output.

    21 

    22 These properties make hash functions useful in cryptography and other

    23 applications as they allow the representation of objects in a known fixed size.

    24 

    25 	@section hashHow How do I use the hash framework?

    26 

    27 There are a couple of ways to interact with the hash framework.  The following example 

    28 is probably the most common: 

    29 

    30 @code 

    31 _LIT(messagePart1, "Hello ");

    32 _LIT(messagePart2, "My "); 

    33 _LIT(messagePart3, "Name "); 

    34 _LIT(messagePart4, "is Fred"); 

    35 TBuf8<20> hash;

    36 

    37 CSHA1* sha1 = CSHA1::NewL(); 

    38 sha1->Update(messagePart1);

    39 sha1->Update(messagePart2); 

    40 sha1->Update(messagePart3);

    41 hash.Copy(sha1->Final(messagePart4)); 

    42 @endcode

    43 

    44 Note that \c Final() has a version that takes no data parameter which may be

    45 useful in certain situations.

    46 

    47 A few pointers:

    48 	- You can reuse a hash object by calling \c Reset().  

    49 	- Both versions of \c Final() call \c Reset() at the end of their function automatically.

    50 	- Be aware that the returned \c TPtrC8 from \c Final() points to an internal

    51 	  buffer.  Calling \c Update() or \c Final() again changes the contents of this

    52 	  buffer and will destroy your previously computed hash.  As in the example

    53 	  above, make sure you copy the data out if you need it.

    54 

    55 	@section hashWhich Which hash should I use?

    56 

    57 Unless you have a specific need to support certain hashes, use @ref SHA "SHA-1".

    58 

    59 	@section hashHmac What is an HMAC?

    60 

    61 HMAC (Hashed Message Authentication Code) is a key dependant hash.  It allows

    62 one to specify a key at creation of the HMAC.  Only persons with that key can

    63 verify the hash.  HMACs are useful when authentication but not secrecy of a

    64 message is required.

    65 */