#!/usr/bin/env python3 """Independent verifier for CAIN-42 Byzantine evidence. Imports nothing from CAIN: only the standard library and `cryptography`. It re-derives every hash and signature digest itself, so a node cannot make it accept evidence merely by claiming `chain_valid: true`. Checks 1. Evidence chain: every record's hash is recomputed; prev_hash links and indices must be contiguous from the all-zero genesis. Any edit, deletion or reorder is reported with the first bad index. 2. EQUIVOCATION_PROOF: both embedded messages must be signed by the accused node (Ed25519 against a public key YOU supply), be the same phase, view, sequence, cluster and epoch, and carry different request digests. Only then is the verdict PROVEN. 3. DEVIATION_PROOF: the accused's signed PREPARE plus the primary's signed proposal for a different digest, and the vote must NOT carry a valid leader proposal for its own digest (else the leader equivocated and the voter is innocent). Legacy proofs without the leader's proposal are reported NOT_INDEPENDENTLY_PROVABLE. KEYS must list every member: the primary of a view is sorted(members)[view % N]. Usage verify_byzantine_evidence.py EVIDENCE.json [--keys KEYS.json] [--json] EVIDENCE.json: the body of GET /api/v1/cluster/pbft/evidence KEYS.json: {"node_id": "", ...} obtained out of band. Without it, keys embedded in EVIDENCE.json are used and the report says so: that is NOT an independent check. Exit status: 0 if the chain verifies and no proof is invalid, 1 otherwise. """ import argparse import base64 import hashlib import json import sys from cryptography.hazmat.primitives.asymmetric import ed25519 GENESIS = "0" * 64 EVIDENCE_DOMAIN = "CAIN42/BYZANTINE-EVIDENCE/v1" def canonical(obj): return json.dumps(obj, sort_keys=True, separators=(",", ":"), default=str).encode("utf-8") def sha256_hex(obj): return hashlib.sha256(canonical(obj)).hexdigest() def record_hash(r): return sha256_hex({ "domain": EVIDENCE_DOMAIN, "idx": r["idx"], "event_type": r["event_type"], "node_id": r["node_id"], "view": r["view"], "sequence": r["sequence"], "payload": r["payload"], "prev_hash": r["prev_hash"], "recorded_at": r["recorded_at"], }) def verify_chain(records): prev = GENESIS for i, r in enumerate(records): if r.get("idx") != i: return False, f"index gap/reorder at position {i}" if r.get("prev_hash") != prev: return False, f"record {i}: prev_hash breaks the chain" if record_hash(r) != r.get("record_hash"): return False, f"record {i}: content does not match record_hash" prev = r["record_hash"] return True, f"{len(records)} records, root {prev}" def pbft_signed_digest(m): """The exact digest a PBFT node signs (PBFTMessage.compute_signing_payload).""" return sha256_hex({ "msg_type": m["msg_type"], "sender_id": m["sender_id"], "cluster_id": m["cluster_id"], "view": m["view"], "sequence": m["sequence"], "request_digest": m["request_digest"], "payload": json.loads(canonical(m["payload"])), "epoch": m["epoch"], "nonce": m["nonce"], "timestamp": round(m["timestamp"], 4), "engine_version": m["engine_version"], }) def signature_valid(m, pub_b64): try: sig = base64.b64decode(m["signature_b64"], validate=True) if base64.b64encode(sig).decode() != m["signature_b64"]: return False ed25519.Ed25519PublicKey.from_public_bytes(base64.b64decode(pub_b64)).verify( sig, pbft_signed_digest(m).encode("utf-8")) return True except Exception: return False def verify_equivocation(proof, keys): node = proof.get("node_id") a, b = proof.get("message_A"), proof.get("message_B") if not a or not b: return "INVALID", "proof does not embed both signed messages" if node not in keys: return "UNVERIFIABLE", f"no public key for {node!r}" for label, m in (("A", a), ("B", b)): if m.get("sender_id") != node: return "INVALID", f"message {label} is not from the accused node" if not signature_valid(m, keys[node]): return "INVALID", f"message {label}: signature does not verify under {node}'s key" same = all(a[k] == b[k] for k in ("msg_type", "view", "sequence", "cluster_id", "epoch")) if not same: return "INVALID", "messages differ in phase/view/sequence/cluster/epoch: not a conflict" if a["request_digest"] == b["request_digest"]: return "INVALID", "messages carry the same digest: not a conflict" return "PROVEN", (f"{node} signed {a['msg_type']} for view={a['view']} seq={a['sequence']} as " f"{a['request_digest'][:12]} and {b['request_digest'][:12]}") def _primary(view, keys): members = sorted(keys) return members[view % len(members)] if members else None def _is_leader_proposal(pp, view, seq, digest, keys): return (isinstance(pp, dict) and pp.get("msg_type") == "PRE_PREPARE" and pp.get("view") == view and pp.get("sequence") == seq and pp.get("request_digest") == digest and pp.get("sender_id") == _primary(view, keys) and pp["sender_id"] in keys and signature_valid(pp, keys[pp["sender_id"]])) def verify_deviation(proof, keys): """PROVEN only if: the accused signed a PREPARE for digest D'; the view's primary (sorted members[view % N], so KEYS must list every member) signed a proposal for D != D' at the same view/sequence; and the vote does NOT carry a valid leader-signed proposal for D' -- if it did, the LEADER equivocated and the voter is innocent.""" node, m, leader = proof.get("node_id"), proof.get("message"), proof.get("leader_message") if not m or node not in keys or m.get("sender_id") != node or not signature_valid(m, keys[node]): return "INVALID", "embedded vote missing or not validly signed by the accused node" if not leader: return ("NOT_INDEPENDENTLY_PROVABLE", "vote signature is genuine, but the leader's signed proposal is not in the proof (legacy format)") if m.get("msg_type") != "PREPARE": return "INVALID", "deviation proofs are only defined for PREPARE votes" if not _is_leader_proposal(leader, m["view"], m["sequence"], leader.get("request_digest"), keys): return "INVALID", "leader_message is not a proposal signed by the primary of that view" if leader["request_digest"] == m["request_digest"]: return "INVALID", "vote agrees with the leader proposal: no deviation" if leader.get("cluster_id") != m.get("cluster_id") or leader.get("epoch") != m.get("epoch"): return "INVALID", "vote and proposal are from different clusters/epochs" if _is_leader_proposal((m.get("payload") or {}).get("pre_prepare"), m["view"], m["sequence"], m["request_digest"], keys): return "INVALID", "vote carries a valid leader-signed proposal for its digest: the LEADER equivocated, not this node" return "PROVEN", (f"{node} voted {m['request_digest'][:12]} at view={m['view']} seq={m['sequence']} with no " f"leader proposal behind it; the leader proposed {leader['request_digest'][:12]}") def quorum_for(n): f = (n - 1) // 3 return (n + f + 2) // 2 def verify_checkpoint_certificate(cert, keys): """A stable checkpoint certificate is valid iff at least Q distinct members (Q from the size of KEYS, which must list every member) signed CHECKPOINT for exactly this (cluster, sequence, application_state_hash).""" if not isinstance(cert, dict) or cert.get("type") != "CHECKPOINT_CERTIFICATE": return "INVALID", "not a checkpoint certificate" q = quorum_for(len(keys)) good = set() for signer, m in (cert.get("signatures") or {}).items(): if (isinstance(m, dict) and m.get("msg_type") == "CHECKPOINT" and m.get("sender_id") == signer and signer in keys and m.get("sequence") == cert.get("sequence") and m.get("request_digest") == cert.get("application_state_hash") and m.get("cluster_id") == cert.get("cluster_id") and signature_valid(m, keys[signer])): good.add(signer) if len(good) < q: return "INVALID", f"only {len(good)} valid distinct member signatures, need {q}" return "PROVEN", f"seq={cert['sequence']} app={cert['application_state_hash'][:12]} signed by {sorted(good)}" def verify(evidence, keys=None): records = evidence.get("records", []) independent_keys = keys is not None keys = keys if keys is not None else evidence.get("peer_public_keys", {}) chain_ok, chain_detail = verify_chain(records) proofs = [] for r in records: if r["event_type"] == "EQUIVOCATION_PROOF": v, why = verify_equivocation(r["payload"], keys) elif r["event_type"] == "DEVIATION_PROOF": v, why = verify_deviation(r["payload"], keys) elif r["event_type"] == "STATE_DIVERGENCE": # Self-reported: the node's own state contradicted a certificate. # The certificate inside must itself be valid. v, why = verify_checkpoint_certificate(r["payload"].get("certificate"), keys) why = f"reporting node diverged from: {why}" else: continue proofs.append({"idx": r["idx"], "type": r["event_type"], "node_id": r["node_id"], "verdict": v, "detail": why}) ok = chain_ok and not any(p["verdict"] == "INVALID" for p in proofs) return { "verifier": "cain42 verify_byzantine_evidence v1 (no CAIN imports)", "node_claimed_chain_valid": evidence.get("chain_valid"), "chain_valid": chain_ok, "chain_detail": chain_detail, "keys_source": "supplied out of band" if independent_keys else "taken from the evidence itself (NOT independent: supply --keys)", "proofs": proofs, "ok": ok, } def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) ap.add_argument("evidence") ap.add_argument("--keys") ap.add_argument("--json", action="store_true") a = ap.parse_args() with open(a.evidence) as fh: evidence = json.load(fh) keys = None if a.keys: with open(a.keys) as fh: keys = json.load(fh) rep = verify(evidence, keys) if a.json: print(json.dumps(rep, indent=2)) else: print(f"chain: {'VALID' if rep['chain_valid'] else 'INVALID'} ({rep['chain_detail']})") print(f"keys: {rep['keys_source']}") for p in rep["proofs"]: print(f" #{p['idx']} {p['type']} {p['node_id']}: {p['verdict']} -- {p['detail']}") print("RESULT:", "OK" if rep["ok"] else "FAILED") sys.exit(0 if rep["ok"] else 1) if __name__ == "__main__": main()