[crypto/mldsa] Cryptolib implementation of ML-DSA-87 sign

andrea-caforio · andrea-caforio · commit 3da164c2288d · 2026-07-14T07:26:57.000Z
The FIPS-compliant implementation of the FIPS-204 signature generation
function with pure/pre-hash modes and random/deterministic signing. To
thwart FI attacks, sign is executed twice (only the successful
rejection loop in the second run).

Signed-off-by: Andrea Caforio &lt;andrea.caforio@lowrisc.org&gt;
diff --git a/sw/device/lib/crypto/impl/mldsa.c b/sw/device/lib/crypto/impl/mldsa.c
@@ -28,6 +28,9 @@ enum {
   kOtCryptoMldsaBufferWords = kOtCryptoMldsaBufferBytes / sizeof(uint32_t),
   // Maximum size of a pre-hash message digest.
   kOtcryptoMldsaPhMaxWords = 16,
+  // Size of the rnd string.
+  kOtcryptoMldsaRndBytes = 32,
+  kOtcryptoMldsaRndWords = kOtcryptoMldsaRndBytes / sizeof(uint32_t),
 };
 
 // Lookup table for the supported pre-hash functions, indexed by their OID.
@@ -81,6 +84,24 @@ static otcrypto_status_t check_unblinded_key(
   return OTCRYPTO_OK;
 }
 
