From: Michal Vaner <vorner@ucw.cz>
Date: Sat, 13 Sep 2008 10:01:58 +0000 (+0200)
Subject: ucw docs: more hash functions
X-Git-Tag: holmes-import~307
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=b5b7b2641b00a18b53c48a1335846133f1d53168;p=libucw.git

ucw docs: more hash functions

I will add more when I find where they live
---

diff --git a/ucw/doc/hash.txt b/ucw/doc/hash.txt
index 22459c1c..bac3b9c9 100644
--- a/ucw/doc/hash.txt
+++ b/ucw/doc/hash.txt
@@ -2,12 +2,24 @@ Hashing routines
 ================
 
 Libucw contains two cryptographic hash algorithms: MD5 (RFC 1321) and SHA1 (RFC
-3174).
+3174). A SHA1-HMAC (RFC 2104) message authentication is available.
+
+There are non-cryptographic hashes as well.
+
+Cryptographic ones
+------------------
 
 - <<md5,MD5>>
 - <<sha1,SHA1>>
+- <<sha1:sha1_hmac(),SHA1_HMAC>>
 - <<usage,Common usage>>
 
+Non-cryptographic ones
+----------------------
+
+- <<strhash,String & block hashes>>
+- <<inthash,Integer hashes>>
+
 [[md5]]
 MD5
 ---
@@ -19,8 +31,8 @@ SHA1
 !!ucw/sha1.h
 
 [[usage]]
-Usage
------
+Common usage
+------------
 
 There are two ways you can use the hashing routines.
 
@@ -48,3 +60,5 @@ There are two ways you can use the hashing routines.
 SHA1 has the same interface, so the same two ways apply.
 
 See also <<string:mem_to_hex()>>.
+
+!!ucw/hashfunc.h
diff --git a/ucw/hashfunc.h b/ucw/hashfunc.h
index 49572882..b67321c1 100644
--- a/ucw/hashfunc.h
+++ b/ucw/hashfunc.h
@@ -13,22 +13,26 @@
 
 #include "ucw/lib.h"
 
+/*** == String hashes [[strhash]] ***/
+
 /* The following functions need str to be aligned to uns.  */
-uns str_len_aligned(const char *str) PURE;
-uns hash_string_aligned(const char *str) PURE;
-uns hash_block_aligned(const byte *str, uns len) PURE;
+uns str_len_aligned(const char *str) PURE; /** Get the string length (actually hash function too). The string must be aligned to uns. For unaligned see str_len(). **/
+uns hash_string_aligned(const char *str) PURE; /** Hash the string. The string must be aligned to uns. For unaligned see hash_string(). **/
+uns hash_block_aligned(const byte *str, uns len) PURE; /** Hash arbitrary data. They must be aligned to uns. For unaligned see hash_block(). **/
 
 #ifdef	CPU_ALLOW_UNALIGNED
 #define	str_len(str)		str_len_aligned(str)
 #define	hash_string(str)	hash_string_aligned(str)
 #define	hash_block(str, len)	hash_block_aligned(str, len)
 #else
-uns str_len(const char *str) PURE;
-uns hash_string(const char *str) PURE;
-uns hash_block(const byte *str, uns len) PURE;
+uns str_len(const char *str) PURE; /** Get the string length (actually a hash function too). If you know it is aligned to uns, you can use faster str_len_aligned(). **/
+uns hash_string(const char *str) PURE; /** Hash the string. If it is aligned to uns, you can use faster hash_string_aligned(). **/
+uns hash_block(const byte *str, uns len) PURE; /** Hash arbitrary data. If they are aligned to uns, use faster hash_block_aligned(). **/
 #endif
 
-uns hash_string_nocase(const char *str) PURE;
+uns hash_string_nocase(const char *str) PURE; /** Hash the string in a case insensitive way. **/
+
+/*** == Integer hashes [[inthash]] ***/
 
 /*
  *  We hash integers by multiplying by a reasonably large prime with
@@ -36,8 +40,8 @@ uns hash_string_nocase(const char *str) PURE;
  *  of using shifts and adds on architectures where multiplication
  *  instructions are slow).
  */
-static inline uns CONST hash_u32(uns x) { return 0x01008041*x; }
-static inline uns CONST hash_u64(u64 x) { return hash_u32((uns)x ^ (uns)(x >> 32)); }
-static inline uns CONST hash_pointer(void *x) { return ((sizeof(x) <= 4) ? hash_u32((uns)(uintptr_t)x) : hash_u64((u64)(uintptr_t)x)); }
+static inline uns CONST hash_u32(uns x) { return 0x01008041*x; } /** Hash a 32 bit unsigned integer. **/
+static inline uns CONST hash_u64(u64 x) { return hash_u32((uns)x ^ (uns)(x >> 32)); } /** Hash a 64 bit unsigned integer. **/
+static inline uns CONST hash_pointer(void *x) { return ((sizeof(x) <= 4) ? hash_u32((uns)(uintptr_t)x) : hash_u64((u64)(uintptr_t)x)); } /** Hash a pointer. **/
 
 #endif
diff --git a/ucw/md5.h b/ucw/md5.h
index 400c8752..6980a1f9 100644
--- a/ucw/md5.h
+++ b/ucw/md5.h
@@ -52,6 +52,7 @@ void md5_transform(u32 buf[4], const u32 in[16]);
  * @buffer, creates the hash from them and returns it in @output.
  *
  * It is equivalent to this code:
+ *
  *  md5_context c;
  *  md5_init(&c);
  *  md5_update(&c, buffer, length);
diff --git a/ucw/sha1.c b/ucw/sha1.c
index 304cbabc..5a547cbb 100644
--- a/ucw/sha1.c
+++ b/ucw/sha1.c
@@ -281,7 +281,7 @@ sha1_hash_buffer(byte *outbuf, const byte *buffer, uns length)
 
   sha1_init(&hd);
   sha1_update(&hd, buffer, length);
-  memcpy(outbuf, sha1_final(&hd), 20);
+  memcpy(outbuf, sha1_final(&hd), SHA1_SIZE);
 }
 
 #ifdef TEST
diff --git a/ucw/sha1.h b/ucw/sha1.h
index ce8fca32..55809ee0 100644
--- a/ucw/sha1.h
+++ b/ucw/sha1.h
@@ -53,7 +53,7 @@ byte *sha1_final(sha1_context *hd);
  *  sha1_context hd;
  *  sha1_init(&hd);
  *  sha1_update(&hd, buffer, length);
- *  memcpy(outbuf, sha1_final(&hd), 20);
+ *  memcpy(outbuf, sha1_final(&hd), SHA1_SIZE);
  */
 void sha1_hash_buffer(byte *outbuf, const byte *buffer, uns length);