ML-DSA: add external Mu support

Signed-off-by: Stephan Mueller <smueller@chronox.de>

Author: smuellerDD

CHANGES.md

@@ -1,4 +1,4 @@
-Changes 1.2.1-prerelease
+Changes 1.3.0-prerelease
 * Allow CPU entropy sources to be used as seed sources with meson option "seedsource=cpu"
 
 * Ensure full clean run on vintage system without AVX2 (thanks to "David C. Rankin" <drankinatty@gmail.com>)
@@ -13,6 +13,8 @@ Changes 1.2.1-prerelease
 
 * *Full FIPS 140 compliance*: Invoke PCT, add integrity test for ELF compilations, enable FIPS compilation by default
 
+* ML-DSA: add external-mu support; new API: lc_dilithium_ctx_external_mu
+
 Changes 1.2.0
 * Locking für seeded_rng added to avoid requiring the caller providing a lock
 

leancrypto.spec

@@ -5,7 +5,7 @@
 #
 
 Name:           leancrypto
-Version:        1.2.1
+Version:        1.3.0
 Release:        1.1
 Summary:        Cryptographic library with stack-only support and PQC-safe algorithms
 License:        GPL-2.0 OR BSD-2-Clause

linux_kernel/Kbuild.version

@@ -1,3 +1,3 @@
 # Version Number of Leancrypto
 #
-ccflags-y	+= -DMAJVERSION=1 -DMINVERSION=2 -DPATCHLEVEL=1
+ccflags-y	+= -DMAJVERSION=1 -DMINVERSION=3 -DPATCHLEVEL=0

meson.build

@@ -11,7 +11,7 @@
 # Patchlevel Version: API / ABI compatible, no functional changes, no
 #		      enhancements, bug fixes only.
 project('leancrypto', 'c',
-	version: '1.2.1',
+	version: '1.3.0',
 	default_options: [
 		'warning_level=3',
 		'optimization=3',

ml-dsa/api/lc_dilithium.h

@@ -274,6 +274,25 @@ void lc_dilithium_ctx_hash(struct lc_dilithium_ctx *ctx,
 void lc_dilithium_ctx_userctx(struct lc_dilithium_ctx *ctx,
 			      const uint8_t *userctx, size_t userctxlen);
 
+/**
+ * @ingroup Dilithium
+ * @brief Specify the optional external mu value.
+ *
+ * \note If the external mu is specified, the signature generation /
+ * verification APIs do not require a message. In this case, the message buffer
+ * can be set to NULL.
+ *
+ * \note If both a message and an external mu are provided, the external mu
+ * takes precedence.
+ *
+ * @param [in] ctx Dilithium context
+ * @param [in] external_mu User context string
+ * @param [in] external_mu_len Size of the user context string
+ */
+void lc_dilithium_ctx_external_mu(struct lc_dilithium_ctx *ctx,
+				  const uint8_t *external_mu,
+				  size_t external_mu_len);
+
 /**
  * @ingroup Dilithium
  * @brief Invalidate the expanded key that potentially is stored in the context.

ml-dsa/api/lc_dilithium_size.h.in

@@ -221,6 +221,16 @@ struct lc_dilithium_ctx {
 	void *ahat;
 	unsigned short ahat_size;
 
+	/**
+	 * @brief Pointer to the external mu.
+	 *
+	 * If set, the signature operation will use the provided mu instead of
+	 * the message. In this case, the message pointer to the signature
+	 * generation or verification can be NULL.
+	 */
+	const uint8_t *external_mu;
+	size_t external_mu_len;
+
 	/**
 	 * @brief Is the Composite-ML-DSA operation wanted? If yes, set the
 	 * NIST category here
@@ -284,7 +294,9 @@ struct lc_dilithium_ctx {
 	(name)->userctx = NULL;                                                \
 	(name)->composite_ml_dsa = 0;                                          \
 	(name)->ahat = NULL;                                                   \
-	(name)->ahat_size = 0
+	(name)->ahat_size = 0;                                                 \
+	(name)->external_mu = NULL;                                            \
+	(name)->external_mu_len = 0;
 #endif
 /// \endcond
 

ml-dsa/src/avx2/dilithium_signature_avx2.c

@@ -326,9 +326,26 @@ static int lc_dilithium_sign_avx2_internal(struct lc_dilithium_sig *sig,
 	mu = rnd + LC_DILITHIUM_RNDBYTES;
 	rhoprime = mu + LC_DILITHIUM_CRHBYTES;
 
-	/* Compute CRH(tr, msg) */
-	lc_hash_set_digestsize(hash_ctx, LC_DILITHIUM_CRHBYTES);
-	lc_hash_final(hash_ctx, mu);
+	/*
+	 * If the external mu is provided, use this verbatim, otherwise
+	 * calculate the mu value.
+	 */
+	if (ctx->external_mu) {
+		if (ctx->external_mu_len != LC_DILITHIUM_CRHBYTES)
+			return -EINVAL;
+		memcpy(mu, ctx->external_mu, LC_DILITHIUM_CRHBYTES);
+	} else {
+		/*
+		 * Set the digestsize - for SHA512 this is a noop, for SHAKE256,
+		 * it sets the value. The BUILD_BUG_ON is to check that the
+		 * SHA-512 output size is identical to the expected length.
+		 */
+		BUILD_BUG_ON(LC_DILITHIUM_CRHBYTES != LC_SHA3_512_SIZE_DIGEST);
+
+		/* Compute CRH(tr, msg) */
+		lc_hash_set_digestsize(hash_ctx, LC_DILITHIUM_CRHBYTES);
+		lc_hash_final(hash_ctx, mu);
+	}
 
 	if (rng_ctx) {
 		CKINT(lc_rng_generate(rng_ctx, NULL, 0, rnd,
@@ -515,25 +532,31 @@ LC_INTERFACE_FUNCTION(int, lc_dilithium_sign_ctx_avx2,
 	uint8_t tr[LC_DILITHIUM_TRBYTES];
 	int ret = 0;
 	static int tested = 0;
-	struct lc_hash_ctx *hash_ctx;
 
 	/* rng_ctx is allowed to be NULL as handled below */
-	if (!sig || !m || !sk || !ctx)
+	if (!sig || !sk || !ctx)
+		return -EINVAL;
+	/* Either the message or the external mu must be provided */
+	if (!m && !ctx->external_mu)
 		return -EINVAL;
 
 	dilithium_siggen_tester(&tested, "Dilithium Siggen AVX2",
 				lc_dilithium_sign_ctx_avx2);
 
 	unpack_sk_tr_avx2(tr, sk);
 
-	/* Compute mu = CRH(tr, msg) */
-	hash_ctx = &ctx->dilithium_hash_ctx;
-	lc_hash_init(hash_ctx);
-	lc_hash_update(hash_ctx, tr, LC_DILITHIUM_TRBYTES);
-	CKINT(signature_domain_separation(
-		&ctx->dilithium_hash_ctx, ctx->ml_dsa_internal,
-		ctx->dilithium_prehash_type, ctx->userctx, ctx->userctxlen, m,
-		mlen, LC_DILITHIUM_NIST_CATEGORY, !!ctx->composite_ml_dsa));
+	if (m) {
+		/* Compute mu = CRH(tr, msg) */
+		struct lc_hash_ctx *hash_ctx = &ctx->dilithium_hash_ctx;
+
+		lc_hash_init(hash_ctx);
+		lc_hash_update(hash_ctx, tr, LC_DILITHIUM_TRBYTES);
+		CKINT(signature_domain_separation(
+			&ctx->dilithium_hash_ctx, ctx->ml_dsa_internal,
+			ctx->dilithium_prehash_type, ctx->userctx,
+			ctx->userctxlen, m, mlen, LC_DILITHIUM_NIST_CATEGORY,
+			!!ctx->composite_ml_dsa));
+	}
 
 	ret = lc_dilithium_sign_avx2_internal(sig, ctx, sk, rng_ctx);
 
@@ -653,9 +676,6 @@ static int lc_dilithium_verify_avx2_internal(const struct lc_dilithium_sig *sig,
 
 	row = ws->rowbuf;
 
-	lc_hash_set_digestsize(hash_ctx, LC_DILITHIUM_CRHBYTES);
-	lc_hash_final(hash_ctx, ws->mu);
-
 	/* Expand challenge */
 	poly_challenge_avx(&ws->c, sig->sig);
 	poly_ntt_avx(&ws->c);
@@ -720,9 +740,23 @@ static int lc_dilithium_verify_avx2_internal(const struct lc_dilithium_sig *sig,
 		}
 	}
 
-	/* Call random oracle and verify challenge */
-	lc_hash_init(hash_ctx);
-	lc_hash_update(hash_ctx, ws->mu, LC_DILITHIUM_CRHBYTES);
+	if (ctx->external_mu) {
+		if (ctx->external_mu_len != LC_DILITHIUM_CRHBYTES)
+			return -EINVAL;
+
+		/* Call random oracle and verify challenge */
+		lc_hash_init(hash_ctx);
+		lc_hash_update(hash_ctx, ctx->external_mu,
+			       LC_DILITHIUM_CRHBYTES);
+	} else {
+		lc_hash_set_digestsize(hash_ctx, LC_DILITHIUM_CRHBYTES);
+		lc_hash_final(hash_ctx, ws->mu);
+
+		/* Call random oracle and verify challenge */
+		lc_hash_init(hash_ctx);
+		lc_hash_update(hash_ctx, ws->mu, LC_DILITHIUM_CRHBYTES);
+	}
+
 	lc_hash_update(hash_ctx, ws->buf.coeffs,
 		       LC_DILITHIUM_K * LC_DILITHIUM_POLYW1_PACKEDBYTES);
 	lc_hash_set_digestsize(hash_ctx, LC_DILITHIUM_CTILDE_BYTES);
@@ -747,9 +781,11 @@ LC_INTERFACE_FUNCTION(int, lc_dilithium_verify_ctx_avx2,
 	uint8_t tr[LC_DILITHIUM_TRBYTES];
 	int ret = 0;
 	static int tested = 0;
-	struct lc_hash_ctx *hash_ctx;
 
-	if (!sig || !m || !pk || !ctx)
+	if (!sig || !pk || !ctx)
+		return -EINVAL;
+	/* Either the message or the external mu must be provided */
+	if (!m && !ctx->external_mu)
 		return -EINVAL;
 
 	dilithium_sigver_tester(&tested, "Dilithium Sigver AVX2",
@@ -759,13 +795,16 @@ LC_INTERFACE_FUNCTION(int, lc_dilithium_verify_ctx_avx2,
 	lc_xof(lc_shake256, pk->pk, LC_DILITHIUM_PUBLICKEYBYTES, tr,
 	       LC_DILITHIUM_TRBYTES);
 
-	hash_ctx = &ctx->dilithium_hash_ctx;
-	lc_hash_init(hash_ctx);
-	lc_hash_update(hash_ctx, tr, LC_DILITHIUM_TRBYTES);
-	CKINT(signature_domain_separation(
-		&ctx->dilithium_hash_ctx, ctx->ml_dsa_internal,
-		ctx->dilithium_prehash_type, ctx->userctx, ctx->userctxlen, m,
-		mlen, LC_DILITHIUM_NIST_CATEGORY, !!ctx->composite_ml_dsa));
+	if (m) {
+		struct lc_hash_ctx *hash_ctx = &ctx->dilithium_hash_ctx;
+		lc_hash_init(hash_ctx);
+		lc_hash_update(hash_ctx, tr, LC_DILITHIUM_TRBYTES);
+		CKINT(signature_domain_separation(
+			&ctx->dilithium_hash_ctx, ctx->ml_dsa_internal,
+			ctx->dilithium_prehash_type, ctx->userctx,
+			ctx->userctxlen, m, mlen, LC_DILITHIUM_NIST_CATEGORY,
+			!!ctx->composite_ml_dsa));
+	}
 
 	ret = lc_dilithium_verify_avx2_internal(sig, pk, ctx);
 

ml-dsa/src/dilithium_api.c

@@ -118,6 +118,16 @@ LC_INTERFACE_FUNCTION(void, lc_dilithium_ctx_userctx,
 	}
 }
 
+LC_INTERFACE_FUNCTION(void, lc_dilithium_ctx_external_mu,
+		      struct lc_dilithium_ctx *ctx, const uint8_t *external_mu,
+		      size_t external_mu_len)
+{
+	if (ctx) {
+		ctx->external_mu = external_mu;
+		ctx->external_mu_len = external_mu_len;
+	}
+}
+
 LC_INTERFACE_FUNCTION(void, lc_dilithium_ctx_drop_ahat,
 		      struct lc_dilithium_ctx *ctx)
 {