Skip to content

Commit cdb0aee

Browse files
mkannwischermkannwischer
committed
HashML-DSA: Add specialized shake256 pre-hashing function
The previous commit added the _pre_hash_internal functions that expect the pre-hashed message, i.e., requiring the callee to compute the pre-hash themselves. The alternative is to perform the pre-hashing inside mldsa-native which eases the use for the consumer. However, that would require maintaining 12 hash functions and allowing consumers to replace those with their own hash functions. This commit implements a compromise: We do add an API that includes the pre-hashing step, but only for the most popular pre-hashing hash function: SHAKE256. If later a consumer also requires other hash functions, we can add it. Signed-off-by: Matthias J. Kannwischer <[email protected]>
1 parent 74e944b commit cdb0aee

File tree

8 files changed

+472
-21
lines changed

8 files changed

+472
-21
lines changed

‎mldsa/sign.c‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -929,3 +929,38 @@ int crypto_sign_verify_pre_hash_internal(const uint8_t *sig, size_t siglen,
929929
mld_zeroize(fmsg, sizeof(fmsg));
930930
return result;
931931
}
932+
933+
MLD_MUST_CHECK_RETURN_VALUE
934+
MLD_EXTERNAL_API
935+
int crypto_sign_signature_pre_hash_shake256(uint8_t *sig, size_t *siglen,
936+
const uint8_t *m, size_t mlen,
937+
const uint8_t *ctx, size_t ctxlen,
938+
const uint8_t rnd[MLDSA_RNDBYTES],
939+
const uint8_t *sk)
940+
{
941+
MLD_ALIGN uint8_t ph[64];
942+
int result;
943+
mld_shake256(ph, sizeof(ph), m, mlen);
944+
result = crypto_sign_signature_pre_hash_internal(
945+
sig, siglen, ph, sizeof(ph), ctx, ctxlen, rnd, sk, MLD_SHAKE_256);
946+
/* @[FIPS204, Section 3.6.3] Destruction of intermediate values. */
947+
mld_zeroize(ph, sizeof(ph));
948+
return result;
949+
}
950+
951+
MLD_MUST_CHECK_RETURN_VALUE
952+
MLD_EXTERNAL_API
953+
int crypto_sign_verify_pre_hash_shake256(const uint8_t *sig, size_t siglen,
954+
const uint8_t *m, size_t mlen,
955+
const uint8_t *ctx, size_t ctxlen,
956+
const uint8_t *pk)
957+
{
958+
MLD_ALIGN uint8_t ph[64];
959+
int result;
960+
mld_shake256(ph, sizeof(ph), m, mlen);
961+
result = crypto_sign_verify_pre_hash_internal(sig, siglen, ph, sizeof(ph),
962+
ctx, ctxlen, pk, MLD_SHAKE_256);
963+
/* @[FIPS204, Section 3.6.3] Destruction of intermediate values. */
964+
mld_zeroize(ph, sizeof(ph));
965+
return result;
966+
}

‎mldsa/sign.h‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@
3737
MLD_NAMESPACE_KL(signature_pre_hash_internal)
3838
#define crypto_sign_verify_pre_hash_internal \
3939
MLD_NAMESPACE_KL(verify_pre_hash_internal)
40+
#define crypto_sign_signature_pre_hash_shake256 \
41+
MLD_NAMESPACE_KL(signature_pre_hash_shake256)
42+
#define crypto_sign_verify_pre_hash_shake256 \
43+
MLD_NAMESPACE_KL(verify_pre_hash_shake256)
4044

