From e7e04f5fcf194ad5ff00709de2432c294ce6c0d1 Mon Sep 17 00:00:00 2001 From: rasky Date: Fri, 24 Sep 2010 17:08:18 +0000 Subject: [PATCH] SEC: add some documentation to the interface. git-svn-id: https://src.develer.com/svnoss/bertos/trunk@4307 38d2e660-2303-0410-9eaa-f027e97ec537 --- bertos/sec/hash.h | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/bertos/sec/hash.h b/bertos/sec/hash.h index 4601e7ef..937111c2 100644 --- a/bertos/sec/hash.h +++ b/bertos/sec/hash.h @@ -50,29 +50,54 @@ typedef struct Hash uint8_t block_len; } Hash; +/** + * Initialize a hash computation. + */ INLINE void hash_begin(Hash *h) { ASSERT(h->begin); h->begin(h); } +/** + * Add some data to the computation. + */ INLINE void hash_update(Hash *h, const void* data, size_t len) { ASSERT(h->update); h->update(h, data, len); } +/** + * Finalize the hash computation and return the digest. + * + * \note This function must be called exactly once per each computation. + * Calling it twice leads to undefined behaviour. + * + * \note The pointer returned is within the hash context structure \a h, so it + * has the same lifetime as the hash instance. The data will be invalidated + * as soon as \a hash_begin is called again on the same instance. + */ INLINE uint8_t* hash_final(Hash *h) { ASSERT(h->final); return h->final(h); } +/** + * Return the digest length in bytes. + */ INLINE int hash_digest_len(Hash *h) { return h->digest_len; } +/* + * Return the internal block length in bytes. + * + * Hash functions operate on a fixed-size block. This information is useful + * for composite functions like HMAC to adjust their internal operations. + */ INLINE int hash_block_len(Hash *h) { return h->block_len; -- 2.25.1