Merge pull request #288 from pq-code-package/cbmc_poly_frombytes

CBMC: Add spec & proof for `poly_frombytes()`

cbmc/proofs/poly_frombytes/Makefile

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: Apache-2.0
+
+include ../Makefile_params.common
+
+HARNESS_ENTRY = harness
+HARNESS_FILE = poly_frombytes_harness
+
+# This should be a unique identifier for this proof, and will appear on the
+# Litani dashboard. It can be human-readable and contain spaces if you wish.
+PROOF_UID = poly_frombytes
+
+DEFINES +=
+INCLUDES +=
+
+REMOVE_FUNCTION_BODY +=
+UNWINDSET +=
+
+PROOF_SOURCES += $(PROOFDIR)/$(HARNESS_FILE).c
+PROJECT_SOURCES += $(SRCDIR)/mlkem/poly.c
+
+CHECK_FUNCTION_CONTRACTS=$(MLKEM_NAMESPACE)poly_frombytes
+USE_FUNCTION_CONTRACTS=
+APPLY_LOOP_CONTRACTS=on
+USE_DYNAMIC_FRAMES=1
+
+# Disable any setting of EXTERNAL_SAT_SOLVER, and choose SMT backend instead
+EXTERNAL_SAT_SOLVER=
+CBMCFLAGS=--bitwuzla
+
+FUNCTION_NAME = $(MLKEM_NAMESPACE)poly_frombytes
+
+# If this proof is found to consume huge amounts of RAM, you can set the
+# EXPENSIVE variable. With new enough versions of the proof tools, this will
+# restrict the number of EXPENSIVE CBMC jobs running at once. See the
+# documentation in Makefile.common under the "Job Pools" heading for details.
+# EXPENSIVE = true
+
+# This function is large enough to need...
+CBMC_OBJECT_BITS = 8
+
+# If you require access to a file-local ("static") function or object to conduct
+# your proof, set the following (and do not include the original source file
+# ("mlkem/poly.c") in PROJECT_SOURCES).
+# REWRITTEN_SOURCES = $(PROOFDIR)/<__SOURCE_FILE_BASENAME__>.i
+# include ../Makefile.common
+# $(PROOFDIR)/<__SOURCE_FILE_BASENAME__>.i_SOURCE = $(SRCDIR)/mlkem/poly.c
+# $(PROOFDIR)/<__SOURCE_FILE_BASENAME__>.i_FUNCTIONS = foo bar
+# $(PROOFDIR)/<__SOURCE_FILE_BASENAME__>.i_OBJECTS = baz
+# Care is required with variables on the left-hand side: REWRITTEN_SOURCES must
+# be set before including Makefile.common, but any use of variables on the
+# left-hand side requires those variables to be defined. Hence, _SOURCE,
+# _FUNCTIONS, _OBJECTS is set after including Makefile.common.
+
+include ../Makefile.common

cbmc/proofs/poly_frombytes/cbmc-proof.txt

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# This file marks this directory as containing a CBMC proof.

cbmc/proofs/poly_frombytes/poly_frombytes_harness.c

@@ -0,0 +1,30 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: MIT-0
+
+/*
+ * Insert copyright notice
+ */
+
+/**
+ * @file poly_frombytes_harness.c
+ * @brief Implements the proof harness for poly_frombytes function.
+ */
+
+/*
+ * Insert project header files that
+ *   - include the declaration of the function
+ *   - include the types needed to declare function arguments
+ */
+#include <poly.h>
+
+/**
+ * @brief Starting point for formal analysis
+ *
+ */
+void harness(void) {
+  poly a;
+  uint8_t r[MLKEM_POLYBYTES];
+
+  /* Contracts for this function are in poly.h */
+  poly_frombytes(&a, r);
+}

mlkem/poly.c

@@ -239,9 +239,6 @@ void poly_tobytes(uint8_t r[MLKEM_POLYBYTES], const poly *a) {
  *
  * Description: De-serialization of a polynomial.
  *
- *              Note that this is not a strict inverse to poly_tobytes() since
- *              the latter includes normalization to unsigned coefficients.
- *
  * Arguments:   INPUT
  *              - a: pointer to input byte array
  *                   (of MLKEM_POLYBYTES bytes)
@@ -251,13 +248,25 @@ void poly_tobytes(uint8_t r[MLKEM_POLYBYTES], const poly *a) {
  *                   0 .. 4095
  **************************************************/
 void poly_frombytes(poly *r, const uint8_t a[MLKEM_POLYBYTES]) {
-  unsigned int i;
-  for (i = 0; i < MLKEM_N / 2; i++) {
-    r->coeffs[2 * i] =
-        ((a[3 * i + 0] >> 0) | ((uint16_t)a[3 * i + 1] << 8)) & 0xFFF;
-    r->coeffs[2 * i + 1] =
-        ((a[3 * i + 1] >> 4) | ((uint16_t)a[3 * i + 2] << 4)) & 0xFFF;
-  }
+  int i;
+  for (i = 0; i < MLKEM_N / 2; i++)
+      // clang-format off
+    ASSIGNS(i, OBJECT_WHOLE(r))
+    INVARIANT(i >= 0 && i <= MLKEM_N / 2)
+    INVARIANT(ARRAY_IN_BOUNDS(int, k, 0, (2 * i - 1), r->coeffs, 0, 4095))
+    DECREASES(MLKEM_N / 2 - i)
+    // clang-format on
+    {
+      // REF-CHANGE: Introduce some locals for better readability
+      const uint8_t t0 = a[3 * i + 0];
+      const uint8_t t1 = a[3 * i + 1];
+      const uint8_t t2 = a[3 * i + 2];
+      r->coeffs[2 * i + 0] = t0 | ((t1 << 8) & 0xFFF);
+      r->coeffs[2 * i + 1] = (t1 >> 4) | (t2 << 4);
+    }
+
+  // Note that the coefficients are not canonical
+  POLY_UBOUND(r, 4096);
 }
 #else  /* MLKEM_USE_NATIVE_POLY_FROMBYTES */
 void poly_frombytes(poly *r, const uint8_t a[MLKEM_POLYBYTES]) {

mlkem/poly.h

@@ -203,7 +203,13 @@ ASSIGNS(OBJECT_WHOLE(r));
 
 
 #define poly_frombytes MLKEM_NAMESPACE(poly_frombytes)
-void poly_frombytes(poly *r, const uint8_t a[MLKEM_POLYBYTES]);
+void poly_frombytes(poly *r, const uint8_t a[MLKEM_POLYBYTES])
+    // clang-format off
+REQUIRES(a != NULL && IS_FRESH(a, MLKEM_POLYBYTES))
+REQUIRES(r != NULL && IS_FRESH(r, sizeof(poly)))
+ASSIGNS(OBJECT_WHOLE(r))
+ENSURES(ARRAY_IN_BOUNDS(int, k, 0, (MLKEM_N - 1), r->coeffs, 0, 4095));
+// clang-format on
 
 #define poly_frommsg MLKEM_NAMESPACE(poly_frommsg)
 void poly_frommsg(poly *r, const uint8_t msg[MLKEM_INDCPA_MSGBYTES]);