Skip to main content

Module verify

hexz_cli::cmd::sys

Module verify 

Source
Expand description

Verify Ed25519 signatures on Hexz archives.

This module implements the verify command, which validates the cryptographic signature on a signed Hexz archive to ensure authenticity and integrity.

§Verification Process

The verification operation follows these steps:

  1. Load Header: Read archive header and extract signature metadata
  2. Check Signature Exists: Verify the archive has been signed
  3. Read Signature: Load the 64-byte Ed25519 signature from the archive
  4. Read Master Index: Read the index structure that was signed
  5. Compute Digest: Calculate SHA-256 hash of the index
  6. Verify Signature: Validate Ed25519 signature using public key

§What Gets Verified

The signature verification checks:

  • The Master Index has not been modified since signing
  • The signature was created by the holder of the corresponding private key
  • The signature is mathematically valid (correct Ed25519 signature)

§Security Guarantees

A valid signature proves:

  • Authenticity: Archive was signed by holder of the private key
  • Integrity: Index structure has not been tampered with
  • Trust: If you trust the public key, you can trust the archive

§Limitations

Signature verification does NOT protect against:

  • Replay attacks: Old valid archives can be replayed
  • Data block modification: Individual blocks could be swapped if hashes collide
  • Header manipulation: Some header fields are mutable (e.g., signature metadata)

§Usage

# Verify an archive signature
hexz sys verify --key ~/.hexz/keys/public.key snapshot.st

# On success
# => Signature Verified! The image index is authentic.

# On failure
# => Error: Signature verification failed

§Exit Codes

  • 0: Signature is valid
  • Non-zero: Verification failed (invalid signature or archive not signed)

Functions§

run
Verify the Ed25519 signature on a signed Hexz archive.