Section on constant-flow testing

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

Author: gilles-peskine-arm

kb/development/test_suites.md

@@ -256,6 +256,19 @@ In a test case that uses PSA crypto only when building with `MBEDTLS_USE_PSA_CRY
 
 See [`<test/psa_crypto_helpers.h>`](https://github.com/Mbed-TLS/mbedtls-framework/blob/development/tests/include/test/psa_crypto_helpers.h) for more complex cases.
 
+### Constant-flow testing
+
+We run some tests with [MemorySanitizer (MSan)](https://github.com/google/sanitizers/wiki/memorysanitizer) and [Valgrind](https://valgrind.org/docs/manual/mc-manual.html) configured to detect secret-dependent control flow: branches or memory addresses computed from secret data. These tests detect library code that could leak secret data through timing side channels to local attackers via shared hardware components such as a memory cache or a branch predictor. We refer to such tests as “constant-time” or more accurately “constant-flow” testing.
+
+Constant-flow testing was added relatively recently in the history of the project, and many functions that should be constant-flow are not tested. However, constant-flow testing is preferred when writing new code that claims to be constant-flow, and especially when fixing a timing side channel.
+
+In unit tests, use the following macros, from [`<test/constant_flow.h>`](https://github.com/Mbed-TLS/mbedtls-framework/blob/main/tests/include/test/constant_flow.h):
+
+* `TEST_CF_SECRET(buffer, size)`: marks the given buffer as secret. Call this on keys, plaintext and other confidential data before passing it to library functions.
+* `TEST_CF_PUBLIC(buffer, size)`: marks the given buffer as public. Call this on outputs before testing their content.
+
+Note that you need to call `TEST_CF_PUBLIC` before `TEST_MEMORY_COMPARE`. However, it is not needed with scalar comparison assertions (`TEST_EQUAL`, etc.), which make a public copy of its argument before comparing them.
+
 ## Guidance on writing unit test data
 
 ### Document the test data

kb/testing/testing-constant-flow.md

@@ -1,5 +1,7 @@
 # Tools for testing constant-flow code
 
+*This document is an investigation into test tooling. For usage in Mbed TLS and TF-PSA-Crypto unit tests, see “[Mbed TLS test guidelines — Constant-flow testing](../development/test_suites.md#constant-flow-testing)”.*
+
 Code that manipulates secret values (private keys, etc.) needs to be constant-flow (often called constant-time, though the requirements are actually stricter than "the total running time is a constant"), that is contain no branches that depend on secret values, and no memory accesses at addresses depending on a secret value, in order to avoid leaking the secret value through side channels.
 
 Ideally, this should not only be enforced by code review, but also tested or checked by tools. This pages list some available options.