{"id":46004993,"url":"https://github.com/siterelenby/keyquorum","last_synced_at":"2026-06-12T08:01:27.625Z","repository":{"id":341272549,"uuid":"1169007003","full_name":"SiteRelEnby/keyquorum","owner":"SiteRelEnby","description":"Shamir secret sharing daemon for distributed teams. Memory hardened, designed to prevent intercepting or handling another user's key or the secret itself, without jank or vulnerability points like shared tmux sessions.","archived":false,"fork":false,"pushed_at":"2026-02-28T21:09:36.000Z","size":148,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-28T23:37:11.734Z","etag":null,"topics":["cli","cryptography","cryptography-tools","distributed-teams","key-management","linux","rust","secret-sharing","security","shamir","shamir-secret-sharing"],"latest_commit_sha":null,"homepage":"https://github.com/SiteRelEnby/keyquorum","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SiteRelEnby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-28T03:46:39.000Z","updated_at":"2026-02-28T21:09:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SiteRelEnby/keyquorum","commit_stats":null,"previous_names":["siterelenby/keyquorum"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/SiteRelEnby/keyquorum","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiteRelEnby%2Fkeyquorum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiteRelEnby%2Fkeyquorum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiteRelEnby%2Fkeyquorum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiteRelEnby%2Fkeyquorum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SiteRelEnby","download_url":"https://codeload.github.com/SiteRelEnby/keyquorum/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiteRelEnby%2Fkeyquorum/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34234557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cryptography","cryptography-tools","distributed-teams","key-management","linux","rust","secret-sharing","security","shamir","shamir-secret-sharing"],"created_at":"2026-02-28T23:04:07.916Z","updated_at":"2026-06-12T08:01:27.615Z","avatar_url":"https://github.com/SiteRelEnby.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# keyquorum\n\n[![CI](https://github.com/SiteRelEnby/keyquorum/actions/workflows/ci.yml/badge.svg)](https://github.com/SiteRelEnby/keyquorum/actions/workflows/ci.yml)\n[![crates.io](https://img.shields.io/crates/v/keyquorum.svg)](https://crates.io/crates/keyquorum)\n[![License: Apache-2.0](https://img.shields.io/crates/l/keyquorum.svg)](https://github.com/SiteRelEnby/keyquorum/blob/main/LICENSE)\n\n![transrights](https://pride-badges.pony.workers.dev/static/v1?label=trans%20rights\u0026stripeWidth=6\u0026stripeColors=5BCEFA,F5A9B8,FFFFFF,F5A9B8,5BCEFA)\n![enbyware](https://pride-badges.pony.workers.dev/static/v1?label=enbyware\u0026labelColor=%23555\u0026stripeWidth=8\u0026stripeColors=FCF434%2CFFFFFF%2C9C59D1%2C2C2C2C)\n![pluralmade](https://pride-badges.pony.workers.dev/static/v1?label=plural+made\u0026labelColor=%23555\u0026stripeWidth=8\u0026stripeColors=2e0525%2C553578%2C7675c3%2C89c7b0%2Cf4ecbd)\n\nShamir secret sharing daemon for distributed teams. Split a secret into shares, distribute them to team members, and reconstruct the secret only when a quorum submits their shares. Nobody ever handles someone else's share or sees the reconstructed key. Shares implemented with [blahaj](https://git.distrust.co/public/blahaj) (maintained fork of sharks with zeroize support).\n\nBuilt for unlocking LUKS partitions, but works with anything that takes a key on stdin. Other things may be supported in the future.\n\n## Why this instead of …\n\nPlenty of tools split secrets with Shamir's scheme. The gap keyquorum fills is the **collection side**: a daemon that gathers shares from K people who never see each other's shares, verifies the reconstruction, runs an action with the secret, and wipes everything — with memory hardening throughout.\n\n| Tool | What it does | What it doesn't |\n|------|--------------|-----------------|\n| `ssss` / `horcrux` / other split CLIs | Split and combine shares offline | Someone has to collect all K shares in one place and handle the reconstructed secret by hand — that person becomes the single point of compromise. Zero references to bad fantasy series by hateful people, guaranteed forever. The trans person makes a better tool, of course ;) |\n| HashiCorp Vault (unseal keys) | K-of-N unseal of Vault itself | Requires running Vault; the quorum mechanism isn't usable for arbitrary secrets or actions outside Vault |\n| clevis / tang | Automatic network-bound LUKS unlock | Trust is in a server being reachable, not in K humans agreeing; no quorum of people |\n| age / GPG | Encrypt a secret to one or more recipients | Any single recipient can decrypt — there's no threshold |\n\nkeyquorum combines the split (with embedded blake3 verification and optional per-recipient `age` encryption, so the dealer never handles plaintext shares) with a hardened collection daemon (mlock'd memory, no core dumps, zeroize-on-wipe, combinatorial retry against corrupted shares) and pluggable actions (LUKS unlock, arbitrary command, stdout). If you only need offline split/combine, the simpler tools above are fine — keyquorum is for when the *reconstruction event* itself needs to be multi-party, audited, and hands-off.\n\n## Install\n\n```bash\ncargo install keyquorum keyquorum-split\n```\n\nOr build from source:\n\n```bash\ncargo build --release\n# binaries at target/release/keyquorum and target/release/keyquorum-split\n```\n\n**Platform support:** Linux is the primary and tested target. macOS builds are **highly experimental and untested** by the project maintainers — memory hardening features (DONTFORK, DONTDUMP, prctl) are Linux-only and are silently skipped on macOS. The maintainer does not have access to Apple hardware. macOS PRs are welcome but please do not open issues requesting Apple support.\n\n### Running as a systemd service\n\nA hardened unit file is provided in `contrib/systemd/`:\n\n```bash\ncp target/release/keyquorum /usr/local/bin/\nmkdir -p /etc/keyquorum \u0026\u0026 cp example-config.toml /etc/keyquorum/config.toml\n# edit /etc/keyquorum/config.toml for your deployment\ncp contrib/systemd/keyquorum.service /etc/systemd/system/\nsystemctl daemon-reload \u0026\u0026 systemctl enable --now keyquorum\n```\n\nThe unit sets `LimitMEMLOCK=infinity` (required by `strict_hardening`'s mlock guarantees), creates `/run/keyquorum` for the socket via `RuntimeDirectory`, and applies systemd sandboxing (`ProtectSystem=strict`, `MemoryDenyWriteExecute`, `PrivateTmp`, and friends) on top of the daemon's own process hardening. `PrivateDevices` is intentionally left off so the `luks` action can reach device-mapper — see the comments in the unit file if you want to tighten further for non-device actions. The daemon handles SIGTERM, so `systemctl stop` shuts down gracefully and cleans up the socket.\n\n## Quick start\n\n### 1. Generate shares\n\n```bash\n# Split a secret into 5 shares, any 3 can reconstruct (3-of-5)\necho -n \"my-secret-key\" | keyquorum-split -n 5 -k 3\n\n# Or write one file per share for easier distribution\necho -n \"my-secret-key\" | keyquorum-split -n 5 -k 3 -o files -d ./shares/\n```\n\nBy default, `keyquorum-split` embeds a blake3 verification checksum in the secret before splitting. This allows the daemon to verify candidate secrets in microseconds during reconstruction, without executing the configured action on wrong keys. Use `--no-checksum` to disable this (not recommended — see [Verification](#verification)).\n\nDistribute each share to its holder. The split operator should delete their copy.\n\n### Encrypting shares to recipients\n\nFor distributed teams where the split operator should never see plaintext shares:\n\n```bash\n# Create a recipients file (one age public key per line)\ncat \u003e recipients.txt \u003c\u003c 'EOF'\n# Alice\nage1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p\n# Bob\nage1xyz...\n# Carol\nage1abc...\nEOF\n\n# Generate encrypted shares (operator never sees plaintext)\necho -n \"my-secret-key\" | keyquorum-split -n 3 -k 2 -o age --recipients recipients.txt -d ./shares/\n\n# Each recipient decrypts their share and submits:\nage -d -i identity.txt share-1.txt.age | keyquorum submit -c /etc/keyquorum/config.toml\n```\n\nUse `--armor` (or `--armour`) to produce ASCII-armored `.age.txt` files that can be pasted into text channels (Signal, email, etc.) instead of binary `.age` files.\n\n### In-person key ceremonies\n\nFor handing out shares in person, `--output interactive` shows one share at a time on the terminal, waits for each holder to record theirs, and clears the screen (and scrollback, where the terminal supports it) between shares — nothing is written to disk and no holder sees another's share:\n\n```bash\necho -n \"my-secret-key\" | keyquorum-split -n 5 -k 3 -o interactive\n```\n\n### 2. Configure the daemon\n\n```toml\n# /etc/keyquorum/config.toml\n\n[daemon]\nsocket_path = \"/run/keyquorum/keyquorum.sock\"\n# tcp_port = 35000  # optional, binds 127.0.0.1 only\n\n[session]\nthreshold = 3\ntotal_shares = 5\ntimeout_secs = 1800  # 30 min window to reach quorum\n\n[action]\ntype = \"luks\"\ndevice = \"/dev/sda2\"\nname = \"cryptdata\"\n\n# OR: pipe secret to any command's stdin\n# [action]\n# type = \"command\"\n# program = \"/usr/local/bin/unseal-vault\"\n# args = [\"--cluster\", \"prod\"]\n```\n\nSee `example-config.toml` for all options.\n\n### 3. Start the daemon\n\n```bash\nkeyquorum daemon -c /etc/keyquorum/config.toml\n```\n\n### 4. Team members submit shares\n\nEach participant SSHes in and submits their share:\n\n```bash\n# Pipe a share file (PEM envelope, bare V1, or raw base64/base32)\nkeyquorum submit -c /etc/keyquorum/config.toml \u003c share-1.txt\n\n# Or type/paste interactively (press Enter twice or Ctrl+D to finish)\nkeyquorum submit -c /etc/keyquorum/config.toml\n\n# Check progress\nkeyquorum status -c /etc/keyquorum/config.toml\n```\n\nShares are always read from stdin — never as command-line arguments — to avoid exposure via the process table (`/proc`, `ps`) and shell history.\n\nWhen the threshold is reached, the secret is reconstructed and the configured action runs automatically. All shares are wiped from memory immediately after.\n\n## Verification\n\n`keyquorum-split` appends a 32-byte blake3 hash to the secret before splitting (enabled by default). On reconstruction, the daemon verifies the hash before executing any action. This means:\n\n- **Wrong share combinations are rejected instantly** without running cryptsetup or other commands with incorrect keys\n- **Retry mode works safely** — corrupted shares are identified by hash mismatch, not by executing the action on every C(n,k) combination\n\nThe config field `verification` controls this (default: `\"embedded-blake3\"`). Set to `\"none\"` only if shares were generated with `--no-checksum`.\n\n### Recovery drill — verifying shares offline\n\nDistributed shares rot: people lose them, copy them wrong, or hand back the wrong file. `keyquorum verify` lets you confirm a set of shares still reconstructs **without revealing the secret or running any action** — it reconstructs in hardened memory purely to check the embedded blake3 checksum, then wipes everything and prints only a verdict:\n\n```bash\nkeyquorum verify ./shares/share-1.txt ./shares/share-2.txt ./shares/share-3.txt\n# PASS: a quorum of 3 share(s) reconstructs a checksum-valid 27-byte secret.\n#       Verified using share indices [1, 2, 3]. The secret was NOT revealed.\n```\n\nThe threshold is read from share metadata when present (override with `-k`). This needs the embedded checksum (the split default); shares made with `--no-checksum` can't be verified without revealing the secret, and `verify` says so. Decrypt any `age` shares to plaintext first. Run it on a schedule as a backup-integrity check.\n\n## Checking config\n\n`keyquorum daemon --check-config` validates the config (applying lockdown and CLI overrides), prints the **effective** settings, and exits without starting anything — useful for catching a misconfiguration before a ceremony rather than during one. It surfaces overrides explicitly (e.g. lockdown forcing `on_failure` to `wipe`), and unknown keys are a hard error.\n\n## Share format\n\nkeyquorum uses a versioned share format (V1) with layered options for integrity and metadata. keyquorum is designed for a wide range of threat models and desired failure modes, and not all options will be appropriate for your use case — read this section before protecting anything valuable.\n\n### Format layers\n\nShares have up to three layers, each independently optional at generation time:\n\n1. **PEM envelope** (default) — human-readable wrapper with a `KEYQUORUM-SHARE-V1` marker line\n2. **Metadata headers** (default) — share number, threshold, total shares, scheme, integrity method. Included in the envelope above the payload\n3. **CRC32 integrity** (default) — per-share checksum embedded in the V1 binary payload, covering the raw share data\n\nExample of a full share (all defaults):\n```\nKEYQUORUM-SHARE-V1\nShare: 1 of 5 (threshold 3)\nScheme: shamir-gf256\nIntegrity: crc32\n\nS1EBATt3zvABLJC/il49S81WaRcD...\n```\n\nThe encoded payload line contains the complete V1 binary (KQ magic + flags + CRC32 + share data). If someone strips the headers and submits only the payload line, it works as a bare V1 share — no information is lost from the cryptographic material.\n\n### Confidentiality vs integrity tradeoffs\n\n**Full envelope with metadata** (`keyquorum-split -n 5 -k 3`, the default): maximum usability. Share holders can see which share they have, what threshold is required, and the daemon can cross-validate metadata against its config. The CRC32 catches corruption before reconstruction is attempted. Metadata is plaintext, so anyone with a share knows the scheme parameters.\n\n**Envelope without metadata** (`--no-metadata`): the envelope marker identifies it as a keyquorum share, but reveals nothing about the scheme. CRC32 still provides integrity checking within the V1 binary payload. The daemon cannot cross-validate parameters.\n\n**Bare V1** (`--bare`): no envelope, just the encoded V1 binary payload. Still includes the KQ magic prefix and optional CRC32. Compact, suitable for automation or embedding in other formats.\n\n**No CRC32** (`--no-integrity`): disables per-share integrity checking. Corruption is only detected at reconstruction time (via blake3 verification or action failure). Use this if your threat model includes intentionally corrupted shares as a canary — without per-share integrity, an adversary who obtains multiple shares cannot determine which are corrupted.\n\n**Base32 encoding** (`--encoding base32`): trades density for hand-writability. Base32 shares are ~60% longer but use only uppercase letters and digits, making them easier to transcribe on paper or read aloud. Base64 is the default.\n\n### Daemon-side enforcement\n\nThe daemon auto-detects all share formats (PEM envelope, bare V1, raw base64/base32) and accepts them interchangeably within the same session.\n\nSet `require_metadata = true` in config to reject shares that lack a PEM envelope with metadata headers. When enabled, the daemon cross-validates each share's threshold and total_shares against its own config, rejecting mismatches. When disabled (the default), metadata headers are ignored entirely — the daemon uses only the binary payload. This is deliberately not enforced by lockdown mode, since headerless shares leak less information about the scheme.\n\n### Metadata is not authenticated\n\nThe PEM envelope metadata headers are **not cryptographically signed**. They are a convenience layer for human operators and optional daemon-side validation, not a security boundary.\n\nAn attacker with access to a share could forge the metadata headers (e.g., changing the claimed threshold or total shares). With `require_metadata = true`, forged headers that don't match the daemon config cause rejection — this is a denial-of-service vector, but an attacker with the share could simply not submit it for the same effect. With `require_metadata = false`, forged headers are ignored entirely.\n\nThe actual cryptographic integrity comes from the CRC32 on raw share data (catches corruption) and the blake3 hash embedded in the secret (catches wrong combinations at reconstruction). Neither depends on metadata headers.\n\nSigned metadata envelopes are a stretch goal for a future format version. The V1 binary format includes a version byte to support this without breaking existing shares.\n\n### What the format protects against (and what it doesn't)\n\n| Threat | Protection | Status |\n|--------|-----------|--------|\n| Accidental share corruption (bit flip, truncation, copy-paste error) | CRC32 rejects at submit time; blake3 catches at reconstruction | Protected |\n| Single malicious participant submits garbage | Retry mode + blake3 verification excludes bad shares automatically | Protected |\n| MITM tampers with share data in transit | Same as accidental corruption — CRC32 + blake3 | Protected |\n| Forged metadata headers on a share | With `require_metadata`: rejected if headers don't match config. Without: headers ignored entirely | Advisory only |\n| Attacker collects K or more shares | Secret is compromised. No share format can prevent this — it's the fundamental assumption of the scheme | Not protectable |\n| Malicious split operator gives fake shares | Not detected. Verifiable Secret Sharing (VSS) schemes solve this but are not yet implemented | Not protected |\n\nIn retry mode with `log_participation = true`, the daemon logs which share indices were used in a successful reconstruction and which were excluded, allowing operators to identify problematic shares.\n\n## Retry on failure\n\nIf a participant submits a corrupted share, the default behavior (`on_failure = \"wipe\"`) discards everything — all participants must resubmit. For high-friction scenarios, enable retry mode:\n\n```toml\n[session]\non_failure = \"retry\"\nmax_retries = 3\n# verification = \"embedded-blake3\"  # required for retry (and is the default)\n# max_combinations = 100            # cap on C(n,k) combinations tried\n```\n\nIn retry mode, the daemon keeps existing shares, returns to accepting new ones, and retries reconstruction with all available combinations. The blake3 checksum ensures only the correct combination triggers the action.\n\n## Duress shares\n\nA duress (canary) share is a tripwire: a designated share index that, when submitted, silently triggers an alert. The submission response, status counters, and daemon log output are **indistinguishable from any other accepted share** — nothing about the detection is ever logged, because logs on the host may be visible to whoever is applying the coercion. The alert program is the only notification channel.\n\nThe intended pattern: give each participant their regular share **plus** their own duress share. A participant submitting under coercion uses the duress one. `keyquorum-split --duress N` designates the last N shares as duress and prints the matching config block:\n\n```bash\n# 3-of-6: shares 1-3 regular, 4-6 duress (one duress per participant)\necho -n \"my-secret-key\" | keyquorum-split -n 6 -k 3 --duress 3 -o files -d ./shares/\n```\n\n```toml\n[session]\nthreshold = 3\ntotal_shares = 6\n\n[session.duress]\nindices = [4, 5, 6]       # printed by keyquorum-split --duress\nmode = \"alert\"            # or \"poison\"\nalert_program = \"/usr/local/bin/notify-security\"\nalert_args = [\"--channel\", \"ops\"]\n```\n\nTwo modes:\n\n- **`alert`** (default) — the session proceeds normally: the duress share is a real share and counts toward quorum, so the unlock still happens, but the alert fires. Choose this when blocking the unlock would itself endanger the coerced participant (\"unlock under duress, but security knows\").\n- **`poison`** — the session looks normal, but reconstruction silently fails with exactly the same messages as a genuine bad-share failure, and the secret is never reconstructed. To the person watching the terminal it looks like someone submitted a corrupted share. An alert program is optional in this mode.\n\nThe alert program runs detached and receives no share or secret data.\n\n\u003e ### ⚠️ Security tradeoff: duress shares halve your collusion threshold\n\u003e\n\u003e **A duress share is a real Shamir share of the same secret — there is no separate \"duress key\".** If you hand each participant a normal share *and* a duress share, every person now holds **two of the N shares**. An attacker who coerces enough people therefore needs only **⌈K/2⌉ people instead of K** to collect a quorum of shares. A 3-of-6 where each of 3 people holds two shares can be unlocked by coercing just **2** of them. Shamir's information-theoretic guarantee is intact (K−1 shares still reveal nothing), but the *number of people* an adversary must compromise is roughly **halved**.\n\u003e\n\u003e Account for this when choosing `-n`/`-k`: if you want a true 3-person floor with per-person duress shares, you need a **5-of-10** scheme (each of 5 people holds 2 shares → 3 people = 6 shares ≥ 5), not 3-of-6. `keyquorum-split --duress` prints this warning with your specific numbers.\n\u003e\n\u003e **For `poison` mode, every participant needs their own distinct duress share.** Poison only protects against the people who actually hold a duress share; if an attacker coerces three people and none of them holds one, the secret reconstructs normally. Do **not** try to share a single duress index among several people — the daemon rejects duplicate indices, which would both break the unlock and look abnormal.\n\u003e\n\u003e A future scheme could avoid the halving by making duress shares decoys of a *different* polynomial (so they poison without being valid shares of the real secret). The current implementation does not do this.\n\n## Lockdown mode\n\nFor maximum security posture, enable lockdown mode via `--lockdown` flag or `lockdown = true` in config:\n\n```bash\nkeyquorum daemon -c /etc/keyquorum/config.toml --lockdown\nkeyquorum-split -n 5 -k 3 --lockdown -o files -d ./shares/\n```\n\nLockdown currently enforces:\n- Rejects `stdout` action type (secrets must not be written to stdout)\n- Forces `on_failure = \"wipe\"` (no retry mode)\n- Implies `strict_hardening = true`\n- Rejects `--output stdout` in keyquorum-split\n\nLockdown may gain new restrictions between versions. Use it when you want the strongest available defaults and accept potential breaking changes on upgrade.\n\n### Strict hardening\n\nBy default (`strict_hardening = true`), the daemon and split tool reject operations if memory protections (`mlock`, `madvise`) fail on secret buffers. This ensures secret material is never held in swappable, dumpable, or forkable memory. Individual protection failures are logged at WARN level with the specific protection name and error.\n\nDisable with `strict_hardening = false` in config or `--no-strict-hardening` on the CLI if your environment cannot provide these guarantees (e.g. unprivileged container without `IPC_LOCK`). Not recommended for production. Lockdown always implies strict hardening regardless of the config value.\n\n## Recommended configuration\n\nFor most deployments, this configuration provides a good balance of fault tolerance and auditability:\n\n**Generating shares:**\n```bash\n# Default V1 format: envelope + metadata + CRC32 + blake3 checksum\n# Generate N = K + 2 shares (two spare shares for fault tolerance)\necho -n \"my-secret\" | keyquorum-split -n 5 -k 3 -o files -d ./shares/\n```\n\nGenerating two more shares than the threshold means a single bad share doesn't block reconstruction, and a second spare covers the case where you need to identify who submitted garbage versus retrying with a replacement.\n\n**Daemon config:**\n```toml\n[daemon]\nsocket_path = \"/run/keyquorum/keyquorum.sock\"\n\n[session]\nthreshold = 3\ntotal_shares = 5\ntimeout_secs = 1800\non_failure = \"retry\"\nmax_retries = 3\n# verification = \"embedded-blake3\"  # the default\n# max_combinations = 100            # the default\nrequire_metadata = true\n\n[action]\ntype = \"luks\"\ndevice = \"/dev/sda2\"\nname = \"cryptdata\"\n\n[logging]\nlog_participation = true\nlevel = \"info\"\n```\n\nWhat this gives you:\n\n- **`on_failure = \"retry\"` + blake3 verification**: if a share is corrupted or malicious, the daemon automatically tries other combinations instead of wiping everything. Bad shares are excluded by blake3 hash mismatch.\n- **`require_metadata = true`**: shares without a PEM envelope and metadata headers are rejected. The daemon cross-validates threshold and total_shares against its config, catching shares generated with wrong parameters.\n- **`log_participation = true`**: the daemon logs who submitted which share index and when. Combined with retry mode, if reconstruction succeeds with shares excluded, the daemon logs which indices were used and which were excluded at WARN level — giving you a trail to identify the problematic share holder.\n- **N = K + 2**: two spare shares means you can tolerate one bad share (retry finds the working combination) and still have one spare if a participant is unavailable.\n\nFor higher-stakes deployments, also consider `--lockdown` (forces `on_failure = \"wipe\"`, rejects stdout action, implies `strict_hardening`). Note that lockdown and retry mode are mutually exclusive — lockdown prioritizes wiping secrets over fault tolerance.\n\n## Security\n\nThis is a security-critical tool. The design assumes the host is trusted but participants may not be in the same room.\n\n**Memory protection:**\n- `mlock()` on all buffers containing shares or the reconstructed secret — never swapped to disk\n- `madvise(MADV_DONTFORK)` on secret buffers — no copy-on-write leaks to child processes\n- `madvise(MADV_DONTDUMP)` — secret pages excluded from core dumps even if dumpable is re-enabled\n- `Zeroize` on drop for all sensitive data, including embedded checksum bytes\n- Reconstructed secret is used immediately then zeroized and munlocked\n\n**Process hardening:**\n- `prctl(PR_SET_DUMPABLE, 0)` at startup — no core dumps, no `/proc/self/mem` reads\n- `prctl(PR_SET_NO_NEW_PRIVS, 1)` — child processes (cryptsetup) cannot gain privileges via setuid/setgid\n\n**Input validation:**\n- Share index verified against decoded share data (first byte is the x-coordinate)\n- Duplicate share indices rejected\n- Total shares capped at configured `total_shares`\n- NDJSON messages capped at 64KB to prevent memory exhaustion\n- Socket path verified to be an actual socket before cleanup\n\n**Network:**\n- TCP binds `127.0.0.1` only (for remote access, participants tunnel via SSH/SSM)\n- Unix socket permissions `0o660`\n\n**Logging:**\n- Share values are never logged and never included in error messages\n- Participation logging (who submitted, when) is opt-in via config\n\n**Architecture:**\n- All secret material lives in a single tokio task — no shared mutexes, no `Arc\u003cMutex\u003e` on secrets\n- Connection handlers communicate with the session via message passing (mpsc channels)\n\n## Limitations\n\n- **Not for boot volumes** — the daemon requires a running OS\n- **No participant authentication** — anyone with a valid share can submit (share-only trust model). With `log_participation = true` the audit log does record the kernel-verified connecting identity (`SO_PEERCRED` uid/gid/pid on the Unix socket), which cannot be forged — but it is a log, not an access control.\n- **Single session at a time** — one unlock operation at a time per daemon instance\n- **Metadata envelope is not signed** — PEM headers are convenience-only and can be forged. See [Metadata is not authenticated](#metadata-is-not-authenticated)\n- **Threat model does not fully protect against a malicious dealer** — `--output age` encrypts shares to recipients so the operator never sees plaintext, but this is defence-in-depth, not a cryptographic guarantee (the operator still generates the shares). VSS (verifiable secret sharing) is planned for a future version.\n\n## CLI reference\n\n### keyquorum\n\n```\nUsage: keyquorum \u003cCOMMAND\u003e\n\nCommands:\n  daemon  Start the collection daemon\n  submit  Submit a share to the running daemon\n  status  Query the current session status\n```\n\n**`keyquorum daemon`**\n```\nOptions:\n  -c, --config \u003cCONFIG\u003e  Path to config file [default: /etc/keyquorum/config.toml]\n      --lockdown              Lockdown mode: maximum security posture\n      --no-strict-hardening   Allow operation if memory protections fail\n```\n\n**`keyquorum submit`**\n\nReads share data from stdin (pipe or interactive). Supports PEM envelopes, bare V1, and raw base64/base32.\n\n```\nOptions:\n  -u, --user \u003cUSER\u003e      Your identifier (optional, for participation logging)\n      --socket \u003cSOCKET\u003e  Socket path or tcp://host:port (overrides config)\n  -c, --config \u003cCONFIG\u003e  Path to config file (reads socket_path from it)\n```\n\n**`keyquorum status`**\n```\nOptions:\n      --socket \u003cSOCKET\u003e  Socket path or tcp://host:port (overrides config)\n  -c, --config \u003cCONFIG\u003e  Path to config file (reads socket_path from it)\n```\n\n### keyquorum-split\n\n```\nUsage: keyquorum-split [OPTIONS] --shares \u003cSHARES\u003e --threshold \u003cTHRESHOLD\u003e\n\nOptions:\n  -n, --shares \u003cSHARES\u003e        Total number of shares to generate (2-255)\n  -k, --threshold \u003cTHRESHOLD\u003e  Minimum shares needed to reconstruct (2-N)\n  -o, --output \u003cOUTPUT\u003e        Output mode: stdout (default), files, or age\n  -d, --dir \u003cDIR\u003e              Output directory (required for files and age modes)\n      --recipients \u003cFILE\u003e      Age recipients file (required for age mode)\n      --armor                  ASCII-armor age output (.age.txt instead of .age)\n      --lockdown               Lockdown mode: rejects stdout output\n      --no-strict-hardening    Allow operation if memory protections fail\n      --no-checksum            Do not embed blake3 verification checksum\n      --no-integrity           Skip per-share CRC32 integrity check\n      --no-metadata            Omit metadata headers from PEM envelope\n      --bare                   Output V1 binary payload only, no PEM envelope\n      --encoding \u003cENCODING\u003e    Payload encoding: base64 (default) or base32\n```\n\n## Protocol\n\nNewline-delimited JSON over Unix socket or TCP. See `example-config.toml` for configuration options.\n\n```\nClient → Daemon:  {\"type\":\"submit_share\",\"share\":{\"index\":3,\"data\":\"\u003cshare data\u003e\"}}\nClient → Daemon:  {\"type\":\"status\"}\nDaemon → Client:  {\"type\":\"share_accepted\",\"status\":{...}}\nDaemon → Client:  {\"type\":\"quorum_reached\",\"action_result\":{...}}\n```\n\n## License\n\nApache-2.0\n\nTrans rights are human rights 🏳️‍⚧️\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiterelenby%2Fkeyquorum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsiterelenby%2Fkeyquorum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiterelenby%2Fkeyquorum/lists"}