[crypto] ML-DSA-87: Secure unmasking gadget

Signed-off-by: Andrea Caforio <andrea.caforio@lowrisc.org>

Author: andrea-caforio

sw/otbn/crypto/mldsa87/mldsa87_gadgets.s

@@ -7,6 +7,7 @@
 .globl sec_a2b_8x32
 .globl sec_b2a_8x32
 .globl sec_add_8x32
+.globl sec_unmask_8x32
 
 /*
 
@@ -133,3 +134,24 @@ sec_add_8x32:
   bn.wsrr w1, MAI_RES_S1
 
   ret
+
+/**
+ * Securely unmask a vector of 8 Boolean-shared coefficients.
+ *
+ * This is an implementation of the `SecUnMask` function (Algorithm 3 in [1]).
+ *
+ * @param[in]  w0: x0_B, first Boolean share of x
+ * @param[in]  w1: x1_B, second Boolean share of x.
+ * @param[out] w0: x, unmasked value x.
+ */
+sec_unmask_8x32:
+  /* Sample a fresh random mask and XOR it to the shares before unmasking. */
+  bn.wsrr w20, RND
+
+  bn.xor w0, w0, w20
+  bn.addi w31, w31, 0 /* dummy */
+  bn.xor w1, w1, w20
+
+  bn.xor w0, w0, w1
+
+  ret

sw/otbn/crypto/mldsa87/tests/BUILD

@@ -36,6 +36,7 @@ unit_tests = [
     "mldsa87_sec_a2b_test",
     "mldsa87_sec_b2a_test",
     "mldsa87_sec_add_test",
+    "mldsa87_sec_unmask_test",
 ]
 
 [

sw/otbn/crypto/mldsa87/tests/mldsa87_sec_unmask_test.hjson

@@ -0,0 +1,12 @@
+// Copyright lowRISC contributors (OpenTitan project).
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+{
+  "entrypoint": "main",
+  "output": {
+    "regs": {
+      "w2": "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
+    }
+  }
+}

sw/otbn/crypto/mldsa87/tests/mldsa87_sec_unmask_test.s

@@ -0,0 +1,54 @@
+/* Copyright lowRISC contributors (OpenTitan project). */
+/* Licensed under the Apache License, Version 2.0, see LICENSE for details. */
+/* SPDX-License-Identifier: Apache-2.0 */
+
+/* Randomized test to verify the secure addition. */
+
+.section .text.start
+
+main:
+  la x31, _stack
+  bn.xor w31, w31, w31
+
+  la x2, _params
+  bn.lid x0, 0(x2)
+  bn.wsrw MOD, w0
+
+  bn.not w2, w31 /* flag */
+
+  /* Generate 100 random Boolean-shared vectors and verify that they can be
+     correctly unmasked. */
+  loopi 100, 7
+    /* Random vectors x and y. */
+    bn.wsrr w3, URND
+
+    /* Random masks. */
+    bn.wsrr w4, URND
+
+    /* Create the two Boolean shares and trigger the conversion. */
+    bn.xor w0, w3, w4
+    bn.mov w1, w4
+    jal x1, sec_unmask_8x32
+
+    /* Check that the unmask result is equal to the initial vector. */
+    bn.cmp w0, w3, FG0
+    bn.sel w2, w2, w31, FG0.Z
+    /* End of loop */
+
+  ecall
+
+.data
+.balign 32
+
+_params:
+.word 0x007fe001 /* q */
+.word 0xfc7fdfff /* mu */
+.word 0x0000a3fa /* n^-1 * R^3 mod q */
+.word 0x00000000
+.word 0x00000000
+.word 0x00000000
+.word 0x00000000
+.word 0x00000000
+
+_stack:
+.zero 4