Signing Backup Manifests with Python cryptography

#!/usr/bin/env python3
"""Sign and verify backup manifests with detached Ed25519 signatures.

Subcommands:
    keygen <keybase>              write <keybase>.key (private) + <keybase>.pub
    sign   <root> <keybase.key>   hash artifacts under <root>, sign the manifest
    verify <manifest> <sig> <pub> verify signature, then every artifact digest

Exit codes:
    0  manifest signature valid AND every artifact digest matches
    1  bad signature, or a digest/size mismatch, or a missing artifact
    2  usage / configuration error
"""
import hashlib
import json
import sys
import time
from pathlib import Path
from typing import Dict, Tuple

from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric.ed25519 import (
    Ed25519PrivateKey,
    Ed25519PublicKey,
)

READ_CHUNK = 1024 * 1024  # 1 MiB streaming window keeps the heap flat


def canonicalize(manifest: dict) -> bytes:
    """Deterministic signing bytes: sorted keys, no incidental whitespace, UTF-8."""
    return json.dumps(
        manifest,
        sort_keys=True,
        separators=(",", ":"),
        ensure_ascii=False,
    ).encode("utf-8")


def hash_file(path: Path) -> Tuple[str, int]:
    """Stream a file through SHA-256; return (hexdigest, byte size)."""
    h = hashlib.sha256()
    size = 0
    with path.open("rb") as fh:
        for block in iter(lambda: fh.read(READ_CHUNK), b""):
            h.update(block)
            size += len(block)
    return h.hexdigest(), size


def build_manifest(root: Path, key_id: str) -> dict:
    """Hash every regular file under root into a manifest keyed by relative path."""
    artifacts: Dict[str, dict] = {}
    for path in sorted(p for p in root.rglob("*") if p.is_file()):
        digest, size = hash_file(path)
        artifacts[str(path.relative_to(root))] = {"sha256": digest, "size": size}
    return {
        "schema": "bv-manifest/1",
        "backup_epoch": int(time.time()),
        "key_id": key_id,
        "artifacts": artifacts,
    }

def cmd_keygen(keybase: str) -> int:
    private_key = Ed25519PrivateKey.generate()
    priv_pem = private_key.private_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PrivateFormat.PKCS8,
        encryption_algorithm=serialization.NoEncryption(),
    )
    pub_pem = private_key.public_key().public_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PublicFormat.SubjectPublicKeyInfo,
    )
    key_path = Path(f"{keybase}.key")
    key_path.write_bytes(priv_pem)
    key_path.chmod(0o600)
    Path(f"{keybase}.pub").write_bytes(pub_pem)
    print(f"wrote {keybase}.key (private, 0600) and {keybase}.pub (public)")
    return 0


def cmd_sign(root: str, key_file: str) -> int:
    root_path = Path(root)
    if not root_path.is_dir():
        print(f"artifact root {root!r} is not a directory", file=sys.stderr)
        return 2
    priv = serialization.load_pem_private_key(Path(key_file).read_bytes(), password=None)
    if not isinstance(priv, Ed25519PrivateKey):
        print("key file is not an Ed25519 private key", file=sys.stderr)
        return 2
    manifest = build_manifest(root_path, key_id=Path(key_file).stem)
    signature = priv.sign(canonicalize(manifest))
    manifest_path = root_path / "manifest.json"
    manifest_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
    (root_path / "manifest.json.sig").write_bytes(signature)
    print(f"signed {len(manifest['artifacts'])} artifacts -> {manifest_path}")
    return 0

def cmd_verify(manifest_file: str, sig_file: str, pub_file: str) -> int:
    try:
        manifest = json.loads(Path(manifest_file).read_text(encoding="utf-8"))
        signature = Path(sig_file).read_bytes()
        pub = serialization.load_pem_public_key(Path(pub_file).read_bytes())
    except (OSError, json.JSONDecodeError, ValueError) as exc:
        print(f"config error: {exc}", file=sys.stderr)
        return 2
    if not isinstance(pub, Ed25519PublicKey):
        print("public key file is not an Ed25519 key", file=sys.stderr)
        return 2

    # 1. Signature gate: reject untrusted manifests before reading any digest.
    try:
        pub.verify(signature, canonicalize(manifest))
    except InvalidSignature:
        print("SIGNATURE INVALID -> manifest untrusted, refusing restore",
              file=sys.stderr)
        return 1
    print(f"signature valid (key_id={manifest.get('key_id')})")

    # 2. Digest gate: every artifact must still reproduce its trusted digest.
    root = Path(manifest_file).resolve().parent
    bad = 0
    for rel, spec in manifest["artifacts"].items():
        artifact = root / rel
        if not artifact.is_file():
            print(f"MISSING {rel}", file=sys.stderr)
            bad += 1
            continue
        digest, size = hash_file(artifact)
        if digest != spec["sha256"] or size != spec["size"]:
            print(f"DIGEST MISMATCH {rel}", file=sys.stderr)
            bad += 1
        else:
            print(f"OK {rel}")
    return 1 if bad else 0


def main(argv: list) -> int:
    if len(argv) >= 2 and argv[1] == "keygen" and len(argv) == 3:
        return cmd_keygen(argv[2])
    if len(argv) >= 2 and argv[1] == "sign" and len(argv) == 4:
        return cmd_sign(argv[2], argv[3])
    if len(argv) >= 2 and argv[1] == "verify" and len(argv) == 5:
        return cmd_verify(argv[2], argv[3], argv[4])
    print("usage: manifest_sign.py keygen <keybase> | "
          "sign <root> <key.key> | verify <manifest> <sig> <pub>",
          file=sys.stderr)
    return 2


if __name__ == "__main__":
    sys.exit(main(sys.argv))

$ python3 manifest_sign.py verify backup/manifest.json backup/manifest.json.sig keys/backup_ed25519.pub
signature valid (key_id=backup_ed25519)
OK base.tar.zst
OK wal/000000010000002B.gz
$ echo $?
0

$ python3 manifest_sign.py verify backup/manifest.json backup/manifest.json.sig keys/backup_ed25519.pub
SIGNATURE INVALID -> manifest untrusted, refusing restore
$ echo $?
1