shamir-cli is a reference-grade command-line tool for splitting and recovering secrets using Shamir Secret Sharing over GF(256), with mandatory authenticated encryption and explicit, auditable formats.
The project prioritizes correctness, auditability, and fail-closed security semantics over convenience, performance, or feature growth.
- Threshold-based secret recovery (Shamir Secret Sharing)
- Finite field arithmetic over GF(256)
- Mandatory authenticated encryption (AEAD)
- Deterministic, versioned share format (FORMAT=2)
- Explicit failure on any corruption or misuse
- Canonical test vectors and full cryptographic coverage
shamir-cli is built around the following principles:
- Explicit over implicit behavior
- Failure over silent recovery
- Auditability over performance
- Determinism over opacity
Every cryptographic and operational decision is documented, testable, and intentional.
Secret ↓ AEAD (ChaCha20-Poly1305) ↓ Shamir Split (GF256) ↓ FORMAT=2 Share Files
Recovery reverses this process and fails immediately on any integrity violation.
- Field: GF(256)
- Polynomial: AES irreducible polynomial (0x11b)
- AEAD: ChaCha20-Poly1305
- KDF: HKDF-SHA256
All parameters are fixed, documented, and contractually frozen.
Shares are stored as human-readable text files using a strict, versioned format:
FORMAT=2 FIELD=GF256 INDEX=1 THRESHOLD=3 TOTAL=5 SALT=... NONCE=... DATA=...
Unsupported versions or malformed files are rejected without fallback.
The system is explicitly fail-closed.
Failures include:
- Insufficient shares
- Duplicate indices
- Corrupted or truncated data
- Authentication failure
- Format violations
No partial recovery or best-effort behavior is permitted.
Normative and authoritative documentation is located in docs/:
CRYPTO_SPEC.md— cryptographic design and primitivesFORMAT.md— canonical FORMAT=2 specificationSECURITY_MODEL.md— attacker model and guaranteesCLI_CONTRACT.md— frozen CLI behavior and exit semanticsAGENTS_CONTRACT.md— explicitly unstable agents subsystemVERSIONING_POLICY.md— versioning and compatibility rulesLTS_POLICY.md— long-term support guaranteesSECURITY_RESPONSE.md— vulnerability reporting and response processNON_GOALS.md— explicitly excluded features
shamir-cli is intended for:
- Secure secret escrow
- Threshold-based recovery workflows
- Auditable security systems
- Long-term archival of sensitive material
It is not a general-purpose encryption tool or key management system.
This tool is built on top of the sealed shamir v1.0.0 reference
implementation.
The CLI acts as a thin, non-contractual adapter over the stable cryptographic core and encoding layers. Its behavior is expected to remain stable, with changes being additive and deliberate.
MIT License. See LICENSE for details.