# Rules for documentation
-$(o)/%.html: $(o)/%.txt
+$(o)/%.html: $(o)/%.txt $(s)/build/asciidoc.conf $(s)/build/asciidoc-xhtml.conf
$(M)"DOC-HTML $<"
$(Q)asciidoc -e -f $(s)/build/asciidoc.conf -f $(s)/build/asciidoc-xhtml.conf -f /etc/asciidoc/asciidoc.conf -f /etc/asciidoc/xhtml11.conf $<
# In reality, we do not depend on the .txt files, but on the corresponding .deflist's.
# However, the Makefile language cannot express that doc-extract generates both .txt
# and .deflist, so we always use the .txt's in dependencies.
-$(patsubst %.html,%.txt,$(DOC_INDICES)): $(o)/%.txt: $(patsubst %.html,%.txt,$(DOCS))
+$(patsubst %.html,%.txt,$(DOC_INDICES)): $(o)/%.txt: $(patsubst %.html,%.txt,$(DOCS)) $(s)/build/doc-defs
$(M)"DOC-DEFS $@"
$(Q)echo $@: $(DOC_HEAD) $(DOC_LIST) >> $(o)/depend.new
$(Q)$(s)/build/doc-defs $(DOC_HEAD) $@ $(DOC_LIST)
-$(patsubst %.html,%.txt,$(DOCS)): $(o)/%.txt: $(s)/%.txt
+$(patsubst %.html,%.txt,$(DOCS)): $(o)/%.txt: $(s)/%.txt $(s)/build/doc-extract
$(M)"DOC-EXT $<"
$(Q)$(s)/build/doc-extract $< $@ $(o)/depend.new $(s) $(patsubst %.txt,%.deflist,$@)
================
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
---
!!ucw/sha1.h
[[usage]]
-Usage
------
+Common usage
+------------
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
#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
* 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
* @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);
sha1_init(&hd);
sha1_update(&hd, buffer, length);
- memcpy(outbuf, sha1_final(&hd), 20);
+ memcpy(outbuf, sha1_final(&hd), SHA1_SIZE);
}
#ifdef TEST
* 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);