improve mem_neq() documentation

Author: sjaeckel

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

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)
 {