CT: Improve documentation and add MLD_CONFIG_NO_ASM_VALUE_BARRIER to config.h

Signed-off-by: Matthias J. Kannwischer <[email protected]>

Author: mkannwischer

mldsa/config.h

@@ -179,5 +179,20 @@
  *****************************************************************************/
 /* #define MLD_CONFIG_NO_ASM */
 
+/******************************************************************************
+ * Name:        MLD_CONFIG_NO_ASM_VALUE_BARRIER
+ *
+ * Description: If this option is set, mldsa-native will be built without
+ *              use of native code or inline assembly for value barriers.
+ *
+ *              By default, inline assembly (if available) is used to implement
+ *              value barriers.
+ *              Without inline assembly, mldsa-native will use a global volatile
+ *              'opt blocker' instead; see ct.h.
+ *
+ *****************************************************************************/
+/* #define MLD_CONFIG_NO_ASM_VALUE_BARRIER */
+
+
 
 #endif /* !MLD_CONFIG_H */

mldsa/ct.h

@@ -3,15 +3,60 @@
  * Copyright (c) The mldsa-native project authors
  * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
  */
+
 #ifndef MLD_CT_H
 #define MLD_CT_H
 
+/* References
+ * ==========
+ *
+ * - [libmceliece]
+ *   libmceliece implementation of Classic McEliece
+ *   Bernstein, Chou
+ *   https://lib.mceliece.org/
+ *
+ * - [optblocker]
+ *   PQC forum post on opt-blockers using volatile globals
+ *   Daniel J. Bernstein
+ *   https://groups.google.com/a/list.nist.gov/g/pqc-forum/c/hqbtIGFKIpU/m/H14H0wOlBgAJ
+ */
+
 #include <stdint.h>
 #include "cbmc.h"
 #include "common.h"
 
-/* TODO: add documentation here */
-/* TODO: add MLD_CONFIG_NO_ASM_VALUE_BARRIER to config.h */
+/* Constant-time comparisons and conditional operations
+
+   We reduce the risk for compilation into variable-time code
+   through the use of 'value barriers'.
+
+   Functionally, a value barrier is a no-op. To the compiler, however,
+   it constitutes an arbitrary modification of its input, and therefore
+   harden's value propagation and range analysis.
+
+   We consider two approaches to implement a value barrier:
+   - An empty inline asm block which marks the target value as clobbered.
+   - XOR'ing with the value of a volatile global that's set to 0;
+     see @[optblocker] for a discussion of this idea, and
+     @[libmceliece, inttypes/crypto_intN.h] for an implementation.
+
+   The first approach is cheap because it only prevents the compiler
+   from reasoning about the value of the variable past the barrier,
+   but does not directly generate additional instructions.
+
+   The second approach generates redundant loads and XOR operations
+   and therefore comes at a higher runtime cost. However, it appears
+   more robust towards optimization, as compilers should never drop
+   a volatile load.
+
+   We use the empty-ASM value barrier for GCC and clang, and fall
+   back to the global volatile barrier otherwise.
+
+   The global value barrier can be forced by setting
+   MLD_CONFIG_NO_ASM_VALUE_BARRIER.
+
+*/
+
 #if defined(MLD_HAVE_INLINE_ASM) && !defined(MLD_CONFIG_NO_ASM_VALUE_BARRIER)
 #define MLD_USE_ASM_VALUE_BARRIER
 #endif