HashImmut

Overview

HashImmut is a PoC command-line tool designed to ensure file immutability and authenticity using digital signatures and SHA-384 hashes. It creates a secure wrapper file (.hashimmut extension) that stores the file's content along with a digitally signed integrity hash. This allows users to verify both that the file has not been modified (integrity) and that it was sealed by a holder of the corresponding private key (authenticity).

Purpose

The tool aims to provide a simple, cross-platform mechanism to:

• Sign: Establish a baseline for integrity by computing a SHA-384 hash and signing it with an Ed25519 private key.
• Seal: Encapsulate the original file and its signed metadata into a portable wrapper.
• Verify: confirm file integrity by validating the digital signature and comparing hash values.
• Restore: Automatically unwrap and restore the original file if verification succeeds.

Current Implementation

• Input Handling:
  • Uses a subcommand-based CLI (keygen, seal, verify).
• Behavior:
  • Key Generation: Generates Ed25519 private/public keypairs.
  • Sealing: Creates a wrapper file (<filename>.hashimmut) with a JSON header containing the original_hash, signature, public_key, current_hash, signed_at timestamp, and content_type.
  • Content Handling: Automatically detects file types. Text files are stored in plain text for readability, while binary files are Base64 encoded within the wrapper.
  • Verifying: Checks the wrapper file. If the signature is valid and the content hash matches the signed hash, it extracts the original file and removes the wrapper. If not, it alerts the user to the specific failure (signature mismatch or content modification).
• Security:
  • Hashing: SHA-384.
  • Signing: Ed25519 (using ed25519-dalek).
• Dependencies:
  • Rust crates: sha2, hex, clap, serde, serde_json, chrono, rand, ed25519-dalek, base64.

Usage

Getting HashImmut

You can either download a prebuilt binary or build the tool from source.

Option 1: From GitHub Releases

1. Download
   Go to the project’s Releases page and download the appropriate archive for your platform (Linux, macOS, or Windows).

2. Make executable (Linux)

   chmod +x hashimmut

3. (Optional) Add to PATH

   sudo mv hashimmut /usr/local/bin/

Option 2: Build from Source

1. Build

   cargo build --release

2. Run the binary

   ./target/release/hashimmut --help

---

Running HashImmut

Once installed (via releases or source), usage is identical.

1. Generate Keys Creates an Ed25519 keypair (private.key and public.key).

   hashimmut keygen
   # Optional: hashimmut keygen --output ./my_keys

2. Seal a File Signs and wraps a file using your private key.

   # Uses 'private.key' from current directory by default
   hashimmut seal test.md
   
   # Or specify a key explicitly
   hashimmut seal test.md --keyfile ./my_keys/private.key

   Result: Creates test.md.hashimmut.

3. Verify and Restore Verifies integrity and authenticity, then restores the original file.

   hashimmut verify test.md.hashimmut

   • Success: Prints FILE IS AUTHENTIC AND UNMODIFIED, restores test.md, and removes the wrapper.
   • Failure: Prints detailed error information (e.g., signature mismatch or content modification) and keeps the wrapper for inspection.

Status

This is a Proof of Concept. The focus is on demonstrating a self-contained, signed file format for immutable workflows.

License

This project is licensed under the MIT License. See LICENSE for details.