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
1 change: 1 addition & 0 deletions changelog.d/+sidecar-verify.misc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Added `rfc9162-sidecar verify` for offline checkpoint verification against trusted signed-note key lines, with optional inclusion proof verification for a path at the signed checkpoint.
115 changes: 109 additions & 6 deletions crates/rfc9162-log/src/bin/sidecar.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
//! 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]
//! ```
//!
//! Status 0 is done, 2 is a command line this binary does not take, 1 is a
Expand All @@ -24,8 +25,8 @@ use std::process::ExitCode;

use ed25519_dalek::pkcs8::DecodePrivateKey;
use ed25519_dalek::SigningKey;
use rfc9162_log::{Op, Sidecar};
use rfc9162_tiles::{Checkpoint, Note, PackStore, Signer, Verifier};
use rfc9162_log::{sidecar::sidecar_keys, store::tiles_keys, Change, Op, Sidecar};
use rfc9162_tiles::{checkpoint, Checkpoint, Note, PackStore, Reader, Signer, TileStore, Verifier};

const SIDECAR_DIR: &str = ".sidecar";

Expand Down Expand Up @@ -63,18 +64,25 @@ enum Command {
note: PathBuf,
trusted: Vec<Verifier>,
},
Verify {
trusted: Vec<Verifier>,
path: Option<String>,
},
}

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");
eprintln!(
"usage: rfc9162-sidecar COMMAND --dir DIR [...]; commands: init sync snapshot history tree diff blob include verify"
);
ExitCode::from(2)
}

