diff --git a/changelog.d/+sidecar-prove-docs.doc.md b/changelog.d/+sidecar-prove-docs.doc.md new file mode 100644 index 0000000..d773a33 --- /dev/null +++ b/changelog.d/+sidecar-prove-docs.doc.md @@ -0,0 +1 @@ +The sidecar reference and the log how-to describe `prove` and `verify-proof`, including a proof that still checks after a later snapshot. \ No newline at end of file diff --git a/changelog.d/+sidecar-prove.feature.md b/changelog.d/+sidecar-prove.feature.md new file mode 100644 index 0000000..cb7349c --- /dev/null +++ b/changelog.d/+sidecar-prove.feature.md @@ -0,0 +1 @@ +`rfc9162-sidecar prove` writes a checkpoint and an inclusion proof for one path, and `verify-proof` checks that proof, and an optional blob file, without opening the log. diff --git a/crates/rfc9162-log/src/bin/sidecar.rs b/crates/rfc9162-log/src/bin/sidecar.rs index d59ba17..28b5794 100644 --- a/crates/rfc9162-log/src/bin/sidecar.rs +++ b/crates/rfc9162-log/src/bin/sidecar.rs @@ -12,6 +12,8 @@ //! rfc9162-sidecar blob --dir DIR HEX [--out FILE] //! rfc9162-sidecar include --dir DIR PATH --note FILE --trusted KEYLINE... [--meta K=V]... //! rfc9162-sidecar verify --dir DIR --trusted KEYLINE... [--path REL_PATH] +//! rfc9162-sidecar prove --dir DIR --path PATH [--index N] +//! rfc9162-sidecar verify-proof --proof FILE --trusted KEYLINE... [--blob-file FILE] //! ``` //! //! Status 0 is done, 2 is a command line this binary does not take, 1 is a @@ -23,6 +25,8 @@ use std::io::{self, Read, Write}; use std::path::{Path, PathBuf}; use std::process::ExitCode; +use sha2::{Digest, Sha256}; + use ed25519_dalek::pkcs8::DecodePrivateKey; use ed25519_dalek::SigningKey; use rfc9162_log::{sidecar::sidecar_keys, store::tiles_keys, Change, Op, Sidecar}; @@ -68,12 +72,21 @@ enum Command { trusted: Vec, path: Option, }, + Prove { + path: String, + index: Option, + }, + VerifyProof { + proof: PathBuf, + trusted: Vec, + blob_file: Option, + }, } fn usage(what: &str) -> ExitCode { eprintln!("rfc9162-sidecar: {what}"); eprintln!( - "usage: rfc9162-sidecar COMMAND --dir DIR [...]; commands: init sync snapshot history tree diff blob include verify" + "usage: rfc9162-sidecar COMMAND --dir DIR [...]; commands: init sync snapshot history tree diff blob include verify prove verify-proof" ); ExitCode::from(2) } @@ -81,8 +94,17 @@ fn usage(what: &str) -> ExitCode { fn parse(argv: Vec) -> Result { let mut it = argv.into_iter(); let name = it.next().ok_or("a command is needed")?; - let (mut dir, mut key, mut origin, mut note, mut out, mut verify_path) = - (None, None, None, None, None, None); + let ( + mut dir, + mut key, + mut origin, + mut note, + mut out, + mut verify_path, + mut index, + mut proof, + mut blob_file, + ) = (None, None, None, None, None, None, None, None, None); let (mut skip, mut trusted, mut meta, mut rest) = (Vec::new(), Vec::new(), BTreeMap::new(), Vec::new()); while let Some(arg) = it.next() { @@ -94,6 +116,9 @@ fn parse(argv: Vec) -> Result { "--note" => note = Some(PathBuf::from(value("--note")?)), "--out" => out = Some(PathBuf::from(value("--out")?)), "--path" => verify_path = Some(value("--path")?), + "--index" => index = Some(value("--index")?), + "--proof" => proof = Some(PathBuf::from(value("--proof")?)), + "--blob-file" => blob_file = Some(PathBuf::from(value("--blob-file")?)), "--skip" => skip.push(value("--skip")?), "--trusted" => trusted.push(value("--trusted")?), "--meta" => { @@ -163,10 +188,38 @@ fn parse(argv: Vec) -> Result { path: verify_path, } } + "prove" => { + let path = verify_path + .or_else(|| rest.first().cloned()) + .ok_or("prove needs --path PATH")?; + Command::Prove { + path, + index: index.as_deref().map(|t| number("INDEX", t)).transpose()?, + } + } + "verify-proof" => { + let proof = proof.ok_or("--proof FILE is needed")?; + if trusted.is_empty() { + return Err("--trusted KEYLINE is needed at least once".to_string()); + } + let trusted = trusted + .iter() + .map(|line| Verifier::parse(line).map_err(|e| format!("--trusted {line:?}: {e}"))) + .collect::, _>>()?; + Command::VerifyProof { + proof, + trusted, + blob_file, + } + } other => return Err(format!("unknown command {other}")), }; + let dir = match &command { + Command::VerifyProof { .. } => dir.unwrap_or_default(), + _ => dir.ok_or("--dir DIR is needed")?, + }; Ok(Args { - dir: dir.ok_or("--dir DIR is needed")?, + dir, command, out, skip, @@ -183,8 +236,19 @@ fn run(args: &Args) -> Result<(), String> { let dir = args.dir.as_path(); let out = io::stdout(); let mut out = out.lock(); - if let Command::Verify { trusted, path } = &args.command { - return verify(dir, trusted, path.as_deref(), &mut out); + match &args.command { + Command::Verify { trusted, path } => { + return verify(dir, trusted, path.as_deref(), &mut out); + } + Command::Prove { path, index } => return prove(dir, path, *index, &mut out), + Command::VerifyProof { + proof, + trusted, + blob_file, + } => { + return verify_proof(proof, trusted, blob_file.as_deref(), &mut out); + } + _ => {} } let store = open(dir)?; let mut sidecar = Sidecar::open(&store).map_err(|e| format!("sidecar: {e}"))?; @@ -294,11 +358,233 @@ fn run(args: &Args) -> Result<(), String> { .map_err(|e| format!("include: {e}"))?; writeln!(out, "included {path} at {index}").ok(); } - Command::Verify { .. } => unreachable!("verify returns early"), + Command::Verify { .. } | Command::Prove { .. } | Command::VerifyProof { .. } => { + unreachable!("verify, prove and verify-proof return early") + } } Ok(()) } +fn prove(dir: &Path, path: &str, index: Option, out: &mut impl Write) -> Result<(), String> { + let store = open(dir)?; + let checkpoint_bytes = store + .get("checkpoint") + .map_err(|e| format!("prove: read checkpoint: {e}"))? + .ok_or("prove: no signed checkpoint in sidecar pack".to_string())?; + let checkpoint_text = String::from_utf8(checkpoint_bytes) + .map_err(|_| "prove: checkpoint is not UTF-8".to_string())?; + let note = Note::parse(&checkpoint_text).map_err(|e| format!("prove: note: {e}"))?; + let checkpoint = + Checkpoint::parse(¬e.text).map_err(|e| format!("prove: checkpoint: {e}"))?; + let keys = sidecar_keys(); + let reader = Reader::at(&store, checkpoint.size, checkpoint.root, tiles_keys(&keys)) + .map_err(|e| format!("prove: open reader at checkpoint: {e}"))?; + let key = format!("path={path}"); + let hits = reader + .find(key.as_bytes()) + .map_err(|e| format!("prove: find {path}: {e}"))?; + let index = match index { + Some(index) => { + if !hits.contains(&index) { + return Err(format!("prove: index {index} is not an entry for {path}")); + } + if index >= checkpoint.size { + return Err(format!( + "prove: index {index} is outside checkpoint size {}", + checkpoint.size + )); + } + index + } + None => hits + .iter() + .copied() + .filter(|index| *index < checkpoint.size) + .max() + .ok_or(format!( + "prove: no entry for {path} at checkpoint size {}", + checkpoint.size + ))?, + }; + let bytes = reader + .get(index) + .map_err(|e| format!("prove: read entry {index}: {e}"))? + .ok_or(format!("prove: no entry at index {index}"))?; + let change: Change = serde_json::from_slice(&bytes) + .map_err(|_| format!("prove: entry {index} is not a sidecar change"))?; + if change.path != path { + return Err(format!( + "prove: entry {index} records {}, not {path}", + change.path + )); + } + let inclusion = reader + .inclusion(index) + .map_err(|e| format!("prove: inclusion {index}: {e}"))? + .ok_or(format!("prove: no inclusion proof for index {index}"))?; + let entry = + String::from_utf8(bytes).map_err(|_| format!("prove: entry {index} is not UTF-8"))?; + let mut obj = serde_json::Map::new(); + if let Some(blob) = &change.blob { + obj.insert("blob".into(), serde_json::Value::String(blob.clone())); + } + obj.insert( + "checkpoint".into(), + serde_json::Value::String(note.to_text()), + ); + obj.insert("entry".into(), serde_json::Value::String(entry)); + obj.insert( + "inclusion".into(), + serde_json::Value::Array( + inclusion + .iter() + .map(|hash| serde_json::Value::String(rfc9162::hex(hash))) + .collect(), + ), + ); + obj.insert("index".into(), serde_json::json!(index)); + obj.insert( + "op".into(), + serde_json::Value::String( + match change.op { + Op::Put => "put", + Op::Delete => "delete", + Op::Checkpoint => "checkpoint", + } + .to_string(), + ), + ); + obj.insert( + "origin".into(), + serde_json::Value::String(checkpoint.origin), + ); + obj.insert("path".into(), serde_json::Value::String(change.path)); + obj.insert( + "root".into(), + serde_json::Value::String(rfc9162::hex(&checkpoint.root)), + ); + obj.insert("size".into(), serde_json::json!(checkpoint.size)); + let text = serde_json::to_string_pretty(&serde_json::Value::Object(obj)) + .map_err(|e| format!("prove: {e}"))?; + writeln!(out, "{text}").ok(); + Ok(()) +} + +fn verify_proof( + proof: &Path, + trusted: &[Verifier], + blob_file: Option<&Path>, + out: &mut impl Write, +) -> Result<(), String> { + let text = std::fs::read_to_string(proof) + .map_err(|e| format!("verify-proof: read {}: {e}", proof.display()))?; + let value: serde_json::Value = + serde_json::from_str(&text).map_err(|e| format!("verify-proof: {e}"))?; + let field = |name: &str| { + value + .get(name) + .and_then(|item| item.as_str()) + .map(str::to_string) + .ok_or(format!("verify-proof: {name} must be a string")) + }; + let checkpoint_text = field("checkpoint")?; + let entry = field("entry")?; + let origin = field("origin")?; + let path = field("path")?; + let root = field("root")?; + let op = field("op")?; + let number = |name: &str| { + value + .get(name) + .and_then(serde_json::Value::as_u64) + .ok_or(format!("verify-proof: {name} must be a number")) + }; + let index = number("index")?; + let size = number("size")?; + let note = Note::parse(&checkpoint_text).map_err(|e| format!("verify-proof: note: {e}"))?; + let signed = + checkpoint::verify(¬e, trusted).map_err(|e| format!("verify-proof: checkpoint: {e}"))?; + let checkpoint = + Checkpoint::parse(¬e.text).map_err(|e| format!("verify-proof: checkpoint: {e}"))?; + let root_hex = rfc9162::hex(&checkpoint.root); + if origin != checkpoint.origin || size != checkpoint.size || root != root_hex { + return Err( + "verify-proof: origin, size or root does not match the checkpoint note".to_string(), + ); + } + let inclusion = value + .get("inclusion") + .and_then(serde_json::Value::as_array) + .ok_or("verify-proof: inclusion must be an array")?; + let mut path_hashes = Vec::with_capacity(inclusion.len()); + for hash in inclusion { + let text = hash + .as_str() + .ok_or("verify-proof: an inclusion hash must be a string")?; + path_hashes.push(rfc9162::from_hex(text).ok_or(format!( + "verify-proof: inclusion hash {text:?} is not 32 bytes" + ))?); + } + let proves = rfc9162::verify_inclusion( + &rfc9162::leaf_hash(entry.as_bytes()), + index as usize, + size as usize, + &path_hashes, + &root_hex, + ); + if !proves { + return Err(format!( + "verify-proof: inclusion for {path} at index {index} does not verify against checkpoint root" + )); + } + let change: Change = serde_json::from_slice(entry.as_bytes()) + .map_err(|_| "verify-proof: entry is not a sidecar change".to_string())?; + if change.path != path { + return Err(format!( + "verify-proof: entry records {}, not {path}", + change.path + )); + } + let recorded = match change.op { + Op::Put => "put", + Op::Delete => "delete", + Op::Checkpoint => "checkpoint", + }; + if op != recorded { + return Err(format!("verify-proof: entry op is {recorded}, not {op}")); + } + if let Some(blob) = value.get("blob").and_then(serde_json::Value::as_str) { + if change.blob.as_deref() != Some(blob) { + return Err("verify-proof: entry blob does not match the proof".to_string()); + } + } else if change.blob.is_some() { + return Err("verify-proof: entry names a blob the proof omits".to_string()); + } + if let Some(file) = blob_file { + let blob = value + .get("blob") + .and_then(serde_json::Value::as_str) + .ok_or("verify-proof: --blob-file needs a blob in the proof")?; + let bytes = std::fs::read(file) + .map_err(|e| format!("verify-proof: read {}: {e}", file.display()))?; + let digest: [u8; 32] = Sha256::digest(&bytes).into(); + let hex = rfc9162::hex(&digest); + if hex != blob { + return Err(format!( + "verify-proof: {} sha256 {hex} does not match blob {blob}", + file.display() + )); + } + } + writeln!( + out, + "verified proof {path} index {index} size {size} root {root_hex} by {} trusted key(s)", + signed.len() + ) + .ok(); + Ok(()) +} + fn verify( dir: &Path, trusted: &[Verifier], diff --git a/crates/rfc9162-log/tests/sidecar_cli.rs b/crates/rfc9162-log/tests/sidecar_cli.rs index cd7ec2b..d5a7d85 100644 --- a/crates/rfc9162-log/tests/sidecar_cli.rs +++ b/crates/rfc9162-log/tests/sidecar_cli.rs @@ -275,3 +275,119 @@ fn a_command_line_it_does_not_take_is_status_2_and_opens_nothing() { } assert!(wrong.is_empty(), "{}", wrong.join("\n")); } + +#[test] +fn prove_writes_a_proof_that_survives_a_later_snapshot() { + let dir = tempfile::tempdir().unwrap(); + let project = dir.path().join("etc"); + std::fs::create_dir_all(&project).unwrap(); + let p = project.to_str().unwrap(); + write(&project, "hosts", b"127.0.0.1 localhost\n"); + let key = dir.path().join("sidecar.pem"); + std::fs::write( + &key, + SigningKey::from_bytes(&[4u8; 32]) + .to_pkcs8_pem(LineEnding::LF) + .unwrap() + .as_bytes(), + ) + .unwrap(); + let k = key.to_str().unwrap(); + ok(&cli(&["sync", "--dir", p])); + ok(&cli(&[ + "snapshot", + "--dir", + p, + "--key", + k, + "--origin", + "example.org/etc", + ])); + let trusted = Signer::new("example.org/etc", SigningKey::from_bytes(&[4u8; 32])) + .unwrap() + .verifier() + .to_text(); + let proof_text = ok(&cli(&["prove", "--dir", p, "--path", "hosts"])); + let proof: serde_json::Value = serde_json::from_str(&proof_text).unwrap(); + assert_eq!(proof["path"], "hosts"); + assert_eq!(proof["op"], "put"); + assert!(proof["inclusion"].as_array().is_some()); + assert!(proof["checkpoint"] + .as_str() + .unwrap() + .contains("example.org/etc")); + let proof_path = dir.path().join("proof.json"); + std::fs::write(&proof_path, &proof_text).unwrap(); + let hosts = project.join("hosts"); + let checked = ok(&cli(&[ + "verify-proof", + "--proof", + proof_path.to_str().unwrap(), + "--trusted", + trusted.as_str(), + "--blob-file", + hosts.to_str().unwrap(), + ])); + assert!(checked.contains("verified proof hosts index "), "{checked}"); + + write(&project, "issue", b"later\n"); + ok(&cli(&["sync", "--dir", p])); + ok(&cli(&[ + "snapshot", + "--dir", + p, + "--key", + k, + "--origin", + "example.org/etc", + ])); + let again = ok(&cli(&[ + "verify-proof", + "--proof", + proof_path.to_str().unwrap(), + "--trusted", + trusted.as_str(), + "--blob-file", + hosts.to_str().unwrap(), + ])); + assert!(again.contains("verified proof hosts"), "{again}"); + + let root = proof["root"].as_str().unwrap(); + let tampered = proof_text.replacen(root, &"0".repeat(root.len()), 1); + let bad = dir.path().join("bad.json"); + std::fs::write(&bad, tampered).unwrap(); + let output = cli(&[ + "verify-proof", + "--proof", + bad.to_str().unwrap(), + "--trusted", + trusted.as_str(), + ]); + assert_eq!(output.status.code(), Some(1), "{output:?}"); + + let other = dir.path().join("other"); + std::fs::write(&other, b"not the hosts file\n").unwrap(); + let mismatch = cli(&[ + "verify-proof", + "--proof", + proof_path.to_str().unwrap(), + "--trusted", + trusted.as_str(), + "--blob-file", + other.to_str().unwrap(), + ]); + assert_eq!(mismatch.status.code(), Some(1)); + assert!( + String::from_utf8_lossy(&mismatch.stderr).contains("does not match blob"), + "{}", + String::from_utf8_lossy(&mismatch.stderr) + ); + + assert_eq!(cli(&["prove", "--path", "hosts"]).status.code(), Some(2)); + assert_eq!( + cli(&["verify-proof", "--trusted", trusted.as_str()]) + .status + .code(), + Some(2) + ); +} diff --git a/docs/src/howto/rfc9162-log.md b/docs/src/howto/rfc9162-log.md index ee39bd3..41181ce 100644 --- a/docs/src/howto/rfc9162-log.md +++ b/docs/src/howto/rfc9162-log.md @@ -92,3 +92,5 @@ The second sync appends the new and changed paths and the deletion at indexes 3, The command reference is the [sidecar page](../reference/sidecar.md). Use `verify --trusted KEYLINE` to check the signed checkpoint offline. Add `--path REL_PATH` to verify an inclusion proof for that path against the same trusted checkpoint. + +`prove --path REL_PATH` prints a JSON object that carries the checkpoint note, the entry and the inclusion path, so the proof still checks after another snapshot replaces `pack/checkpoint`. `verify-proof --proof FILE --trusted KEYLINE` checks that object without opening the log. `--blob-file FILE` also checks that the file's SHA-256 is the blob named in the object. `--index N` on `prove` selects one entry when the path has several. diff --git a/docs/src/install/linux.md b/docs/src/install/linux.md index e7474b4..ccc711a 100644 --- a/docs/src/install/linux.md +++ b/docs/src/install/linux.md @@ -43,7 +43,7 @@ With no arguments the binary exits 2 and prints: ```text rfc9162-sidecar: a command is needed -usage: rfc9162-sidecar COMMAND --dir DIR [...]; commands: init sync snapshot history tree diff blob include +usage: rfc9162-sidecar COMMAND --dir DIR [...]; commands: init sync snapshot history tree diff blob include verify prove verify-proof ``` The [log how-to](../howto/rfc9162-log.md) has a full transcript. diff --git a/docs/src/reference/sidecar.md b/docs/src/reference/sidecar.md index fe87436..b10a672 100644 --- a/docs/src/reference/sidecar.md +++ b/docs/src/reference/sidecar.md @@ -1,6 +1,6 @@ # rfc9162-sidecar -The binary in the `rfc9162-log` crate. Its rustdoc page is [`rfc9162_sidecar`](../api/rfc9162_sidecar/index.html). The pack for `--dir DIR` is `DIR/.sidecar/pack`. Each command opens that pack, holds the writer lock while it runs, and prints one line per result. Exit status 0 means the command finished. Exit status 2 means the command line is rejected; it is checked before the pack is opened, so nothing is created. Exit status 1 means the store or a proof failed. +The binary in the `rfc9162-log` crate. Its rustdoc page is [`rfc9162_sidecar`](../api/rfc9162_sidecar/index.html). The pack for `--dir DIR` is `DIR/.sidecar/pack`. Each command that names a directory opens that pack, holds the writer lock while it runs, and prints one line per result. `verify-proof` reads a proof file and does not open a pack. Exit status 0 means the command finished. Exit status 2 means the command line is rejected; it is checked before the pack is opened, so nothing is created. Exit status 1 means the store or a proof failed. ```text rfc9162-sidecar init --dir DIR @@ -12,6 +12,8 @@ rfc9162-sidecar diff --dir DIR FROM TO rfc9162-sidecar blob --dir DIR HEX [--out FILE] rfc9162-sidecar include --dir DIR PATH --note FILE --trusted KEYLINE... [--meta K=V]... rfc9162-sidecar verify --dir DIR --trusted KEYLINE... [--path REL_PATH] +rfc9162-sidecar prove --dir DIR --path PATH [--index N] +rfc9162-sidecar verify-proof --proof FILE --trusted KEYLINE... [--blob-file FILE] ``` `--meta` repeats. The value is `K=V` and is stored on the change. `--skip` repeats and names a top-level directory entry that `sync` leaves alone. The binary always skips `.sidecar`. `--key` is a PKCS#8 PEM Ed25519 key (`-----BEGIN PRIVATE KEY-----`). `--trusted` repeats and is a verifier line, `name+keyid+base64`. `--note` is the signed checkpoint text of a child log. @@ -27,6 +29,8 @@ rfc9162-sidecar verify --dir DIR --trusted KEYLINE... [--path REL_PATH] | `blob` | the bytes of blob `HEX` on stdout, or written to `--out` | | `include` | `included PATH at INDEX` | | `verify` | `verified checkpoint ORIGIN size SIZE root HEX by N trusted key(s)` and, with `--path`, `verified inclusion PATH index INDEX op OP steps N` | +| `prove` | one JSON object: the checkpoint note, the entry bytes, the inclusion path, and the blob hash of a put | +| `verify-proof` | `verified proof PATH index INDEX size SIZE root HEX by N trusted key(s)` | A history, tree or diff line for a put is: @@ -38,3 +42,7 @@ A delete omits the blob and the size. A checkpoint line carries the child's orig `snapshot` seals the unsealed tail when there is one, then signs the log. `include` verifies the note against the trusted keys. A child note with a smaller size, or the same size and another root, is refused. `verify` checks the signed checkpoint in `DIR/.sidecar/pack/checkpoint` against `--trusted` keys, then opens the log at that checkpoint size and root. With `--path`, it verifies the latest entry for that path at the checkpoint with the reader's inclusion path. + +`prove` reads that same checkpoint and writes a JSON object for one path. `--index` selects an entry; without it, the object is the latest entry for the path whose index is below the checkpoint size. The object carries the checkpoint note, the exact entry bytes, the inclusion path as lowercase hex, and, for a put, the blob hash. A later `snapshot` replaces `pack/checkpoint`. The object still verifies, because it holds the note it was proved against. + +`verify-proof` checks that object. It does not read a log. `--trusted` is the verifier line of a key that signed the note, repeated when several keys are trusted. `--blob-file` checks that the file's SHA-256 is the object's blob hash. A note no trusted key signed, an inclusion path that does not meet the checkpoint root, or a blob that differs is exit status 1.