4145
/*************************************************
4246
* Hash algorithm enumeration for pre-hash functions
@@ -500,4 +504,81 @@ __contract__(
500504
ensures(return_value == 0 || return_value == -1)
501505
);
502506

507+
/*************************************************
508+
* Name: crypto_sign_signature_pre_hash_shake256
509+
*
510+
* Description: FIPS 204: Algorithm 4 HashML-DSA.Sign with SHAKE256.
511+
* Computes signature with pre-hashed message using SHAKE256.
512+
* This function computes the SHAKE256 hash of the message
513+
*internally.
514+
*
515+
* Arguments: - uint8_t *sig: pointer to output signature (of length
516+
* CRYPTO_BYTES)
517+
* - size_t *siglen: pointer to output length of signature
518+
* - const uint8_t *m: pointer to message to be hashed and signed
519+
* - size_t mlen: length of message
520+
* - const uint8_t *ctx: pointer to context string
521+
* - size_t ctxlen: length of context string
522+
* - const uint8_t *rnd: pointer to random seed
523+
* - const uint8_t *sk: pointer to bit-packed secret key
524+
*
525+
* Returns 0 (success) or -1 (context string too long OR nonce exhaustion)
526+
**************************************************/
527+
MLD_MUST_CHECK_RETURN_VALUE
528+
MLD_EXTERNAL_API
529+
int crypto_sign_signature_pre_hash_shake256(uint8_t *sig, size_t *siglen,
530+
const uint8_t *m, size_t mlen,
531+
const uint8_t *ctx, size_t ctxlen,
532+
const uint8_t rnd[MLDSA_RNDBYTES],
533+
const uint8_t *sk)
534+
__contract__(
535+
requires(mlen <= MLD_MAX_BUFFER_SIZE)
536+
requires(ctxlen <= MLD_MAX_BUFFER_SIZE)
537+
requires(memory_no_alias(sig, CRYPTO_BYTES))
538+
requires(memory_no_alias(siglen, sizeof(size_t)))
539+
requires(memory_no_alias(m, mlen))
540+
requires(ctxlen == 0 || memory_no_alias(ctx, ctxlen))
541+
requires(memory_no_alias(rnd, MLDSA_RNDBYTES))
542+
requires(memory_no_alias(sk, CRYPTO_SECRETKEYBYTES))
543+
assigns(memory_slice(sig, CRYPTO_BYTES))
544+
assigns(object_whole(siglen))
545+
ensures((return_value == 0 && *siglen == CRYPTO_BYTES) ||
546+
(return_value == -1 && *siglen == 0))
547+
);
548+
549+
/*************************************************
550+
* Name: crypto_sign_verify_pre_hash_shake256
551+
*
552+
* Description: FIPS 204: Algorithm 5 HashML-DSA.Verify with SHAKE256.
553+
* Verifies signature with pre-hashed message using SHAKE256.
554+
* This function computes the SHAKE256 hash of the message
555+
*internally.
556+
*
557+
* Arguments: - const uint8_t *sig: pointer to input signature
558+
* - size_t siglen: length of signature
559+
* - const uint8_t *m: pointer to message to be hashed and verified
560+
* - size_t mlen: length of message
561+
* - const uint8_t *ctx: pointer to context string
562+
* - size_t ctxlen: length of context string
563+
* - const uint8_t *pk: pointer to bit-packed public key
564+
*
565+
* Returns 0 if signature could be verified correctly and -1 otherwise
566+
**************************************************/
567+
MLD_MUST_CHECK_RETURN_VALUE
568+
MLD_EXTERNAL_API
569+
int crypto_sign_verify_pre_hash_shake256(const uint8_t *sig, size_t siglen,
570+
const uint8_t *m, size_t mlen,
571+
const uint8_t *ctx, size_t ctxlen,
572+
const uint8_t *pk)
573+
__contract__(
574+
requires(mlen <= MLD_MAX_BUFFER_SIZE)
575+
requires(ctxlen <= MLD_MAX_BUFFER_SIZE - 77)
576+
requires(siglen <= MLD_MAX_BUFFER_SIZE)
577+
requires(memory_no_alias(sig, siglen))
578+
requires(memory_no_alias(m, mlen))
579+
requires(ctxlen == 0 || memory_no_alias(ctx, ctxlen))
580+
requires(memory_no_alias(pk, CRYPTO_PUBLICKEYBYTES))
581+
ensures(return_value == 0 || return_value == -1)
582+
);
583+
503584
#endif /* !MLD_SIGN_H */