fn parse(argv: Vec<String>) -> Result<Args, String> {
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) = (None, None, None, None, None);
let (mut dir, mut key, mut origin, mut note, mut out, mut verify_path) =
(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() {
Expand All @@ -85,6 +93,7 @@ fn parse(argv: Vec<String>) -> Result<Args, String> {
"--origin" => origin = Some(value("--origin")?),
"--note" => note = Some(PathBuf::from(value("--note")?)),
"--out" => out = Some(PathBuf::from(value("--out")?)),
"--path" => verify_path = Some(value("--path")?),
"--skip" => skip.push(value("--skip")?),
"--trusted" => trusted.push(value("--trusted")?),
"--meta" => {
Expand Down Expand Up @@ -141,6 +150,19 @@ fn parse(argv: Vec<String>) -> Result<Args, String> {
trusted,
}
}
"verify" => {
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::<Result<Vec<_>, _>>()?;
Command::Verify {
trusted,
path: verify_path,
}
}
other => return Err(format!("unknown command {other}")),
};
Ok(Args {
Expand All @@ -159,10 +181,13 @@ fn open(dir: &Path) -> Result<PackStore, String> {

fn run(args: &Args) -> Result<(), String> {
let dir = args.dir.as_path();
let store = open(dir)?;
let mut sidecar = Sidecar::open(&store).map_err(|e| format!("sidecar: {e}"))?;
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);
}
let store = open(dir)?;
let mut sidecar = Sidecar::open(&store).map_err(|e| format!("sidecar: {e}"))?;
match &args.command {
Command::Init => {
writeln!(
Expand Down Expand Up @@ -269,6 +294,84 @@ 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"),
}
Ok(())
}

fn verify(
dir: &Path,
trusted: &[Verifier],
path: Option<&str>,
out: &mut impl Write,
) -> Result<(), String> {
let store = open(dir)?;
let checkpoint_bytes = store
.get("checkpoint")
.map_err(|e| format!("verify: read checkpoint: {e}"))?
.ok_or("verify: no signed checkpoint in sidecar pack".to_string())?;
let checkpoint_text = String::from_utf8(checkpoint_bytes)
.map_err(|_| "verify: checkpoint is not UTF-8".to_string())?;
let note = Note::parse(&checkpoint_text).map_err(|e| format!("verify: note: {e}"))?;
let signed = checkpoint::verify(&note, trusted).map_err(|e| format!("verify: {e}"))?;
let checkpoint =
Checkpoint::parse(&note.text).map_err(|e| format!("verify: checkpoint: {e}"))?;
let root_hex = rfc9162::hex(&checkpoint.root);
writeln!(
out,
"verified checkpoint {} size {} root {} by {} trusted key(s)",
checkpoint.origin,
checkpoint.size,
root_hex,
signed.len()
)
.ok();

if let Some(path) = path {
let keys = sidecar_keys();
let reader = Reader::at(&store, checkpoint.size, checkpoint.root, tiles_keys(&keys))
.map_err(|e| format!("verify: open reader at checkpoint: {e}"))?;
let key = format!("path={path}");
let hits = reader
.find(key.as_bytes())
.map_err(|e| format!("verify: find {path}: {e}"))?;
let index = hits.last().copied().ok_or(format!(
"verify: no entry for {path} at checkpoint size {}",
checkpoint.size
))?;
let bytes = reader
.get(index)
.map_err(|e| format!("verify: read entry {index}: {e}"))?
.ok_or(format!("verify: no entry at index {index}"))?;
let change: Change = serde_json::from_slice(&bytes)
.map_err(|_| format!("verify: entry {index} is not a sidecar change"))?;
let inclusion = reader
.inclusion(index)
.map_err(|e| format!("verify: inclusion {index}: {e}"))?
.ok_or(format!("verify: no inclusion proof for index {index}"))?;
let proves = rfc9162::verify_inclusion(
&rfc9162::leaf_hash(&bytes),
index as usize,
checkpoint.size as usize,
&inclusion,
&root_hex,
);
if !proves {
return Err(format!(
"verify: inclusion for {path} at index {index} does not verify against checkpoint root"
));
}
writeln!(
out,
"verified inclusion {path} index {index} op {} steps {}",
match change.op {
Op::Put => "put",
Op::Delete => "delete",
Op::Checkpoint => "checkpoint",
},
inclusion.len()
)
.ok();
}
Ok(())
}
Expand Down
123 changes: 122 additions & 1 deletion crates/rfc9162-log/tests/sidecar_cli.rs
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
//! The sidecar from the command line: init, sync, snapshot, history, tree,
//! diff and blob over a project directory, with a PEM signing key.
//! diff, blob and verify over a project directory, with a PEM signing key.

use ed25519_dalek::pkcs8::spki::der::pem::LineEnding;
use ed25519_dalek::pkcs8::EncodePrivateKey;
use ed25519_dalek::SigningKey;
use rfc9162_tiles::{PackStore, Signer, TileStore};
use std::path::Path;
use std::process::{Command, Output};

Expand Down Expand Up @@ -70,6 +71,21 @@ fn a_project_is_synced_snapshotted_and_read_back_from_the_shell() {
snap.starts_with("snapshot example.org/etc size 3 root "),
"{snap}"
);
let trusted = Signer::new("example.org/etc", SigningKey::from_bytes(&[7u8; 32]))
.unwrap()
.verifier()
.to_text();
let verify = ok(&cli(&[
"verify",
"--dir",
p,
"--trusted",
trusted.as_str(),
"--path",
"ssh/sshd_config",
]));
assert!(verify.contains("verified checkpoint example.org/etc size 3 root "));
assert!(verify.contains("verified inclusion ssh/sshd_config index 1 op put steps 2"));

write(&project, "ssh/sshd_config", b"Port 2222\n");
std::fs::remove_file(project.join("hosts")).unwrap();
Expand Down Expand Up @@ -114,6 +130,111 @@ fn a_project_is_synced_snapshotted_and_read_back_from_the_shell() {
);
}

#[test]
fn verify_fails_on_a_tampered_checkpoint_note() {
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(&[8u8; 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(&[8u8; 32]))
.unwrap()
.verifier()
.to_text();

{
let store = PackStore::open(project.join(".sidecar/pack")).unwrap();
let mut tampered = String::from_utf8(store.get("checkpoint").unwrap().unwrap()).unwrap();
tampered = tampered.replacen("example.org/etc", "example.org/evil", 1);
store.put("checkpoint", tampered.as_bytes()).unwrap();
}

let output = cli(&["verify", "--dir", p, "--trusted", trusted.as_str()]);
assert_eq!(output.status.code(), Some(1));
assert!(
String::from_utf8_lossy(&output.stderr).contains("signature does not verify"),
"{}",
String::from_utf8_lossy(&output.stderr)
);
}

#[test]
fn verify_fails_on_a_tampered_inclusion_source() {
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, "ssh/sshd_config", b"Port 22\n");
let key = dir.path().join("sidecar.pem");
std::fs::write(
&key,
SigningKey::from_bytes(&[9u8; 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(&[9u8; 32]))
.unwrap()
.verifier()
.to_text();

{
let store = PackStore::open(project.join(".sidecar/pack")).unwrap();
let entry_paths = store.list("tile/entries").unwrap();
let entry_path = entry_paths.first().expect("one bundle path");
store.put(entry_path, b"not a bundle").unwrap();
}

let output = cli(&[
"verify",
"--dir",
p,
"--trusted",
trusted.as_str(),
"--path",
"ssh/sshd_config",
]);
assert_eq!(output.status.code(), Some(1));
assert!(
String::from_utf8_lossy(&output.stderr).contains("verify: read entry")
|| String::from_utf8_lossy(&output.stderr).contains("verify: find ssh/sshd_config"),
"{}",
String::from_utf8_lossy(&output.stderr)
);
}

#[test]
fn a_command_line_it_does_not_take_is_status_2_and_opens_nothing() {
let dir = tempfile::tempdir().unwrap();
Expand Down
1 change: 1 addition & 0 deletions docs/src/howto/rfc9162-log.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,3 +91,4 @@ The second sync appends the new and changed paths and the deletion at indexes 3,
`include` reads the child's signed note. `show_checkpoint` in `docs/examples` prints the `checkpoint` record from a pack; a caller that already has the note file skips that step. The trusted line is the child's verifier. The command logs the note at index 0 under `stacks/2026`.

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.
3 changes: 3 additions & 0 deletions docs/src/reference/sidecar.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ rfc9162-sidecar tree --dir DIR [SIZE]
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]
```

`--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.
Expand All @@ -25,6 +26,7 @@ rfc9162-sidecar include --dir DIR PATH --note FILE --trusted KEYLINE... [--meta
| `diff` | changes with index in `FROM..TO`, `TO` clamped to the current size |
| `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` |

A history, tree or diff line for a put is:

Expand All @@ -35,3 +37,4 @@ INDEX put PATH BLOBHEX SIZE
A delete omits the blob and the size. A checkpoint line carries the child's origin. The fields are separated by tabs. The [log how-to](../howto/rfc9162-log.md) includes a transcript of each command.

`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.
Loading