# SPDX-License-Identifier: Apache-2.0 # Copyright 2026 Scienting # # Source Code: https://git.scient.ing/papers/paperspec # See the LICENSE.md file for full license terms. """ML-DSA-65 of FIPS 204 in plain Python (paperspec.mldsa).""" import pytest from hypothesis import given, settings, strategies as st from conftest import vector_cases from helpers_lib2 import PROPS from paperspec import mldsa CASES = {c["id"]: c for c in vector_cases("signatures") if c["id"].startswith("ml-dsa")} SEED = bytes.fromhex(CASES["ml-dsa-65-sign-empty"]["seed"]) POLY = st.lists(st.integers(0, mldsa.Q - 1), min_size=mldsa.N, max_size=mldsa.N) @pytest.fixture(scope="module") def keys(): return mldsa.keygen(SEED) @pytest.fixture(scope="module") def signature(keys): return mldsa.sign(keys[1], b"a message") def negacyclic_product(a, b): """The product of two polynomials modulo x^256 + 1 and q, by the schoolbook method.""" out = [0] * mldsa.N for i, x in enumerate(a): for j, y in enumerate(b): k = i + j if k < mldsa.N: out[k] += x * y else: out[k - mldsa.N] -= x * y return [c % mldsa.Q for c in out] # --- vectors and sizes ---------------------------------------------------------------------- @pytest.mark.parametrize("case", CASES.values(), ids=list(CASES)) def test_key_generation_matches_the_vector(case): public, _ = mldsa.keygen(bytes.fromhex(case["seed"])) assert public.hex() == case["public"] assert mldsa.public_key(bytes.fromhex(case["seed"])) == public def test_signature_matches_the_vector_and_verifies(keys): case = CASES["ml-dsa-65-sign-empty"] public, secret = keys message = bytes.fromhex(case["message"]) signature = mldsa.sign(secret, message) assert signature.hex() == case["signature"] assert mldsa.verify(public, message, signature) assert not mldsa.verify(public, b"x", signature) def test_key_and_signature_sizes_are_those_of_ml_dsa_65(keys, signature): public, secret = keys assert (len(public), len(secret), len(signature)) == (1952, 4032, 3309) assert (mldsa.PK_SIZE, mldsa.SK_SIZE, mldsa.SIG_SIZE) == (1952, 4032, 3309) def test_signing_is_deterministic(keys, signature): assert mldsa.sign(keys[1], b"a message") == signature def test_the_hedging_bytes_change_the_signature_but_not_its_validity(keys): public, secret = keys hedged = mldsa.sign(secret, b"a message", rnd=bytes([7]) * 32) assert hedged != mldsa.sign(secret, b"a message") assert mldsa.verify(public, b"a message", hedged) @pytest.mark.parametrize("length", [0, 31, 33]) def test_key_generation_needs_a_32_byte_seed(length): with pytest.raises(ValueError, match="32 bytes"): mldsa.keygen(bytes(length)) # --- verification refusals -------------------------------------------------------------------- def test_a_signature_does_not_verify_under_another_key_or_message(keys, signature): public, _ = keys other, _ = mldsa.keygen(bytes(32)) assert mldsa.verify(public, b"a message", signature) assert not mldsa.verify(other, b"a message", signature) assert not mldsa.verify(public, b"a message ", signature) assert not mldsa.verify(public, b"", signature) @pytest.mark.parametrize( "position", [0, 23, 24, 1000, 3000, 3200, 3309 - 56, 3309 - 7, 3308], ids=lambda p: f"byte-{p}", ) def test_a_signature_with_a_changed_bit_does_not_verify(keys, signature, position): bad = bytearray(signature) bad[position] ^= 0x04 assert not mldsa.verify(keys[0], b"a message", bytes(bad)) @pytest.mark.parametrize("length", [0, 3308, 3310]) def test_a_signature_of_the_wrong_length_does_not_verify(keys, signature, length): padded = signature + bytes(8) assert not mldsa.verify(keys[0], b"a message", padded[:length]) def test_a_key_of_the_wrong_length_does_not_verify(keys, signature): assert not mldsa.verify(keys[0][:-1], b"a message", signature) assert not mldsa.verify(keys[0] + b"\x00", b"a message", signature) def test_verification_never_raises_on_the_wrong_types(keys, signature): assert not mldsa.verify(keys[0], None, signature) assert not mldsa.verify(None, b"a message", signature) assert not mldsa.verify(keys[0], b"a message", None) def test_a_signature_with_a_response_out_of_bounds_does_not_verify(keys, signature): c_tilde, z, hint = mldsa.sig_decode(signature) z[0][0] = mldsa.GAMMA1 - 1 forged = mldsa.sig_encode(c_tilde, z, hint) assert len(forged) == mldsa.SIG_SIZE assert not mldsa.verify(keys[0], b"a message", forged) def test_a_signature_with_a_malformed_hint_does_not_verify(keys, signature): tail = mldsa.SIG_SIZE - mldsa.OMEGA - mldsa.K bad = signature[:tail] + bytes([0xFF] * mldsa.OMEGA) + bytes(mldsa.K) assert not mldsa.verify(keys[0], b"a message", bad) # --- contexts ----------------------------------------------------------------------------------- def test_a_context_is_part_of_what_is_signed(keys): public, secret = keys signature = mldsa.sign(secret, b"a message", ctx=b"paper") assert mldsa.verify(public, b"a message", signature, ctx=b"paper") assert not mldsa.verify(public, b"a message", signature) assert not mldsa.verify(public, b"a message", signature, ctx=b"papers") def test_a_context_of_256_bytes_is_refused(keys): public, secret = keys longest = bytes(255) signature = mldsa.sign(secret, b"m", ctx=longest) assert mldsa.verify(public, b"m", signature, ctx=longest) with pytest.raises(ValueError, match="at most 255 bytes"): mldsa.sign(secret, b"m", ctx=bytes(256)) assert not mldsa.verify(public, b"m", signature, ctx=bytes(256)) @given(st.binary(max_size=80)) @settings(PROPS, max_examples=6) def test_a_signature_of_any_message_verifies_and_only_for_it(keys, message): public, secret = keys signature = mldsa.sign(secret, message) assert mldsa.verify(public, message, signature) assert not mldsa.verify(public, message + b"\x00", signature) @given(st.binary(min_size=32, max_size=32)) @settings(PROPS, max_examples=4) def test_any_seed_gives_a_key_that_verifies_its_own_signature(seed): public, secret = mldsa.keygen(seed) assert (len(public), len(secret)) == (mldsa.PK_SIZE, mldsa.SK_SIZE) assert mldsa.verify(public, b"m", mldsa.sign(secret, b"m")) # --- encodings ---------------------------------------------------------------------------------- def test_key_encodings_round_trip(keys): public, secret = keys rho, t1 = mldsa.pk_decode(public) assert mldsa.pk_encode(rho, t1) == public assert len(t1) == mldsa.K assert all(0 <= c < 1 << 10 for t in t1 for c in t) assert mldsa.sk_encode(*mldsa.sk_decode(secret)) == secret def test_signature_encoding_round_trips(signature): c_tilde, z, hint = mldsa.sig_decode(signature) assert len(c_tilde) == mldsa.LAMBDA // 4 assert len(z) == mldsa.L assert sum(map(sum, hint)) <= mldsa.OMEGA assert mldsa.sig_encode(c_tilde, z, hint) == signature @given(POLY, st.sampled_from([1, 255, 1023, (mldsa.Q - 1) // 32 - 1])) @PROPS def test_simple_bit_packing_round_trips(poly, bound): clipped = [c % (bound + 1) for c in poly] assert ( mldsa.simple_bit_unpack(mldsa.simple_bit_pack(clipped, bound), bound) == clipped ) @given(st.lists(st.integers(-4, 4), min_size=256, max_size=256)) @PROPS def test_bit_packing_of_small_coefficients_round_trips(poly): assert mldsa.bit_unpack(mldsa.bit_pack(poly, 4, 4), 4, 4) == poly @given(st.lists(st.integers(-(2**19) + 1, 2**19), min_size=256, max_size=256)) @PROPS def test_bit_packing_of_masks_round_trips(poly): packed = mldsa.bit_pack(poly, mldsa.GAMMA1 - 1, mldsa.GAMMA1) assert len(packed) == 32 * 20 assert mldsa.bit_unpack(packed, mldsa.GAMMA1 - 1, mldsa.GAMMA1) == poly @given( st.sets(st.tuples(st.integers(0, mldsa.K - 1), st.integers(0, 255)), max_size=55) ) @PROPS def test_hints_round_trip(positions): hint = [[0] * mldsa.N for _ in range(mldsa.K)] for row, col in positions: hint[row][col] = 1 packed = mldsa.hint_bit_pack(hint) assert len(packed) == mldsa.OMEGA + mldsa.K assert mldsa.hint_bit_unpack(packed) == hint def hint_bytes(counts, indexes=()): """A packed hint with the given cumulative counts per row and leading index bytes.""" packed = bytearray(mldsa.OMEGA + mldsa.K) packed[: len(indexes)] = bytes(indexes) packed[mldsa.OMEGA :] = bytes(counts) return bytes(packed) @pytest.mark.parametrize( "packed", [ hint_bytes([2, 2, 2, 2, 2, 2], [9, 3]), hint_bytes([2, 2, 2, 2, 2, 2], [4, 4]), hint_bytes([2, 1, 1, 1, 1, 1], [3, 4]), hint_bytes([mldsa.OMEGA + 1] * mldsa.K), hint_bytes([0, 0, 0, 0, 0, 0], [5]), ], ids=[ "indexes-descend", "index-repeats", "counts-shrink", "count-above-omega", "unused-byte-set", ], ) def test_malformed_hints_are_refused(packed): assert mldsa.hint_bit_unpack(packed) is None # --- arithmetic --------------------------------------------------------------------------------- @given(POLY) @PROPS def test_the_number_theoretic_transform_inverts(poly): assert mldsa.ntt_inv(mldsa.ntt(poly)) == poly @given(POLY, POLY) @settings(PROPS, max_examples=6) def test_the_transform_turns_products_into_negacyclic_convolutions(a, b): product = mldsa.ntt_inv( [x * y % mldsa.Q for x, y in zip(mldsa.ntt(a), mldsa.ntt(b), strict=True)] ) assert product == negacyclic_product(a, b) @given(st.integers(0, mldsa.Q - 1)) @PROPS def test_power2round_splits_a_residue_into_high_and_low_parts(r): high, low = mldsa.power2round(r) assert high * 2**mldsa.D + low == r assert -(2 ** (mldsa.D - 1)) < low <= 2 ** (mldsa.D - 1) @given(st.integers(0, mldsa.Q - 1)) @PROPS def test_decompose_splits_a_residue_around_multiples_of_two_gamma2(r): high, low = mldsa.decompose(r) step = 2 * mldsa.GAMMA2 assert (high * step + low) % mldsa.Q == r assert -mldsa.GAMMA2 <= low <= mldsa.GAMMA2 assert 0 <= high < (mldsa.Q - 1) // step assert (mldsa.high_bits(r), mldsa.low_bits(r)) == (high, low) def test_decompose_folds_the_top_residue_into_the_lowest_high_part(): assert mldsa.decompose(mldsa.Q - 1) == (0, -1) @given(st.integers(-mldsa.GAMMA2, mldsa.GAMMA2), st.integers(0, mldsa.Q - 1)) @PROPS def test_a_hint_recovers_the_high_bits_of_a_sum(z, r): hint = mldsa.make_hint(z, r) assert hint in (0, 1) assert mldsa.use_hint(hint, r) == mldsa.high_bits(r + z) @pytest.mark.parametrize( ("hint", "r", "expected"), [(0, 10, 0), (1, 10, 1), (1, mldsa.GAMMA2 + 1, 0), (1, 0, 15)], ids=["no-hint", "positive-low-part-up", "negative-low-part-down", "zero-wraps"], ) def test_use_hint_moves_the_high_part_toward_the_low_part(hint, r, expected): assert mldsa.use_hint(hint, r) == expected # --- sampling ----------------------------------------------------------------------------------- @given(st.binary(min_size=34, max_size=34)) @settings(PROPS, max_examples=10) def test_rejection_sampling_gives_reduced_coefficients(rho): poly = mldsa.rej_ntt_poly(rho) assert len(poly) == mldsa.N assert all(0 <= c < mldsa.Q for c in poly) assert poly == mldsa.rej_ntt_poly(rho) @given(st.binary(min_size=66, max_size=66)) @settings(PROPS, max_examples=10) def test_bounded_sampling_gives_small_coefficients(rho): poly = mldsa.rej_bounded_poly(rho) assert len(poly) == mldsa.N assert all(-mldsa.ETA <= c <= mldsa.ETA for c in poly) @given(st.binary(min_size=48, max_size=48)) @settings(PROPS, max_examples=10) def test_sample_in_ball_has_exactly_tau_signed_ones(rho): ball = mldsa.sample_in_ball(rho) assert len(ball) == mldsa.N assert sorted(c for c in ball if c) == sorted( c for c in ball if c in (1, mldsa.Q - 1) ) assert sum(1 for c in ball if c) == mldsa.TAU def test_the_matrix_and_secret_vectors_have_the_shapes_of_ml_dsa_65(): matrix = mldsa.expand_a(bytes(32)) s1, s2 = mldsa.expand_s(bytes(64)) assert (len(matrix), len(matrix[0])) == (mldsa.K, mldsa.L) assert (len(s1), len(s2)) == (mldsa.L, mldsa.K) assert len(mldsa.expand_mask(bytes(64), 0)) == mldsa.L assert mldsa.expand_mask(bytes(64), 0) != mldsa.expand_mask(bytes(64), mldsa.L) def test_ntt_sampling_asks_for_more_bytes_when_the_stream_runs_out(monkeypatch): def stream(data, n): return ( b"\xff" * n if n <= 900 else b"\xff" * 900 + b"\x05\x00\x00" * ((n - 900) // 3) ) monkeypatch.setattr(mldsa, "_shake128", stream) assert mldsa.rej_ntt_poly(bytes(34)) == [5] * mldsa.N def test_bounded_sampling_asks_for_more_bytes_when_the_stream_runs_out(monkeypatch): def stream(data, n): return b"\xff" * n if n <= 200 else b"\xff" * 200 + bytes(n - 200) monkeypatch.setattr(mldsa, "_shake256", stream) assert mldsa.rej_bounded_poly(bytes(66)) == [mldsa.ETA] * mldsa.N def test_bounded_sampling_stops_at_the_last_coefficient_mid_byte(monkeypatch): def stream(data, n): return b"\x0f" + bytes(n - 1) monkeypatch.setattr(mldsa, "_shake256", stream) assert mldsa.rej_bounded_poly(bytes(66)) == [mldsa.ETA] * mldsa.N def test_ball_sampling_asks_for_more_bytes_when_the_stream_runs_out(monkeypatch): first = 8 + mldsa.TAU * 4 def stream(data, n): return bytes(8) + b"\xff" * (first - 8) + bytes(n - first) monkeypatch.setattr(mldsa, "_shake256", stream) ball = mldsa.sample_in_ball(bytes(48)) assert sum(1 for c in ball if c) == mldsa.TAU assert set(ball) == {0, 1}