ucw/doc/hash.txt

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