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.