‎proofs/cbmc/crypto_sign_signature_pre_hash_shake256/Makefile‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Copyright (c) The mldsa-native project authors
2+
# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
3+
4+
include ../Makefile_params.common
5+
6+
HARNESS_ENTRY = harness
7+
HARNESS_FILE = crypto_sign_signature_pre_hash_shake256_harness
8+
9+
# This should be a unique identifier for this proof, and will appear on the
10+
# Litani dashboard. It can be human-readable and contain spaces if you wish.
11+
PROOF_UID = crypto_sign_signature_pre_hash_shake256
12+
13+
DEFINES +=
14+
INCLUDES +=
15+
16+
REMOVE_FUNCTION_BODY +=
17+
UNWINDSET +=
18+
19+
PROOF_SOURCES += $(PROOFDIR)/$(HARNESS_FILE).c
20+
PROJECT_SOURCES += $(SRCDIR)/mldsa/sign.c
21+
22+
CHECK_FUNCTION_CONTRACTS=$(MLD_NAMESPACE)signature_pre_hash_shake256
23+
USE_FUNCTION_CONTRACTS=$(MLD_NAMESPACE)signature_pre_hash_internal $(FIPS202_NAMESPACE)shake256
24+
25+
APPLY_LOOP_CONTRACTS=on
26+
USE_DYNAMIC_FRAMES=1
27+
28+
# Disable any setting of EXTERNAL_SAT_SOLVER, and choose SMT backend instead
29+
EXTERNAL_SAT_SOLVER=
30+
CBMCFLAGS=--smt2
31+
CBMCFLAGS += --slice-formula
32+
CBMCFLAGS += --no-array-field-sensitivity
33+
34+
FUNCTION_NAME = crypto_sign_signature_pre_hash_shake256
35+
36+
# If this proof is found to consume huge amounts of RAM, you can set the
37+
# EXPENSIVE variable. With new enough versions of the proof tools, this will
38+
# restrict the number of EXPENSIVE CBMC jobs running at once. See the
39+
# documentation in Makefile.common under the "Job Pools" heading for details.
40+
# EXPENSIVE = true
41+
42+
# This function is large enough to need...
43+
CBMC_OBJECT_BITS = 8
44+
45+
# If you require access to a file-local ("static") function or object to conduct
46+
# your proof, set the following (and do not include the original source file
47+
# ("mldsa/poly.c") in PROJECT_SOURCES).
48+
# REWRITTEN_SOURCES = $(PROOFDIR)/<__SOURCE_FILE_BASENAME__>.i
49+
# include ../Makefile.common
50+
# $(PROOFDIR)/<__SOURCE_FILE_BASENAME__>.i_SOURCE = $(SRCDIR)/mldsa/poly.c
51+
# $(PROOFDIR)/<__SOURCE_FILE_BASENAME__>.i_FUNCTIONS = foo bar
52+
# $(PROOFDIR)/<__SOURCE_FILE_BASENAME__>.i_OBJECTS = baz
53+
# Care is required with variables on the left-hand side: REWRITTEN_SOURCES must
54+
# be set before including Makefile.common, but any use of variables on the
55+
# left-hand side requires those variables to be defined. Hence, _SOURCE,
56+
# _FUNCTIONS, _OBJECTS is set after including Makefile.common.
57+
58+
include ../Makefile.common

‎proofs/cbmc/crypto_sign_signature_pre_hash_shake256/crypto_sign_signature_pre_hash_shake256_harness.c‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Copyright (c) The mldsa-native project authors
2+
// SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
3+
4+
#include "sign.h"
5+
6+
void harness(void)
7+
{
8+
uint8_t *sig;
9+
size_t *siglen;
10+
const uint8_t *m;
11+
size_t mlen;
12+
const uint8_t *ctx;
13+
size_t ctxlen;
14+
const uint8_t *rnd;
15+
const uint8_t *sk;
16+
int r;
17+
r = crypto_sign_signature_pre_hash_shake256(sig, siglen, m, mlen, ctx, ctxlen,
18+
rnd, sk);
19+
}

‎proofs/cbmc/crypto_sign_verify_pre_hash_shake256/Makefile‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Copyright (c) The mldsa-native project authors
2+
# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
3+
4+
include ../Makefile_params.common
5+
6+
HARNESS_ENTRY = harness
7+
HARNESS_FILE = crypto_sign_verify_pre_hash_shake256_harness
8+
9+
# This should be a unique identifier for this proof, and will appear on the
10+
# Litani dashboard. It can be human-readable and contain spaces if you wish.
11+
PROOF_UID = crypto_sign_verify_pre_hash_shake256
12+
13+
DEFINES +=
14+
INCLUDES +=
15+
16+
REMOVE_FUNCTION_BODY +=
17+
UNWINDSET +=
18+
19+
PROOF_SOURCES += $(PROOFDIR)/$(HARNESS_FILE).c
20+
PROJECT_SOURCES += $(SRCDIR)/mldsa/sign.c
21+
22+
CHECK_FUNCTION_CONTRACTS=$(MLD_NAMESPACE)verify_pre_hash_shake256
23+
USE_FUNCTION_CONTRACTS=$(MLD_NAMESPACE)verify_pre_hash_internal $(FIPS202_NAMESPACE)shake256
24+
25+
APPLY_LOOP_CONTRACTS=on
26+
USE_DYNAMIC_FRAMES=1
27+
28+
# Disable any setting of EXTERNAL_SAT_SOLVER, and choose SMT backend instead
29+
EXTERNAL_SAT_SOLVER=
30+
CBMCFLAGS=--smt2
31+
CBMCFLAGS += --slice-formula
32+
CBMCFLAGS += --no-array-field-sensitivity
33+
34+
FUNCTION_NAME = crypto_sign_verify_pre_hash_shake256
35+
36+
# If this proof is found to consume huge amounts of RAM, you can set the
37+
# EXPENSIVE variable. With new enough versions of the proof tools, this will
38+
# restrict the number of EXPENSIVE CBMC jobs running at once. See the
39+
# documentation in Makefile.common under the "Job Pools" heading for details.
40+
# EXPENSIVE = true
41+
42+
# This function is large enough to need...
43+
CBMC_OBJECT_BITS = 8
44+
45+
# If you require access to a file-local ("static") function or object to conduct
46+
# your proof, set the following (and do not include the original source file
47+
# ("mldsa/poly.c") in PROJECT_SOURCES).
48+
# REWRITTEN_SOURCES = $(PROOFDIR)/<__SOURCE_FILE_BASENAME__>.i
49+
# include ../Makefile.common
50+
# $(PROOFDIR)/<__SOURCE_FILE_BASENAME__>.i_SOURCE = $(SRCDIR)/mldsa/poly.c
51+
# $(PROOFDIR)/<__SOURCE_FILE_BASENAME__>.i_FUNCTIONS = foo bar
52+
# $(PROOFDIR)/<__SOURCE_FILE_BASENAME__>.i_OBJECTS = baz
53+
# Care is required with variables on the left-hand side: REWRITTEN_SOURCES must
54+
# be set before including Makefile.common, but any use of variables on the
55+
# left-hand side requires those variables to be defined. Hence, _SOURCE,
56+
# _FUNCTIONS, _OBJECTS is set after including Makefile.common.
57+
58+
include ../Makefile.common

