# 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. """Keyed hashing, Merkle trees, RFC 9162 proofs, Ed25519 and did:key (paperspec.crypto).""" import hashlib import sys import pytest from hypothesis import given, strategies as st from conftest import vector_cases from helpers_lib2 import PROPS from paperspec import crypto, jcs SHA256_EMPTY = hashlib.sha256(b"").hexdigest() ITEM = st.tuples( st.sampled_from(["node", "annotation", "digitization"]), st.text(alphabet="abcdefghjkmnpqrstvwxyz0123456789", min_size=1, max_size=8), st.binary(min_size=4, max_size=4).map(lambda b: hashlib.sha256(b).hexdigest()), ).map(list) TREES = st.lists(ITEM, min_size=1, max_size=24) def mth(items): """The Merkle tree hash of RFC 6962 ยง2.1, written out from the definition.""" leaves = [hashlib.sha256(b"\x00" + jcs.dumpb(i)).digest() for i in items] def tree(ls): if len(ls) == 1: return ls[0] k = 1 << ((len(ls) - 1).bit_length() - 1) return hashlib.sha256(b"\x01" + tree(ls[:k]) + tree(ls[k:])).digest() return tree(leaves).hex() def base58_decode(text): """The bytes a base58btc string encodes, with its leading `1` characters as zero bytes.""" n = 0 for ch in text: n = n * 58 + crypto.BASE58.index(ch) body = n.to_bytes((n.bit_length() + 7) // 8, "big") return b"\x00" * (len(text) - len(text.lstrip("1"))) + body # --- keyed hashes and keys ---------------------------------------------------------------- KEYED = {c["id"]: c for c in vector_cases("keyed")} def test_team_key_and_its_id(): case = KEYED["team-key"] key = crypto.team_key(bytes.fromhex(case["secret"])) assert key.hex() == case["key"] assert crypto.key_id(key) == case["key_id"] def test_hkdf_rfc5869_case_1(): okm = crypto.hkdf( bytes.fromhex("0b" * 22), bytes(range(13)), bytes(range(0xF0, 0xFA)), length=42, ) assert okm.hex() == ( "3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf" "34007208d5b887185865" ) def test_page_hashes(): case = KEYED["page-hashes"] assert [crypto.page_hash(fp) for fp in case["page_fps"]] == case["page_hashes"] def test_page_key_depends_on_every_page_and_the_context(): case = KEYED["page-key"] key = crypto.page_key(case["page_fps"], case["context"]) assert key.hex() == case["key"] other = KEYED["non-holder"] wrong = crypto.page_key(other["wrong_page_fps"], case["context"]) assert wrong.hex() == other["wrong_key"] != case["key"] assert crypto.page_key(case["page_fps"], case["context"] + "x") != key assert crypto.page_key(case["page_fps"][::-1], case["context"]) != key def test_missing_cryptography_package_names_the_extra(monkeypatch): monkeypatch.setitem(sys.modules, "cryptography", None) with pytest.raises(ImportError, match=r"paperspec\[crypto\]"): crypto.hkdf(b"k", b"salt", b"info") with pytest.raises(ImportError, match="cryptography"): crypto.ed25519_public(bytes(32)) # --- Merkle roots --------------------------------------------------------------------------- @pytest.mark.parametrize("case", vector_cases("merkle"), ids=lambda c: c["id"]) def test_merkle_root_vectors(case): assert crypto.merkle_root(case["items"]) == case["root"] def test_merkle_root_of_nothing_is_refused(): with pytest.raises(ValueError, match="at least one item"): crypto.merkle_root([]) def test_history_root_of_nothing_is_the_hash_of_the_empty_string(): assert crypto.history_root([]) == crypto.EMPTY_ROOT == SHA256_EMPTY def test_history_root_agrees_with_merkle_root_on_a_nonempty_list(): items = [["node", "k0yqkzd", "00" * 32], ["node", "h9haqzy", "11" * 32]] assert crypto.history_root(items) == crypto.merkle_root(items) def test_a_single_item_root_is_its_leaf_hash(): item = ["node", "k0yqkzd", "ab" * 32] assert crypto.merkle_root([item]) == crypto.leaf_hash(item) def test_leaf_and_node_hashes_are_domain_separated(): left, right = ["node", "a", "00" * 32], ["node", "b", "11" * 32] root = crypto.merkle_root([left, right]) forged_leaf = bytes.fromhex(crypto.leaf_hash(left) + crypto.leaf_hash(right)) assert hashlib.sha256(b"\x00" + forged_leaf).hexdigest() != root def test_receipt_items_lists_nodes_before_records(): receipt = { "nodes": [["n1", "h1"], ["n2", "h2"]], "records": [("annotation", "a1", "h3")], } assert crypto.receipt_items(receipt) == [ ["node", "n1", "h1"], ["node", "n2", "h2"], ["annotation", "a1", "h3"], ] def test_receipt_items_of_a_receipt_without_either_is_empty(): assert crypto.receipt_items({}) == [] @given(TREES) @PROPS def test_merkle_root_follows_the_rfc_6962_definition(items): assert crypto.merkle_root(items) == mth(items) == crypto.history_root(items) # --- inclusion and consistency proofs ----------------------------------------------------------- PROOFS = vector_cases("proofs") def test_proof_vectors_cover_every_kind(): assert {c["kind"] for c in PROOFS} == {"root", "inclusion", "consistency"} @pytest.mark.parametrize( "case", [c for c in PROOFS if c["kind"] == "root"], ids=lambda c: c["id"] ) def test_root_vectors(case): assert crypto.history_root(case["items"]) == case["root"] @pytest.mark.parametrize( "case", [c for c in PROOFS if c["kind"] == "inclusion"], ids=lambda c: c["id"] ) def test_inclusion_vectors(case): items, index = case["items"], case["index"] assert crypto.history_root(items) == case["root"] assert crypto.inclusion_path(items, index) == case["path"] assert crypto.leaf_hash(items[index]) == case["leaf"] assert crypto.verify_inclusion( case["root"], case["leaf"], index, case["size"], case["path"] ) if case["size"] > 1: other = (index + 1) % case["size"] assert not crypto.verify_inclusion( case["root"], case["leaf"], other, case["size"], case["path"] ) @pytest.mark.parametrize( "case", [c for c in PROOFS if c["kind"] == "consistency"], ids=lambda c: c["id"] ) def test_consistency_vectors(case): items, m = case["items"], case["from"] assert crypto.history_root(items[:m]) == case["from_root"] assert crypto.history_root(items) == case["to_root"] assert crypto.consistency_proof(items, m) == case["path"] assert crypto.verify_consistency( case["from_root"], case["to_root"], m, case["to"], case["path"] ) if m > 0: assert not crypto.verify_consistency( case["from_root"], "0" * 64, m, case["to"], case["path"] ) def make_items(n): return [ ["node", f"n{i}", hashlib.sha256(str(i).encode()).hexdigest()] for i in range(n) ] @pytest.mark.parametrize("index", [-1, 5]) def test_inclusion_path_outside_the_tree_is_refused(index): with pytest.raises(ValueError, match="outside the tree"): crypto.inclusion_path(make_items(5), index) def test_inclusion_path_of_an_empty_tree_is_refused(): with pytest.raises(ValueError, match="outside the tree"): crypto.inclusion_path([], 0) @pytest.mark.parametrize("m", [-1, 6]) def test_consistency_proof_beyond_the_tree_is_refused(m): with pytest.raises(ValueError, match="outside the tree"): crypto.consistency_proof(make_items(5), m) def test_consistency_proof_is_empty_for_the_empty_prefix_and_the_whole_tree(): items = make_items(6) assert crypto.consistency_proof(items, 0) == [] assert crypto.consistency_proof(items, 6) == [] @given(TREES) @PROPS def test_every_inclusion_proof_verifies_and_only_at_its_own_index(items): root, size = crypto.history_root(items), len(items) for i, item in enumerate(items): path = crypto.inclusion_path(items, i) leaf = crypto.leaf_hash(item) assert crypto.verify_inclusion(root, leaf, i, size, path) assert not crypto.verify_inclusion(SHA256_EMPTY, leaf, i, size, path) if size > 1 and len(set(map(str, items))) == size: assert not crypto.verify_inclusion(root, leaf, (i + 1) % size, size, path) @given(TREES) @PROPS def test_every_prefix_is_consistent_with_the_whole(items): n, root = len(items), crypto.history_root(items) for m in range(n + 1): proof = crypto.consistency_proof(items, m) root_m = crypto.history_root(items[:m]) assert crypto.verify_consistency(root_m, root, m, n, proof) if 0 < m < n: assert not crypto.verify_consistency(SHA256_EMPTY, root, m, n, proof) assert not crypto.verify_consistency(root_m, SHA256_EMPTY, m, n, proof) @pytest.mark.parametrize( ("index", "size"), [(-1, 4), (4, 4), (0, 0)], ids=["negative", "at-size", "empty"] ) def test_inclusion_outside_the_tree_does_not_verify(index, size): items = make_items(4) leaf = crypto.leaf_hash(items[0]) root = crypto.history_root(items) assert not crypto.verify_inclusion(root, leaf, index, size, []) def test_inclusion_with_a_path_too_long_or_too_short_does_not_verify(): items = make_items(4) root = crypto.history_root(items) path = crypto.inclusion_path(items, 2) leaf = crypto.leaf_hash(items[2]) assert crypto.verify_inclusion(root, leaf, 2, 4, path) assert not crypto.verify_inclusion(root, leaf, 2, 4, [*path, path[0]]) assert not crypto.verify_inclusion(root, leaf, 2, 4, path[:-1]) @pytest.mark.parametrize("path", [["zz"], [None], "not-a-list", None, 7], ids=repr) def test_inclusion_verification_never_raises_on_garbage(path): items = make_items(3) assert not crypto.verify_inclusion( crypto.history_root(items), crypto.leaf_hash(items[0]), 0, 3, path ) def test_inclusion_verification_never_raises_on_a_garbage_leaf(): assert not crypto.verify_inclusion("00" * 32, "not hex", 0, 1, []) def test_consistency_of_the_empty_prefix_needs_the_empty_root_and_no_proof(): root = crypto.history_root(make_items(3)) assert crypto.verify_consistency(crypto.EMPTY_ROOT, root, 0, 3, []) assert not crypto.verify_consistency(crypto.EMPTY_ROOT, root, 0, 3, [root]) assert not crypto.verify_consistency(root, root, 0, 3, []) def test_consistency_of_equal_sizes_needs_equal_roots_and_no_proof(): root = crypto.history_root(make_items(3)) other = crypto.history_root(make_items(4)) assert crypto.verify_consistency(root, root, 3, 3, []) assert not crypto.verify_consistency(root, other, 3, 3, []) assert not crypto.verify_consistency(root, root, 3, 3, [root]) @pytest.mark.parametrize( ("m", "n"), [(4, 3), (-1, 3)], ids=["prefix-longer", "negative-prefix"] ) def test_consistency_with_impossible_sizes_does_not_verify(m, n): root = crypto.history_root(make_items(3)) assert not crypto.verify_consistency(root, root, m, n, [root]) def test_consistency_without_a_proof_does_not_verify(): items = make_items(5) assert not crypto.verify_consistency( crypto.history_root(items[:2]), crypto.history_root(items), 2, 5, [] ) def test_consistency_with_extra_proof_hashes_does_not_verify(): items = make_items(5) proof = crypto.consistency_proof(items, 3) args = (crypto.history_root(items[:3]), crypto.history_root(items), 3, 5) assert crypto.verify_consistency(*args, proof) assert not crypto.verify_consistency(*args, [*proof, proof[0]]) assert not crypto.verify_consistency(*args, proof[:-1]) @pytest.mark.parametrize("proof", [["zz"], [None], None], ids=repr) def test_consistency_verification_never_raises_on_garbage(proof): items = make_items(4) assert not crypto.verify_consistency( crypto.history_root(items[:1]), crypto.history_root(items), 1, 4, proof ) # --- Ed25519 ------------------------------------------------------------------------------------ RFC8032 = vector_cases("signatures")[0] def test_ed25519_matches_rfc_8032_test_1(): secret = bytes.fromhex(RFC8032["secret"]) message = RFC8032["message"].encode() assert crypto.ed25519_public(secret).hex() == RFC8032["public"] signature = crypto.ed25519_sign(secret, message) assert signature.hex() == RFC8032["signature"] assert crypto.ed25519_verify(bytes.fromhex(RFC8032["public"]), message, signature) def test_ed25519_rejects_a_changed_message_signature_or_key(): secret = bytes.fromhex(RFC8032["secret"]) public = crypto.ed25519_public(secret) signature = crypto.ed25519_sign(secret, b"message") flipped = bytes([signature[0] ^ 1]) + signature[1:] other = crypto.ed25519_public(bytes(32)) assert crypto.ed25519_verify(public, b"message", signature) assert not crypto.ed25519_verify(public, b"messagf", signature) assert not crypto.ed25519_verify(public, b"message", flipped) assert not crypto.ed25519_verify(other, b"message", signature) @pytest.mark.parametrize( ("public", "signature"), [(bytes(31), bytes(64)), (bytes(33), bytes(64)), (bytes(32), bytes(63))], ids=["short-key", "long-key", "short-signature"], ) def test_ed25519_rejects_wrong_lengths(public, signature): assert not crypto.ed25519_verify(public, b"message", signature) def test_ed25519_rejects_bytes_that_encode_no_point(): assert not crypto.ed25519_verify(b"\xff" * 32, b"message", bytes(64)) @given(st.binary(min_size=32, max_size=32), st.binary(max_size=64)) @PROPS def test_ed25519_signatures_verify_and_are_deterministic(secret, message): public = crypto.ed25519_public(secret) signature = crypto.ed25519_sign(secret, message) assert len(public) == 32 assert len(signature) == 64 assert signature == crypto.ed25519_sign(secret, message) assert crypto.ed25519_verify(public, message, signature) assert not crypto.ed25519_verify(public, message + b"\x00", signature) # --- did:key -------------------------------------------------------------------------------------- @pytest.mark.parametrize( "case", [c for c in vector_cases("signatures") if "did" in c], ids=lambda c: c["id"], ) def test_did_key_vectors(case): did = crypto.did_key(case["scheme"], bytes.fromhex(case["public"])) assert did == case["did"] def test_did_key_for_an_unknown_scheme_is_refused(): with pytest.raises(ValueError, match="no multicodec code for rsa"): crypto.did_key("rsa", bytes(32)) def test_did_key_decodes_to_the_multicodec_prefix_and_the_key(): public = crypto.ed25519_public(bytes(32)) did = crypto.did_key("ed25519", public) assert did.startswith("did:key:z6Mk") assert base58_decode(did.removeprefix("did:key:z")) == b"\xed\x01" + public def test_ml_dsa_multicodec_is_a_two_byte_varint(): did = crypto.did_key("ml-dsa-65", b"\x07" * 4) assert base58_decode(did.removeprefix("did:key:z")) == b"\x87\x24" + b"\x07" * 4 @pytest.mark.parametrize( ("data", "text"), [ (b"", ""), (b"\x00", "1"), (b"\x00\x00\x01", "112"), (b"hello world", "StV1DL6CwTryKyV"), (b"\x00\x00hello", "11Cn8eVZg"), ], ) def test_base58btc_known_encodings(data, text): assert crypto.base58btc(data) == text @given(st.binary(max_size=40)) @PROPS def test_base58btc_round_trips(data): text = crypto.base58btc(data) assert set(text) <= set(crypto.BASE58) assert base58_decode(text) == data