Merge branch '2.5.x'

[catacomb] / base / ct.h

diff --git a/base/ct.h b/base/ct.h
index 00cecc0..445d889 100644 (file)
--- a/base/ct.h
+++ b/base/ct.h
@@ -36,7 +36,7 @@
 
 #include <mLib/bits.h>
 
-/*----- Functions provided ------------------------------------------------*/
+/*----- Miscellaneous constant-time utilities -----------------------------*/
 
 /* --- @ct_inteq@ --- *
  *
@@ -53,7 +53,7 @@ extern int ct_inteq(uint32 /*x*/, uint32 /*y*/);
  *
  * Arguments:  @uint32 x, y@ = two 32-bit unsigned integers
  *
- * Returns:    One if %$x \le y$% are equal, zero if @x@ is greater.
+ * Returns:    One if %$x \le y$%, zero if @x@ is greater.
  *
  * Use:                Answers whether two integers are ordered, in constant time.
  */
@@ -103,6 +103,44 @@ extern void ct_condcopy(uint32 /*a*/,
 
 extern int ct_memeq(const void */*p*/, const void */*q*/, size_t /*n*/);
 
+/*----- Utilities for testing ---------------------------------------------*/
+
+/* --- @ct_poison@ --- *
+ *
+ * Arguments:  @const void *p@ = pointer to a secret
+ *             @size_t sz@ = size of the secret
+ *
+ * Returns:    ---
+ *
+ * Use:                Ordinarily, does nothing.  If the process is running under
+ *             the control of Valgrind's `memcheck' utility, then mark the
+ *             secret as `uninitialized', so that Valgrind warns about
+ *             conditional execution or memory addressing based on the value
+ *             of the secret.
+ *
+ *             Credit for this idea goes to Adam Langley, who described it
+ *             in https://www.imperialviolet.org/2010/04/01/ctgrind.html,
+ *             though this implementation doesn't require patching Valgrind.
+ */
+
+extern void ct_poison(const void */*p*/, size_t /*sz*/);
+
+/* --- @ct_remedy@ --- *
+ *
+ * Arguments:  @const void *p@ = pointer to a secret
+ *             @size_t sz@ = size of the secret
+ *
+ * Returns:    ---
+ *
+ * Use:                Ordinarily, does nothing.  If the process is running under
+ *             the control of Valgrind's `memcheck' utility, then mark the
+ *             secret as `initialized'.  This is intended to reverse the
+ *             effect of @ct_poison@ so that a test program can verify
+ *             function outputs wihtout Valgrind warning.
+ */
+
+extern void ct_remedy(const void */*p*/, size_t /*sz*/);
+
 /*----- That's all, folks -------------------------------------------------*/
 
 #ifdef __cplusplus