+// Check the integrity and length of a blinded key.
+static otcrypto_status_t check_blinded_key(const otcrypto_blinded_key_t *key) {
+  // Integrity check.
+  if (launder32(otcrypto_integrity_blinded_key_check(key)) !=
+      kHardenedBoolTrue) {
+    return OTCRYPTO_BAD_ARGS;
+  }
+  HARDENED_CHECK_EQ(otcrypto_integrity_blinded_key_check(key),
+                    kHardenedBoolTrue);
+
+  // Length check.
+  if (key->keyblob_length != kOtcryptoMldsa87SkBytes) {
+    return OTCRYPTO_BAD_ARGS;
+  }
+  HARDENED_CHECK_EQ(key->keyblob_length, kOtcryptoMldsa87SkBytes);
+  return OTCRYPTO_OK;
+}
+
 // Check the integrity and length of a constant byte buffer.
 static otcrypto_status_t check_byte_buf(const otcrypto_const_byte_buf_t *buf,
                                         size_t max_len) {
@@ -233,11 +254,15 @@ otcrypto_status_t otcrypto_mldsa87_keygen(
 
 otcrypto_status_t otcrypto_mldsa87_sign(
     const otcrypto_blinded_key_t *private_key,
-    const otcrypto_const_byte_buf_t message,
-    const otcrypto_const_byte_buf_t context,
-    otcrypto_mldsa_hash_mode_t hash_mode, otcrypto_word32_buf_t signature) {
-  // TODO: Connect ML-DSA operations to API.
-  return OTCRYPTO_NOT_IMPLEMENTED;
+    const otcrypto_const_byte_buf_t *message,
+    const otcrypto_const_byte_buf_t *context,
+    otcrypto_mldsa_hash_mode_t hash_mode, otcrypto_mldsa_sign_mode_t sign_mode,
+    otcrypto_word32_buf_t *signature) {
+  HARDENED_TRY(otcrypto_mldsa87_sign_async_start(private_key, message, context,
+                                                 hash_mode, sign_mode));
+  HARDENED_TRY(otcrypto_mldsa87_double_sign_async_finalize(signature));
+
+  return OTCRYPTO_OK;
 }
 
 otcrypto_status_t otcrypto_mldsa87_verify(
@@ -276,20 +301,76 @@ otcrypto_status_t otcrypto_mldsa87_keygen_async_finalize(
 
 otcrypto_status_t otcrypto_mldsa87_sign_async_start(
     const otcrypto_blinded_key_t *private_key,
-    const otcrypto_const_byte_buf_t message,
-    const otcrypto_const_byte_buf_t context,
-    otcrypto_mldsa_hash_mode_t hash_mode, otcrypto_word32_buf_t signature) {
-  // TODO: Connect ML-DSA operations to API.
-  return OTCRYPTO_NOT_IMPLEMENTED;
+    const otcrypto_const_byte_buf_t *message,
+    const otcrypto_const_byte_buf_t *context,
+    otcrypto_mldsa_hash_mode_t hash_mode,
+    otcrypto_mldsa_sign_mode_t sign_mode) {
+#ifndef OTCRYPTO_DISABLE_NULL_CHECKS
+  if (private_key == NULL || private_key->keyblob == NULL || message == NULL ||
+      context == NULL) {
+    return OTCRYPTO_BAD_ARGS;
+  }
+#endif
+
+  // Check the integrity and length of the input buffers.
+  HARDENED_TRY(check_blinded_key(private_key));
+  HARDENED_TRY(check_byte_buf(context, kOtcryptoMldsa87CtxMaxBytes));
+  HARDENED_TRY(check_byte_buf(message, kOtcryptoMldsa87MsgMaxBytes));
+
+  // Allocate the 64-byte mu digest.
+  uint32_t mu_data[kOtcryptoMldsaMuWords] = {0};
+  otcrypto_hash_digest_t mu = {
+      .data = mu_data,
+      .len = kOtcryptoMldsaMuWords,
+  };
+
+  // Extract tr from the secret key.
+  otcrypto_hash_digest_t tr = {
+      .data = private_key->keyblob + 24,
+      .len = kOtcryptoMldsaTrWords,
+  };
+
+  // mu = Shake256(tr || M').
+  HARDENED_TRY(compute_mu(&tr, context, message, hash_mode, &mu));
+
+  // Invoke the signature generation OTBN app.
+  HARDENED_TRY_WIPE_DMEM(
+      mldsa87_sign_internal_start(private_key, &mu, sign_mode));
+
+  // Check the buffers again before exiting.
+  HARDENED_TRY(check_blinded_key(private_key));
+  HARDENED_TRY(check_byte_buf(context, kOtcryptoMldsa87CtxMaxBytes));
+  HARDENED_TRY(check_byte_buf(message, kOtcryptoMldsa87MsgMaxBytes));
+
+  return otcrypto_eval_exit(OTCRYPTO_OK);
 }
 
 otcrypto_status_t otcrypto_mldsa87_sign_async_finalize(
-    const otcrypto_blinded_key_t *private_key,
-    const otcrypto_const_byte_buf_t message,
-    const otcrypto_const_byte_buf_t context,
-    otcrypto_mldsa_hash_mode_t hash_mode, otcrypto_word32_buf_t signature) {
-  // TODO: Connect ML-DSA operations to API.
-  return OTCRYPTO_NOT_IMPLEMENTED;
+    otcrypto_word32_buf_t *signature) {
+#ifndef OTCRYPTO_DISABLE_NULL_CHECKS
+  if (signature == NULL || signature->data == NULL) {
+    return OTCRYPTO_BAD_ARGS;
+  }
+#endif
+
+  HARDENED_TRY_WIPE_DMEM(
+      mldsa87_sign_internal_finalize(signature, kMldsa87SingleSign));
+
+  return otcrypto_eval_exit(OTCRYPTO_OK);
+}
+
+otcrypto_status_t otcrypto_mldsa87_double_sign_async_finalize(
+    otcrypto_word32_buf_t *signature) {
+#ifndef OTCRYPTO_DISABLE_NULL_CHECKS
+  if (signature == NULL || signature->data == NULL) {
+    return OTCRYPTO_BAD_ARGS;
+  }
+#endif
+
+  HARDENED_TRY_WIPE_DMEM(
+      mldsa87_sign_internal_finalize(signature, kMldsa87DoubleSign));
+
+  return otcrypto_eval_exit(OTCRYPTO_OK);
 }
 
 otcrypto_status_t otcrypto_mldsa87_verify_async_start(
@@ -358,8 +439,10 @@ otcrypto_status_t otcrypto_mldsa87_verify_async_finalize(
 
   HARDENED_TRY(check_word32_buf(signature, kOtcryptoMldsa87SigWords));
 
-  return otcrypto_eval_exit(
+  HARDENED_TRY_WIPE_DMEM(
       mldsa87_verify_internal_finalize(signature, verification_result));
+
+  return otcrypto_eval_exit(OTCRYPTO_OK);
 }
 
 otcrypto_status_t otcrypto_mldsa87_keycheck_async_start(
diff --git a/sw/device/lib/crypto/impl/mldsa/BUILD b/sw/device/lib/crypto/impl/mldsa/BUILD
@@ -16,6 +16,7 @@ cc_library(
         "//sw/device/lib/base:hardened_memory",
         "//sw/device/lib/crypto/drivers:otbn",
         "//sw/device/lib/crypto/impl:status",
+        "//sw/otbn/crypto/mldsa87/sign:mldsa87_sign",
         "//sw/otbn/crypto/mldsa87/verify:mldsa87_verify",
     ],
 )
diff --git a/sw/device/lib/crypto/impl/mldsa/mldsa.c b/sw/device/lib/crypto/impl/mldsa/mldsa.c
@@ -13,7 +13,18 @@
 // Module ID for status codes.
 #define MODULE_ID MAKE_MODULE_ID('m', 'l', 'd')
 
-// OTBN app.
+// Sign app.
+OTBN_DECLARE_APP_SYMBOLS(mldsa87_sign);
+// Inputs.
+OTBN_DECLARE_SYMBOL_ADDR(mldsa87_sign, mldsa87_sign_mode);
+OTBN_DECLARE_SYMBOL_ADDR(mldsa87_sign, mldsa87_sign_sk);
+OTBN_DECLARE_SYMBOL_ADDR(mldsa87_sign, mldsa87_sign_mu);
+// Outputs.
+OTBN_DECLARE_SYMBOL_ADDR(mldsa87_sign, mldsa87_sign_sig_c_tilde);
+OTBN_DECLARE_SYMBOL_ADDR(mldsa87_sign, mldsa87_sign_sig_z);
+OTBN_DECLARE_SYMBOL_ADDR(mldsa87_sign, mldsa87_sign_sig_h);
+
+// Verify app.
 OTBN_DECLARE_APP_SYMBOLS(mldsa87_verify);
 // Inputs.
 OTBN_DECLARE_SYMBOL_ADDR(mldsa87_verify, mldsa87_verify_pk);
@@ -23,6 +34,101 @@ OTBN_DECLARE_SYMBOL_ADDR(mldsa87_verify, mldsa87_verify_mu);
 OTBN_DECLARE_SYMBOL_ADDR(mldsa87_verify, mldsa87_verify_res_ok);
 OTBN_DECLARE_SYMBOL_ADDR(mldsa87_verify, mldsa87_verify_res_c_tilde_prime);
 
+enum {
+  kMldsa87AbridgedMode = 0x29d8e5c9,
+};
+
+static status_t read_signature(uint32_t *sig) {
+  // Read c_tilde_prime.
+  const otbn_addr_t kOtbnCTilde =
+      OTBN_ADDR_T_INIT(mldsa87_sign, mldsa87_sign_sig_c_tilde);
+  HARDENED_TRY(otbn_dmem_read(kMldsa87CTildeWords, kOtbnCTilde, sig));
+
+  // Read Z.
+  const otbn_addr_t kOtbnZ = OTBN_ADDR_T_INIT(mldsa87_sign, mldsa87_sign_sig_z);
+  HARDENED_TRY(
+      otbn_dmem_read(kMldsa87ZWords, kOtbnZ, sig + kMldsa87CTildeWords));
+
+  // Read hint.
+  const otbn_addr_t kOtbnH = OTBN_ADDR_T_INIT(mldsa87_sign, mldsa87_sign_sig_h);
+  HARDENED_TRY(otbn_dmem_read(kMldsa87HWords, kOtbnH,
+                              sig + kMldsa87CTildeWords + kMldsa87ZWords));
+
+  // Clear the Z vector.
+  HARDENED_TRY(otbn_dmem_set(kMldsa87ZWords, 0, kOtbnZ));
+
+  return OTCRYPTO_OK;
+}
+
+status_t mldsa87_sign_internal_start(const otcrypto_blinded_key_t *secret_key,
+                                     const otcrypto_hash_digest_t *mu,
+                                     uint32_t mode) {
+  // Load the ML-DSA-87 sign app and write the inputs.
+  const otbn_app_t kOtbnAppMldsa87Sign = OTBN_APP_T_INIT(mldsa87_sign);
+  HARDENED_TRY(otbn_load_app(kOtbnAppMldsa87Sign));
+
+  const otbn_addr_t kOtbnMode =
+      OTBN_ADDR_T_INIT(mldsa87_sign, mldsa87_sign_mode);
+  HARDENED_TRY(otbn_dmem_write(1, &mode, kOtbnMode));
+
+  const otbn_addr_t kOtbnSk = OTBN_ADDR_T_INIT(mldsa87_sign, mldsa87_sign_sk);
+  HARDENED_TRY(otbn_dmem_write(secret_key->keyblob_length / sizeof(uint32_t),
+                               secret_key->keyblob, kOtbnSk));
+
+  const otbn_addr_t kOtbnMu = OTBN_ADDR_T_INIT(mldsa87_sign, mldsa87_sign_mu);
+  HARDENED_TRY(otbn_dmem_write(mu->len, mu->data, kOtbnMu));
+
+  return otbn_execute();
+}
+
+status_t mldsa87_sign_internal_finalize(otcrypto_word32_buf_t *signature,
+                                        mldsa_sign_redundancy_t redundancy) {
+  // Stall until the OTBN finishes.
+  HARDENED_TRY(otbn_busy_wait_for_done());
+
+  // Read back the signature.
+  HARDENED_TRY(read_signature(signature->data));
+
+  // Return if single-sign redundancy is selected.
+  if (redundancy == kMldsa87SingleSign) {
+    HARDENED_CHECK_EQ(redundancy, kMldsa87SingleSign);
+    return OTCRYPTO_OK;
+  }
+  HARDENED_CHECK_EQ(redundancy, kMldsa87DoubleSign);
+
+  /*
+   * To thwart FI attacks, we execute a second sign operation in abridged mode
+   * without clearing the secret key, nonce KAPPA, RND and RHO_PRIME. After
+   * the completion of the second sign the entire DMEM is wiped.
+   */
+
+  uint32_t mode = kMldsa87AbridgedMode;
+  const otbn_addr_t kOtbnMode =
+      OTBN_ADDR_T_INIT(mldsa87_sign, mldsa87_sign_mode);
+  HARDENED_TRY(otbn_dmem_write(1, &mode, kOtbnMode));
+
+  // Buffer for the second signature value.
+  uint32_t sig_cmp_data[kMldsa87SigWords];
+
+  // Execute the second abridged sign and wait for its completion.
+  HARDENED_TRY(otbn_execute());
+  HARDENED_TRY(otbn_busy_wait_for_done());
+
+  // Read back the second signature.
+  HARDENED_TRY(read_signature(sig_cmp_data));
+
+  // Make sure both signature values are equal.
+  if (hardened_memeq(signature->data, sig_cmp_data, kMldsa87SigWords) !=
+      kHardenedBoolTrue) {
+    HARDENED_TRAP();
+  }
+  HARDENED_CHECK_EQ(
+      hardened_memeq(signature->data, sig_cmp_data, kMldsa87SigWords),
+      kHardenedBoolTrue);
+
+  return OTCRYPTO_OK;
+}
+
 status_t mldsa87_verify_internal_start(
     const otcrypto_unblinded_key_t *public_key,
     const otcrypto_const_word32_buf_t *signature,
@@ -74,5 +180,5 @@ status_t mldsa87_verify_internal_finalize(
   *result =
       hardened_memeq(signature->data, c_tilde_prime, kMldsa87CTildePrimeWords);
 
-  return otbn_dmem_sec_wipe();
+  return OTCRYPTO_OK;
 }
diff --git a/sw/device/lib/crypto/impl/mldsa/mldsa.h b/sw/device/lib/crypto/impl/mldsa/mldsa.h
@@ -21,13 +21,64 @@ enum {
    */
   kMldsa87CTildePrimeWords = 16,
 
+  kMldsa87CTildeBytes = 64,
+  kMldsa87CTildeWords = kMldsa87CTildeBytes / sizeof(uint32_t),
+
+  kMldsa87ZBytes = 4480,
+  kMldsa87ZWords = kMldsa87ZBytes / sizeof(uint32_t),
+
+  kMldsa87HBytes = 83 + 1,
+  kMldsa87HWords = kMldsa87HBytes / sizeof(uint32_t),
+
+  kMldsa87SigBytes = 4627 + 1,
+  kMldsa87SigWords = kMldsa87SigBytes / sizeof(uint32_t),
+
   /**
    * 32-bit success and error indicators.
    */
   kMldsa87StatusOk = 0x7baf73d2,
   kMldsa87StatusFail = 0xadf1aebd,
 };
 
+/**
+ * Redundancy modes for ML-DSA sign.
+ */
+typedef enum mldsa_sign_redundancy {
+  /**
+   * Compute a single signature.
+   */
+  kMldsa87SingleSign = 0x5514edb7,
+  /**
+   * Compute two signatures and compare that they are equal.
+   */
+  kMldsa87DoubleSign = 0xfaacd725,
+} mldsa_sign_redundancy_t;
+
+/**
+ * Start an async ML-DSA-87 signature generation on the OTBN.
+ *
+ * Returns an `OTCRYPTO_ASYNC_INCOMPLETE` error if OTBN is busy.
+ *
+ * @param secret_key Masked key for the signature generation (6368 bytes).
+ * @param rnd The randomness string (32 bytes).
+ * @param mu The message hash (64 bytes).
+ * @param kappa The rejection loop nonce.
+ */
+status_t mldsa87_sign_internal_start(const otcrypto_blinded_key_t *secret_key,
+                                     const otcrypto_hash_digest_t *mu,
+                                     uint32_t mode);
+
+/**
+ * Finish an async ML-DSA-87 signature generation on the OTBN.
+ *
+ * Blocks until OTBN is idle.
+ *
+ * @param[out] signature The generated signature (4627 + 1 bytes).
+ * @return Result of the operation (OK or error).
+ */
+status_t mldsa87_sign_internal_finalize(otcrypto_word32_buf_t *signature,
+                                        mldsa_sign_redundancy_t redundancy);
+
 /**
  * Start an async ML-DSA-87 signature verification on the OTBN.
  *
@@ -58,7 +109,7 @@ status_t mldsa87_verify_internal_start(
  * status will be OK but `result` will be `kHardenedBoolFalse`.
  *
  * @param signature Signature to be verified (4628 bytes).
- * @param result (true if signature is valid, false otherwise).
+ * @param[out] result (true if signature is valid, false otherwise).
  * @return Result of the operation (OK or error).
  */
 OT_WARN_UNUSED_RESULT
diff --git a/sw/device/lib/crypto/include/mldsa.h b/sw/device/lib/crypto/include/mldsa.h

Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,7 @@ cc_library(`
`16`	`16`	`"//sw/device/lib/base:hardened_memory",`
`17`	`17`	`"//sw/device/lib/crypto/drivers:otbn",`
`18`	`18`	`"//sw/device/lib/crypto/impl:status",`
	`19`	`+ "//sw/otbn/crypto/mldsa87/sign:mldsa87_sign",`
`19`	`20`	`"//sw/otbn/crypto/mldsa87/verify:mldsa87_verify",`
`20`	`21`	`],`
`21`	`22`	`)`