‎proofs/cbmc/crypto_sign_verify_pre_hash_shake256/crypto_sign_verify_pre_hash_shake256_harness.c‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
// Copyright (c) The mldsa-native project authors
2+
// SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
3+
4+
#include "sign.h"
5+
6+
void harness(void)
7+
{
8+
const uint8_t *sig;
9+
size_t siglen;
10+
const uint8_t *m;
11+
size_t mlen;
12+
const uint8_t *ctx;
13+
size_t ctxlen;
14+
const uint8_t *pk;
15+
int r;
16+
r = crypto_sign_verify_pre_hash_shake256(sig, siglen, m, mlen, ctx, ctxlen,
17+
pk);
18+
}

‎test/acvp_client.py‎

Lines changed: 42 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -172,18 +172,29 @@ def run_sigGen_test(tg, tc):
172172
tc["rnd"] = "0" * 64
173173

174174
if tg["preHash"] == "preHash":
175-
ph = compute_hash(tc["message"], tc["hashAlg"])
176175
assert len(tc["context"]) <= 2 * 255
177176

178-
acvp_call = exec_prefix + [
179-
acvp_bin,
180-
"sigGenPreHash",
181-
f"ph={ph}",
182-
f"context={tc['context']}",
183-
f"rng={tc['rnd']}",
184-
f"sk={tc['sk']}",
185-
f"hashAlg={tc['hashAlg']}",
186-
]
177+
# Use specialized SHAKE256 function that computes hash internally
178+
if tc["hashAlg"] == "SHAKE-256":
179+
acvp_call = exec_prefix + [
180+
acvp_bin,
181+
"sigGenPreHashShake256",
182+
f"message={tc['message']}",
183+
f"context={tc['context']}",
184+
f"rnd={tc['rnd']}",
185+
f"sk={tc['sk']}",
186+
]
187+
else:
188+
ph = compute_hash(tc["message"], tc["hashAlg"])
189+
acvp_call = exec_prefix + [
190+
acvp_bin,
191+
"sigGenPreHash",
192+
f"ph={ph}",
193+
f"context={tc['context']}",
194+
f"rng={tc['rnd']}",
195+
f"sk={tc['sk']}",
196+
f"hashAlg={tc['hashAlg']}",
197+
]
187198
elif tg["signatureInterface"] == "external":
188199
assert tc["hashAlg"] == "none"
189200
assert len(tc["context"]) <= 2 * 255
@@ -238,18 +249,29 @@ def run_sigVer_test(tg, tc):
238249
acvp_bin = get_acvp_binary(tg)
239250

240251
if tg["preHash"] == "preHash":
241-
ph = compute_hash(tc["message"], tc["hashAlg"])
242252
assert len(tc["context"]) <= 2 * 255
243253

244-
acvp_call = exec_prefix + [
245-
acvp_bin,
246-
"sigVerPreHash",
247-
f"ph={ph}",
248-
f"context={tc['context']}",
249-
f"signature={tc['signature']}",
250-
f"pk={tc['pk']}",
251-
f"hashAlg={tc['hashAlg']}",
252-
]
254+
# Use specialized SHAKE256 function that computes hash internally
255+
if tc["hashAlg"] == "SHAKE-256":
256+
acvp_call = exec_prefix + [
257+
acvp_bin,
258+
"sigVerPreHashShake256",
259+
f"message={tc['message']}",
260+
f"context={tc['context']}",
261+
f"signature={tc['signature']}",
262+
f"pk={tc['pk']}",
263+
]
264+
else:
265+
ph = compute_hash(tc["message"], tc["hashAlg"])
266+
acvp_call = exec_prefix + [
267+
acvp_bin,
268+
"sigVerPreHash",
269+
f"ph={ph}",
270+
f"context={tc['context']}",
271+
f"signature={tc['signature']}",
272+
f"pk={tc['pk']}",
273+
f"hashAlg={tc['hashAlg']}",
274+
]
253275
elif tg["signatureInterface"] == "external":
254276
assert tc["hashAlg"] == "none"
255277
assert len(tc["context"]) <= 2 * 255

0 commit comments

Comments
 (0)