Fastbufs: Clean up exception handling

[libucw.git] / ucw / doc / hash.txt

diff --git a/ucw/doc/hash.txt b/ucw/doc/hash.txt
index b28c42a76eb5448ba0b403851f368ad294bf8630..3e01b94156c23de6d9a79f7732f7992954787a89 100644 (file)
--- a/ucw/doc/hash.txt
+++ b/ucw/doc/hash.txt
@@ -1,26 +1,43 @@
 Hashing routines
 ================
 
 Hashing routines
 ================
 

-Libucw contains two hash algorithms, MD5 (RFC 1321) and SHA1 (RFC
-3174).
+Libucw contains two cryptographic hash algorithms: MD5 (RFC 1321) and SHA1 (RFC
+3174). A SHA1-HMAC (RFC 2104) message authentication is available.
+
+There are non-cryptographic hashes as well.
+
+<<crypto,Cryptographic ones>>:

 
 - <<md5,MD5>>
 - <<sha1,SHA1>>
 
 - <<md5,MD5>>
 - <<sha1,SHA1>>

-- <<usage,Usage>>
+- <<sha1:sha1_hmac(),SHA1_HMAC>>
+- <<usage,Common usage>>
+
+<<checksum,Checksums>>:
+- <<crypto:adler,Adler-32>>
+
+<<nocrypto,Non-cryptographic ones>>:
+
+- <<strhash,String & block hashes>>
+- <<inthash,Integer hashes>>
+
+[[crypto]]
+Cryptographic hashes
+--------------------

 
 [[md5]]
 MD5
 
 [[md5]]
 MD5

----
+~~~

 !!ucw/md5.h
 
 [[sha1]]
 SHA1
 !!ucw/md5.h
 
 [[sha1]]
 SHA1

-----
+~~~~

 !!ucw/sha1.h
 
 [[usage]]
 !!ucw/sha1.h
 
 [[usage]]

-Usage
------
+Common usage
+~~~~~~~~~~~~

 
 There are two ways you can use the hashing routines.
 
 
 There are two ways you can use the hashing routines.
 


@@ -45,6 +62,27 @@ There are two ways you can use the hashing routines.
   byte output[MD5_SIZE];
   memcpy(output, md5_final(&c), MD5_SIZE);
 
   byte output[MD5_SIZE];
   memcpy(output, md5_final(&c), MD5_SIZE);
 

-SHA1 has the same interface, so both ways work to it as well.
+SHA1 has the same interface, so the same two ways apply.

 
 See also <<string:mem_to_hex()>>.
 
 See also <<string:mem_to_hex()>>.

+
+[[checksum]]
+Checksums
+---------
+
+Their purpose is checking against random data changes, hardware
+failures and alike. They are not to be used against aimed attacks.
+
+The <<compress:adler,Adler-32 checksum>> is documented in the
+<<compression,compression capter>>.
+
+[[nocrypto]]
+Non-cryptographic hashes
+------------------------
+
+They are usually used to identify values in hash tables.
+
+All these functions expect to be moduled by the size of a hash table.
+The size should be a prime number (it gives better distribution).
+
+!!ucw/hashfunc.h