From f789b80f620159ea138da8c32b3c2e023fd942c5 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Mon, 16 Nov 2026 02:44:07 +0000 Subject: [PATCH] docs(rfc9162): a root is the lower-case hex that hex writes Head.root was documented as hex and the verify functions' roots not at all, but both verify functions compare the root they recompute with the given text as hex writes it, and from_hex refuses anything but 0-9 and a-f. An upper-case root verified nothing with no word why. Lower case stays the one form, since Head::material signs the root as text and a second spelling would be a second signed form of one head; the docs of Head.root and both verify functions now say so, and the reference page says lowercase. The code was right, so there is no failing test; a test pins that an upper-case root fails inclusion and both consistency paths. The verify_consistency doc named its path parameter nodes. --- changelog.d/+head-root-hex.doc.md | 2 ++ crates/rfc9162/src/lib.rs | 46 +++++++++++++++++++++++++++++-- docs/src/reference/rfc9162.md | 4 +-- 3 files changed, 48 insertions(+), 4 deletions(-) create mode 100644 changelog.d/+head-root-hex.doc.md diff --git a/changelog.d/+head-root-hex.doc.md b/changelog.d/+head-root-hex.doc.md new file mode 100644 index 0000000..9427cfd --- /dev/null +++ b/changelog.d/+head-root-hex.doc.md @@ -0,0 +1,2 @@ +`rfc9162`: `Head.root`, `verify_inclusion` and `verify_consistency` say that a root is the lower-case hex `hex` writes: the same root in upper case does not verify, so a head has one form for `Head::material` to sign. +They said only "hex". diff --git a/crates/rfc9162/src/lib.rs b/crates/rfc9162/src/lib.rs index 209cce0..d4eaba5 100644 --- a/crates/rfc9162/src/lib.rs +++ b/crates/rfc9162/src/lib.rs @@ -72,7 +72,9 @@ fn split_point(width: usize) -> usize { pub struct Head { /// Number of entries the root covers. pub size: usize, - /// Merkle root, hex. + /// Merkle root, in the lower-case hex [`hex`] writes. The verify + /// functions compare roots as that text, so the same root in upper case + /// does not verify, and [`Head::material`] covers it as written. pub root: String, } @@ -119,6 +121,8 @@ pub fn inclusion_proof(leaves: &[[u8; 32]], index: usize) -> Option Vec<[u8; 32]> { } /// Whether the tree of `old` leaves with `old_root` is a prefix of the tree of -/// `new` leaves with `new_root`; both roots are recomputed from `nodes`. +/// `new` leaves with `new_root`; both roots are recomputed from `path`. Both +/// are the lower-case hex [`hex`] writes, as in [`Head::root`]; any other +/// spelling does not verify. #[must_use] pub fn verify_consistency( old: usize, @@ -468,4 +474,40 @@ mod tests { assert_eq!(head.root.len(), 64); assert!(inclusion_proof(&[], 0).is_none()); } + + /// A root is the lower-case hex a signature over [`Head::material`] + /// covers. The same root in upper case is not that head and verifies + /// nothing, on either path the consistency check takes. + #[test] + fn a_root_in_upper_case_does_not_verify() { + let all = leaves(12); + let later = Head::over(&all); + let upper = later.root.to_uppercase(); + assert_ne!(upper, later.root); + let path = inclusion_proof(&all, 3).expect("a path"); + assert!(verify_inclusion(&all[3], 3, 12, &path, &later.root)); + assert!(!verify_inclusion(&all[3], 3, 12, &path, &upper)); + for old in [4, 5] { + let earlier = Head::over(&all[..old]); + let proof = consistency_proof(&all, old).expect("a proof"); + let earlier_upper = earlier.root.to_uppercase(); + assert!(verify_consistency( + old, + &earlier.root, + 12, + &later.root, + &proof + )); + assert!(!verify_consistency( + old, + &earlier_upper, + 12, + &later.root, + &proof + )); + assert!(!verify_consistency(old, &earlier.root, 12, &upper, &proof)); + } + assert!(!verify_consistency(12, &upper, 12, &later.root, &[])); + assert!(from_hex(&upper).is_none()); + } } diff --git a/docs/src/reference/rfc9162.md b/docs/src/reference/rfc9162.md index 48a7876..7ab4d9e 100644 --- a/docs/src/reference/rfc9162.md +++ b/docs/src/reference/rfc9162.md @@ -8,10 +8,10 @@ | [`node_hash`](../api/rfc9162/fn.node_hash.html) | `SHA-256(0x01 \|\| left \|\| right)` | | [`root`](../api/rfc9162/fn.root.html) | Merkle root of a leaf slice, including the empty slice | | [`inclusion_proof`](../api/rfc9162/fn.inclusion_proof.html) | sibling hashes, innermost first, or `None` when the index is outside the slice | -| [`verify_inclusion`](../api/rfc9162/fn.verify_inclusion.html) | folds a path back to a hexadecimal root | +| [`verify_inclusion`](../api/rfc9162/fn.verify_inclusion.html) | folds a path back to a lowercase hexadecimal root | | [`consistency_proof`](../api/rfc9162/fn.consistency_proof.html) | nodes that recompute an old root and a new root, or `None` when `old` is 0 or past the slice | | [`verify_consistency`](../api/rfc9162/fn.verify_consistency.html) | checks that pair of roots | -| [`Head`](../api/rfc9162/struct.Head.html) | size and hexadecimal root; [`over`](../api/rfc9162/struct.Head.html#method.over) builds one; [`material`](../api/rfc9162/struct.Head.html#method.material) is the tab-separated signing input | +| [`Head`](../api/rfc9162/struct.Head.html) | size and lowercase hexadecimal root; [`over`](../api/rfc9162/struct.Head.html#method.over) builds one; [`material`](../api/rfc9162/struct.Head.html#method.material) is the tab-separated signing input | | [`hex`](../api/rfc9162/fn.hex.html) / [`from_hex`](../api/rfc9162/fn.from_hex.html) | lowercase hexadecimal for a 32-byte hash; `from_hex` accepts 64 digits in `0-9` and `a-f` | The [tree how-to](../howto/rfc9162.md) runs these functions. The [Merkle tree](../topics/merkle-tree.md), [inclusion](../topics/inclusion.md) and [consistency](../topics/consistency.md) pages describe the results.