md: Add function gcry_md_hash_buffers.

* src/gcrypt.h.in (gcry_buffer_t): new.
(gcry_md_hash_buffers): New.
* src/visibility.c, src/visibility.h: Add wrapper for new function.
* src/libgcrypt.def, src/libgcrypt.vers: Export new function.
* cipher/md.c (gcry_md_hash_buffers): New.
* cipher/sha1.c (_gcry_sha1_hash_buffers): New.
* tests/basic.c (check_one_md_multi): New.
(check_digests): Run that test.
* tests/hmac.c (check_hmac_multi): New.
(main): Run that test.

Signed-off-by: Werner Koch <wk@gnupg.org>

1 files changed, 59 insertions, 4 deletions

diff --git a/doc/gcrypt.texi b/doc/gcrypt.texi
index 09501f06..afef7f76 100644
--- a/doc/gcrypt.texi
+++ b/doc/gcrypt.texi
@@ -3115,8 +3115,36 @@ The function does return @code{NULL} if the requested algorithm has not
 been enabled.
 @end deftypefun
 
-Because it is often necessary to get the message digest of one block of
-memory, a fast convenience function is available for this task:
+Because it is often necessary to get the message digest of blocks of
+memory, two fast convenience function are available for this task:
+
+@deftypefun gpg_err_code_t gcry_md_hash_buffers ( @
+  @w{int @var{algo}}, @w{unsigned int @var{flags}}, @
+  @w{void *@var{digest}}, @
+  @w{const gcry_buffer_t *@var{iov}}, @w{int @var{iovcnt}} )
+
+@code{gcry_md_hash_buffers} is a shortcut function to calculate a
+message digest from several buffers.  This function does not require a
+context and immediately returns the message digest of of the data
+described by @var{iov} and @var{iovcnt}.  @var{digest} must be
+allocated by the caller, large enough to hold the message digest
+yielded by the the specified algorithm @var{algo}.  This required size
+may be obtained by using the function @code{gcry_md_get_algo_dlen}.
+
+@var{iov} is an array of buffer descriptions with @var{iovcnt} items.
+The caller should zero out the structures in this array and for each
+array item set the fields @code{.data} to the address of the data to
+be hashed, @code{.len} to number of bytes to be hashed.  If @var{.off}
+is also set, the data is taken starting at @var{.off} bytes from the
+begin of the buffer.  The field @code{.size} is not used.
+
+The only supported flag value for @var{flags} is
+@var{GCRY_MD_FLAG_HMAC} which turns this function into a HMAC
+function; the first item in @var{iov} is then used as the key.
+
+On success the function returns 0 and stores the resulting hash or MAC
+at @var{digest}.
+@end deftypefun
 
 @deftypefun void gcry_md_hash_buffer (int @var{algo}, void *@var{digest}, const void *@var{buffer}, size_t @var{length});
 
@@ -3128,8 +3156,8 @@ enough to hold the message digest yielded by the the specified algorithm
 @var{algo}.  This required size may be obtained by using the function
 @code{gcry_md_get_algo_dlen}.
 
-Note that this function will abort the process if an unavailable
-algorithm is used.
+Note that in contrast to @code{gcry_md_hash_buffers} this function
+will abort the process if an unavailable algorithm is used.
 @end deftypefun
 
 @c ***********************************
@@ -4359,8 +4387,10 @@ wrong.
 @menu
 * Memory allocation::   Functions related with memory allocation.
 * Context management::  Functions related with context management.
+* Buffer description::  A data type to describe buffers.
 @end menu
 
+
 @node Memory allocation
 @section Memory allocation
 
@@ -4418,6 +4448,31 @@ Release the context object @var{ctx} and all associated resources.  A
 @code{NULL} passed as @var{ctx} is ignored.
 @end deftypefun
 
+@node Buffer description
+@section Buffer description
+
+To help hashing non-contiguous areas of memory a general purpose data
+type is defined:
+
+@deftp {Data type} {gcry_buffer_t}
+This type is a structure to describe a buffer.  The user should make
+sure that this structure is initialized to zero.  The available fields
+of this structure are:
+
+@table @code
+  @item .size
+  This is either 0 for no information available or indicates the
+  allocated length of the buffer.
+  @item .off
+  This is the offset into the buffer.
+  @item .len
+  This is the valid length of the buffer starting at @code{.off}.
+  @item .data
+  This is the address of the buffer.
+  @end table
+@end deftp
+
+
 
 @c **********************************************************
 @c *********************  Tools  ****************************