🔐 Seal

Seal is a minimal, local-only file encryption tool written in Go.

It encrypts and decrypts files on the same machine using AES-256-GCM with a single in-memory master key loaded. Seal is intentionally limited in scope to demonstrate correct, defensible cryptographic engineering.

If the key is lost, the data is lost. That is a design decision, not a flaw.

---

✨ Features

• Strong authenticated encryption using AES-256-GCM
• Local file encryption and decryption only
• Self-contained encrypted file format
• Strict input validation and safe failure behavior
• Append-only local audit log for successful operations
• No network access, no background services, no hidden state

---

🚫 Non-Goals (Very Important)

Seal deliberately does not support:

• File sharing or networking
• Public-key cryptography
• Password-based encryption
• Key recovery or escrow
• UI or background daemons
• Cloud storage or synchronization
• Custom or experimental crypto

Seal is not a vault, password manager, or backup system.

---

Architecture Overview

Seal is structured as a small set of focused, single-responsibility modules:

• cmd/seal
  CLI entrypoint and argument parsing.

• internal/key
  Loads and validates the master encryption key from the environment.

• internal/crypto
  AES-256-GCM encryption and decryption logic.

• internal/format
  Definition and validation of the sealed file format.

• internal/util
  File I/O helpers and cryptographic hashing utilities.

• internal/audit
  Append-only audit logging for successful operations.

The CLI composes these modules without introducing shared global state.

---

🖥️ Usage

Commands

seal encrypt <input_file> [-o output_file]
seal decrypt <input_file> [-o output_file]
seal info <sealed_file>

Examples

seal encrypt hello.txt
seal info hello.txt.sealed
seal decrypt hello.txt.sealed

By default:

• hello.txt → hello.txt.sealed
• hello.txt.sealed → hello.txt

Seal never overwrites existing files.

---

🔑 Key Management

Seal uses a single master key provided via an environment variable:

SEAL_MASTER_KEY

Requirements

• Base64-encoded
• Must decode to exactly 32 bytes
• Loaded only into memory
• Never written to disk
• Never logged

Key Generation Example

openssl rand -base64 32

⚠️ WARNING If the master key is lost, all encrypted data is permanently unrecoverable. Seal provides no recovery mechanism by design.

---

📦 Encrypted File Format

Each encrypted file is self-contained and structured as follows:

+------------+----------+----------+----------------------+
| Magic (4B) | Version  | Nonce    | Ciphertext + Tag     |
| "SEAL"     | 1 byte   | 12 bytes | variable length      |
+------------+----------+----------+----------------------+

Details

• Magic bytes identify the file as a Seal artifact
• Version enables future format evolution
• Nonce is randomly generated per encryption
• Payload is AES-GCM ciphertext including authentication tag

The format is fully validated before any decryption attempt.

---

🧾 Audit Logging

Seal records successful operations only in a local audit log:

~/.seal/audit.log

Each entry contains:

• UTC timestamp (RFC3339)
• Operation type (encrypt or decrypt)
• SHA-256 hash of the input file

Example audit log entry

2025-01-25T18:02:11Z encrypt 3b7c2e6e8c5e1f9d...

Design Notes

• Logs are append-only
• No file paths, filenames, or contents are logged
• Failed operations are intentionally not logged to avoid information leakage

---

🛡️ Security Model

Seal provides:

• Confidentiality via AES-256-GCM
• Integrity & authenticity via GCM authentication
• Atomic filesystem operations (no partial writes)
• Clear and explicit failure behavior

Seal assumes:

• A non-compromised operating system
• Secure handling of the master key by the user

Seal does not protect against:

• Malware or memory inspection
• Compromised OS or hardware
• Key exfiltration
• User error such as deleting the key

---

🧠 Engineering Philosophy

• Prefer boring, correct solutions over clever ones
• Minimize attack surface
• Fail loudly and safely
• Be explicit about limitations
• Build only what is required

Every design choice in Seal is intentional and defensible.

---

🧪 Development

Run directly during development:

go run ./cmd/seal encrypt file.txt

Build a local binary:

go build -o seal ./cmd/seal

Run tests:

go test ./internal/...

---

Design Decisions

• Single master key
  Simplifies the threat model and avoids key management complexity.

• No password-based encryption
  Prevents weak or reused passwords from undermining security.

• No failure logging
  Avoids turning logs into a side-channel or information oracle.

• Atomic file writes
  Ensures no partial output is ever produced.

Seal intentionally trades features for clarity and correctness.

---

📜 License

MIT License.

---