ucw/doc/hash.txt

   1 Hashing routines
   2 ================
   3
   4 LibUCW contains implementations of several hash algorithms.
   5
   6 <<crypto,Cryptographic hashes>>:
   7
   8 - <<md5,MD5>> (RFC 1321)
   9 - <<sha1,SHA1>> (RFC 3174)
  10 - <<hash:sha1_hmac(),SHA1_HMAC message authentication>> (RFC 2104)
  11 - <<usage,Common usage>>
  12
  13 <<checksum,Checksums>>:
  14
  15 - <<crypto:adler,Adler-32>>
  16 - <<crc,CRC>>
  17
  18 <<nocrypto,Non-cryptographic hashes>>:
  19
  20 - <<strhash,String & block hashes>>
  21 - <<inthash,Integer hashes>>
  22
  23 [[crypto]]
  24 Cryptographic hashes
  25 --------------------
  26
  27 [[md5]]
  28 MD5
  29 ~~~
  30 !!ucw/md5.h
  31
  32 [[sha1]]
  33 SHA1
  34 ~~~~
  35 !!ucw/sha1.h
  36
  37 [[usage]]
  38 Common usage
  39 ~~~~~~~~~~~~
  40
  41 There are two ways you can use the hashing routines.
  42
  43 - Single-shot interface. If you have an in-memory buffer of the whole
  44   message you want to hash, you can use this.
  45
  46   char *message = "Hello world";
  47   byte output[MD5_SIZE];
  48   md5_hash_buffer(output, message, strlen(message));
  49
  50 - Multi-shot interface. If you have the message scattered in many
  51   buffers or you get it by parts, you do not need to concatenate the
  52   parts together.
  53
  54   byte buffer[MAX_BUFFER];
  55   uint buffer_len;
  56   md5_context c;
  57   md5_init(&c);
  58   while(buffer_len = get_chunk(buffer, MAX_BUFFER)) {
  59     md5_update(&c, buffer, buffer_len);
  60   }
  61   byte output[MD5_SIZE];
  62   memcpy(output, md5_final(&c), MD5_SIZE);
  63
  64 SHA1 has the same interface, so the same two ways apply.
  65
  66 See also <<string:mem_to_hex()>>.
  67
  68 [[checksum]]
  69 Checksums
  70 ---------
  71
  72 Their purpose is checking against random data changes, hardware
  73 failures and alike. They are not to be used against aimed attacks.
  74
  75 Adler-32
  76 ~~~~~~~~
  77
  78 The <<compress:adler,Adler-32 checksum>> is documented in the
  79 <<compress:,compression capter>>.
  80
  81 CRC-32
  82 ~~~~~~
  83
  84 32-bit Cyclic Redundancy Check with the polynomial suggested by
  85 Castagnoli et al.: Optimization of Cyclic Redundancy-Check Codes
  86 with 24 and 32 Parity Bits", IEEE Trans. on Communications, Vol. 41,
  87 No. 6, 1993.
  88
  89 The interface is similar to the one we use for the cryptographic hashes.
  90
  91 !!ucw/crc.h
  92
  93 [[nocrypto]]
  94 Non-cryptographic hashes
  95 ------------------------
  96
  97 They are usually used to identify values in hash tables.
  98
  99 All these functions expect to be moduled by the size of a hash table.
 100 The size should be a prime number (it gives better distribution).
 101
 102 !!ucw/hashfunc.h