doc: State that gcry_md_write et al may be used after md_read.

--

3 files changed, 23 insertions, 8 deletions

diff --git a/cipher/hash-common.c b/cipher/hash-common.c
index ed63a0ba..9a007e12 100644
--- a/cipher/hash-common.c
+++ b/cipher/hash-common.c
@@ -95,7 +95,10 @@ _gcry_hash_selftest_check_one (int algo,
 
 /* Common function to write a chunk of data to the transform function
    of a hash algorithm.  Note that the use of the term "block" does
-   not imply a fixed size block.  */
+   not imply a fixed size block.  Note that we explicitly allow to use
+   this function after the context has been finalized; the result does
+   not have any meaning but writing after finalize is sometimes
+   helpful to mitigate timing attacks. */
 void
 _gcry_md_block_write (void *context, const void *inbuf_arg, size_t inlen)
 {
diff --git a/cipher/md.c b/cipher/md.c
index f9414def..9fef5559 100644
--- a/cipher/md.c
+++ b/cipher/md.c
@@ -642,6 +642,9 @@ md_write (gcry_md_hd_t a, const void *inbuf, size_t inlen)
 }
 
 
+/* Note that this function may be used after finalize and read to keep
+   on writing to the transform function so to mitigate timing
+   attacks.  */
 void
 _gcry_md_write (gcry_md_hd_t hd, const void *inbuf, size_t inlen)
 {
diff --git a/doc/gcrypt.texi b/doc/gcrypt.texi
index be5f8053..30acd2ff 100644
--- a/doc/gcrypt.texi
+++ b/doc/gcrypt.texi
@@ -3233,7 +3233,11 @@ by just one character.  Both methods can be used on the same hash context.
 
 Pass @var{length} bytes of the data in @var{buffer} to the digest object
 with handle @var{h} to update the digest values. This
-function should be used for large blocks of data.
+function should be used for large blocks of data.  If this function is
+used after the context has been finalized, it will keep on pushing
+the data through the algorithm specific transform function and change
+the context; however the results are not meaningful and this feature
+is only available to mitigate timing attacks.
 @end deftypefun
 
 @deftypefun void gcry_md_putc (gcry_md_hd_t @var{h}, int @var{c})
@@ -3253,7 +3257,9 @@ message digest or some padding.
 Finalize the message digest calculation.  This is not really needed
 because @code{gcry_md_read} does this implicitly.  After this has been
 done no further updates (by means of @code{gcry_md_write} or
-@code{gcry_md_putc} are allowed.  Only the first call to this function
+@code{gcry_md_putc} should be done; However, to mitigate timing
+attacks it is sometimes useful to keep on updating the context after
+having stored away the actual digest.  Only the first call to this function
 has an effect. It is implemented as a macro.
 @end deftypefun
 
@@ -3266,8 +3272,9 @@ function:
 calculation.  This function may be used as often as required but it will
 always return the same value for one handle.  The returned message digest
 is allocated within the message context and therefore valid until the
-handle is released or reseted (using @code{gcry_md_close} or
-@code{gcry_md_reset}.  @var{algo} may be given as 0 to return the only
+handle is released or reset-ed (using @code{gcry_md_close} or
+@code{gcry_md_reset} or it has been updated as a mitigation measure
+against timing attacks.  @var{algo} may be given as 0 to return the only
 enabled message digest or it may specify one of the enabled algorithms.
 The function does return @code{NULL} if the requested algorithm has not
 been enabled.
@@ -3680,10 +3687,13 @@ see how it is actually done.
 @deftypefun gcry_error_t gcry_mac_write (gcry_mac_hd_t @var{h}, const void *@var{buffer}, size_t @var{length})
 
 Pass @var{length} bytes of the data in @var{buffer} to the MAC object
-with handle @var{h} to update the MAC values.
+with handle @var{h} to update the MAC values.  If this function is
+used after the context has been finalized, it will keep on pushing the
+data through the algorithm specific transform function and thereby
+change the context; however the results are not meaningful and this
+feature is only available to mitigate timing attacks.
 @end deftypefun
 
-
 The way to read out the calculated MAC is by using the function:
 
 @deftypefun gcry_error_t gcry_mac_read (gcry_mac_hd_t @var{h}, void *@var{buffer}, size_t *@var{length})
@@ -3694,7 +3704,6 @@ Function copies the resulting MAC value to @var{buffer} of the length
 then length of MAC is returned through @var{length}.
 @end deftypefun
 
-
 To compare existing MAC value with recalculated MAC, one is to use the function:
 
 @deftypefun gcry_error_t gcry_mac_verify (gcry_mac_hd_t @var{h}, void *@var{buffer}, size_t @var{length})