Module sign 

Cryptographically sign Hexz archives with Ed25519 signatures.

This module implements the sign command, which creates a cryptographic signature for a Hexz archive to ensure authenticity and integrity.

Signing Process

The signing operation follows these steps:

1. Load Header: Read and parse the archive header
2. Read Master Index: Read the entire index structure (block mappings)
3. Compute Digest: Calculate SHA-256 hash of the index
4. Sign Digest: Create Ed25519 signature using private key
5. Append Signature: Write 64-byte signature to end of file
6. Update Header: Record signature offset and length in header

What Gets Signed

The signature covers the Master Index only, not the entire file. This is because:

• The header is mutable (to store signature metadata)
• Data blocks are content-addressed via their hashes in the index
• Signing the index ensures block mappings haven’t been tampered with

Signature Format

• Algorithm: Ed25519 (EdDSA on Curve25519)
• Digest: SHA-256 of Master Index
• Signature Size: 64 bytes
• Storage: Appended to end of archive file

Security Properties

• Authenticity: Proves the archive was created by holder of private key
• Integrity: Detects any modification to the index structure
• Non-repudiation: Signer cannot deny creating the signature

Usage

# Generate keys first
hexz sys keygen --output-dir ~/.hexz/keys

# Sign an archive
hexz sys sign --key ~/.hexz/keys/private.key snapshot.st

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

File Format Changes

After signing, the archive structure becomes:

┌─────────────────┐
│  Header         │ signature_offset, signature_length fields updated
├─────────────────┤
│  Index          │ ← This is what gets signed (SHA-256 digest)
├─────────────────┤
│  Data Blocks    │
├─────────────────┤
│  Signature      │ ← 64-byte Ed25519 signature (appended)
└─────────────────┘

Functions

run

Sign a Hexz archive with an Ed25519 private key.