Files
paperspec/tests/test_crypto.py
T
alexmandClaude a8fc7237ae Add the pytest suite and fix the bugs it found
The suite takes its data from the vectors and fixtures: 3635 tests, 97.9% branch
coverage, and paperspec check and paperspec stress give the same results as before.
Fixed: receipts.verify_signature raised KeyError for a record without a format;
traces.DOC_TAG matched a tag followed by a line feed; paperspec load and paperspec check
left SQLite connections open; the site builder copied the output folder's subfolders into
itself.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B8cL4zN4XpaQF5cBtASzfq
2026-10-19 04:32:44 -04:00

443 lines
15 KiB
Python

# 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