From ae698927ff34687b2328e32416138ccc1dcef9c4 Mon Sep 17 00:00:00 2001
From: Steffen Jaeckel <s@jaeckel.eu>
Date: Wed, 21 Jun 2017 14:39:08 +0200
Subject: [PATCH] improve `mem_neq()` documentation

---
 src/headers/tomcrypt_custom.h |  3 +++
 src/misc/mem_neq.c            | 11 ++++++++---
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/headers/tomcrypt_custom.h b/src/headers/tomcrypt_custom.h
index 344b0d2..cc63b08 100644
--- a/src/headers/tomcrypt_custom.h
+++ b/src/headers/tomcrypt_custom.h
@@ -33,6 +33,9 @@
 #ifndef XMEMCMP
 #define XMEMCMP  memcmp
 #endif
+/* A memory compare function that has to run in constant time,
+ * c.f. mem_neq() API summary.
+ */
 #ifndef XMEM_NEQ
 #define XMEM_NEQ  mem_neq
 #endif
diff --git a/src/misc/mem_neq.c b/src/misc/mem_neq.c
index e20fd33..fbd0cce 100644
--- a/src/misc/mem_neq.c
+++ b/src/misc/mem_neq.c
@@ -10,22 +10,27 @@
 
 /**
    @file mem_neq.c
-   Compare two blocks of memory for inequality.
+   Compare two blocks of memory for inequality in constant time.
    Steffen Jaeckel
 */
 
 /**
-   Compare two blocks of memory for inequality.
+   Compare two blocks of memory for inequality in constant time.
 
    The usage is similar to that of standard memcmp, but you can only test
    if the memory is equal or not - you can not determine by how much the
    first different byte differs.
 
+   This function shall be used to compare results of cryptographic
+   operations where inequality means most likely usage of a wrong key.
+   The execution time has therefore to be constant as otherwise
+   timing attacks could be possible.
+
    @param a     The first memory region
    @param b     The second memory region
    @param len   The length of the area to compare (octets)
 
-   @return 0 when a and b are equal for len bytes, else they are not equal.
+   @return 0 when a and b are equal for len bytes, 1 they are not equal.
 */
 int mem_neq(const void *a, const void *b, size_t len)
 {