Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions changelog.d/+head-root-hex.doc.md
Original file line number Diff line number Diff line change
@@ -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".
46 changes: 44 additions & 2 deletions crates/rfc9162/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand Down Expand Up @@ -119,6 +121,8 @@ pub fn inclusion_proof(leaves: &[[u8; 32]], index: usize) -> Option<Vec<[u8; 32]
}

/// Whether `leaf` sits at `index` of a tree of `size` leaves with that root.
/// `root_hex` is the lower-case hex [`hex`] writes, as in [`Head::root`];
/// any other spelling of the root does not verify.
#[must_use]
pub fn verify_inclusion(
leaf: &[u8; 32],
Expand Down Expand Up @@ -190,7 +194,9 @@ fn subproof(leaves: &[[u8; 32]], old: usize, known: bool) -> 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,
Expand Down Expand Up @@ -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());
}
}
4 changes: 2 additions & 2 deletions docs/src/reference/rfc9162.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading