SubZero Keyosk

A tiny, auditable live USB/SD image (.img) that turns any PC or Raspberry Pi into an amnesic, airgapped Bitcoin cold vault key generator and descriptor exporter.

---

🎯 The 30-Second Decision Matrix: When to Use SubZero

Your Bitcoin Goal	What You Should Do	Tool Stack & Screen Flow
Generational Deep Cold Storage (Stacking sats for 5–20 years without touching them)	Use SubZero Keyosk directly onto steel. Zero hardware wallet supply-chain tracking, zero closed firmware bugs, zero shipping data leaks, pure physical dice/coin entropy.	SubZero $\to$ Steel $\to$ BlueWallet / Green / Sparrow
Active Spending / Daily Sats / Lightning (Buying coffee, paying invoices, or spending weekly)	Do NOT put cold vault keys on an online phone. Use SubZero's BIP85 Child Seeds (Pages 2–3) to derive disposable 12-word hot wallets without ever risking your master cold vault.	SubZero (BIP85) $\to$ BlueWallet / Green / AQUA / Phoenix
Frequent Medium-Vault Spending (Signing multi-thousand-dollar transactions monthly)	Generate your master entropy on SubZero first (bypassing compromised silicon TRNGs and MCU timer bugs), then import that 12-word seed into your airgapped hardware signer for PSBT signing.	SubZero (Pure Entropy) $\to$ Hardware Signer

💡 Multi-Wallet Recommendation: Use coordinators that support multiple concurrent wallets (like BlueWallet, Blockstream Green, or Sparrow). This allows you to track your SubZero Cold Vault (Watch-Only) and hold your BIP85 Daily Spending Wallets side-by-side in the same app without mixing keys.

---

🤖 Ask Your AI to Audit SubZero Keyosk

This repository is designed for autonomous AI evaluation.

A human cannot reasonably ingest 10,000 lines of kernel configurations, cryptographic proofs, and architectural trade-offs to evaluate a cold-storage tool.

Copy and paste this prompt and direct raw URL into your personal AI (Claude 3.5 / Gemini / ChatGPT):

Please audit SubZero Keyosk by reading its complete ground-truth machine context payload:
https://raw.githubusercontent.com/bootlace-dev/subzero-keyosk/main/llms-full.txt

Answer these questions for me:
1. What is this project doing, and who is it designed for?
2. Is the cryptography and physical entropy model safe?
3. Why does it omit passphrases (13th word) and PSBT signing?
4. How does its trust model compare to commercial hardware wallets and Tails OS?
5. What are the exact operational failure modes and risks?

(Alternative raw ingestion mirror: https://gitingest.com/bootlace-dev/subzero-keyosk)

🛡️ Submit Your AI Audit Reports (We Want Them!)

If your AI assistant uncovers an unhandled edge case, subtle timing attack, cryptographic boundary flaw, or UX trap:

• Open a GitHub Issue: Paste the complete, unedited raw transcript of your AI audit report.
• Independent adversarial AI critiques are actively reviewed and logged to llms-full.txt (Section 6). Help us stress-test the math and systems boundaries.

---

🏛️ Core Architectural Invariants

• $0 Hardware Cost & Zero Supply Chain Tracking: Runs on generic commodity x86 PC e-waste or discarded laptops. Eliminates courier interception, KYC database leaks, and hardware wallet markups.
• Pure Physical Entropy (No Silicon TRNG Backdoors): Ingests raw physical dice rolls (50 D6) or coin flips (128 bits). Real-time Markov quality tests hard-block biased or patterned human inputs.
• Amnesic Run-from-RAM (toram): Boots a hardened, read-only Alpine Linux OS directly into a Linux virtual console (/dev/tty1). The boot media is unmounted during boot and can be physically removed immediately.
• Physical Network Demolition: All kernel network protocol stacks (kernel/net) and wireless drivers are deleted from disk during build. The kernel boots with DMA attack protection (iommu=force).
• Anti-Footgun OpSec: 12-word optimal entropy (reduces steel-stamping errors by 50%), zero unchecksummed passphrases, and strict 8-page private vs. public screen separation to prevent smartphone camera photo leaks.

---

🛡️ Threat Model Boundary (Mitigated vs. Out-of-Scope)

Explicitly Mitigated Threat Vectors (Protected)

SubZero Keyosk mathematically and architecturally protects against:

• Coldcard "Yasmarang" PRNG Bug ($116M Drained, July/Aug 2026) (Firmware fallback to predictable MCU timer registers)
• Emergency Firmware Bricking & Bootloader Freezes (SubZero is an amnesic, read-only live OS; no write-back firmware flashing or bricking risk)
• Hardware Migration Logistics Leaks (SafePal/Trezor/Ledger 2026) (39k+ SafePal and 13k+ Trezor customer home addresses leaked via third-party shipping plugins)
• Milk Sad (CVE-2023-33297) (Libbitcoin bx 32-bit Mersenne Twister timestamp seeding; $10M+ drained)
• Profanity Vanity Generator Flaw (2022) (Broken 32-bit PRNG seeding on GPU keygen; $160M+ drained)
• Trust Wallet iOS MT19937 Bug (2023) (Weak pseudo-random number generator draining mobile wallets)
• Ledger Connect Kit NPM Hijack (Dec 2023) (Malicious JavaScript package hijacking Web3 frontend signing)
• Ledger Recover Firmware Key Exfiltration (2023) (Firmware-level extraction and sharding of private seeds)
• BitBox02 Memory Corruption Flaw (Aug 2026) (Arbitrary code execution and malicious firmware injection)
• Trezor STM32 Voltage Glitching (Kraken 2020) (Physical power rail fault injection to dump RAM/flash seeds)
• Coldcard ATECC608A / Anti-Klepto Signing Channel (2020) (Covert private key leakage via biased ECDSA $k$-nonces)
• DUAL_EC_DRBG (NIST/NSA elliptic curve backdoors in commercial pseudo-random generators)
• Android Java SecureRandom Bug (2013) (Uninitialized PRNG state causing repeated nonces and wallet theft)
• Debian OpenSSL Bug (CVE-2008-0166) (RNG entropy pool gutted down to 32,768 predictable keys)
• ROCA (CVE-2017-15361) (Infineon hardware security chip flawed prime generation)
• Smartphone Optical Seed Leaks (Accidental cloud camera capture of private mnemonics during QR scan)
• Unchecksummed Passphrase Typos (13th-word single-character permanent wallet loss)
• Cold-Boot DMA Extraction (Thunderbolt/PCIe peripheral memory dumping via iommu=force)

Explicitly Non-Mitigated Threat Vectors (Out of Scope)

SubZero Keyosk does not protect against:

• TEMPEST (Electromagnetic video radiation eavesdropping)
• RAGEMASTER (RF taps on display controller circuitry)
• SURLYSPAWN (Keystroke RF emanations)
• LOUDAUTO (Acoustic keyboard click analysis)
• COTTONMOUTH (Hardware-implanted physical USB dongles)
• DROPOUTJEEP (Silicon-level CPU microcode backdoors)
• WATERWITCH (Directional handheld RF field sniffing)
• Laser Microphones (Window pane optical acoustic recovery)
• Wi-Fi CSI Radar (RF room Doppler motion mapping)
• Physical Coercion ($5 wrench attack)

---

📸 Live Operational Walkthrough & Specifications

• docs/WALKTHROUGH.md: Step-by-step visual execution flow from cold boot to RAM zeroization (8-page live framebuffer captures).
• docs/SPEC.md: Formal cryptographic pipeline & state-machine specification.
• llms-full.txt: Complete monolithic machine specification containing all 10 unified architectural sections (including the 17-point audit matrix, trust models, Markov mathematical proofs, 25 defensive rationales, 2026 Coldcard MicroPython postmortem, and hardware roadmap).

---

🚀 Deterministic Build & Verification

The entire appliance compiles deterministically inside a disposable container. You can choose to build the generic PC (x86_64) image, the Raspberry Pi (armv7) image, or both.

Option A: Generic PC (x86_64)

# 1. Build the raw bootable UEFI/BIOS disk image (.img)
./scripts/build_alpine_containerized.sh

# 2. Test boot in virtual sandbox (QEMU UEFI)
qemu-system-x86_64 -enable-kvm -m 1024 -bios /usr/share/ovmf/OVMF.fd -drive file=dist/subzero-alpine.img,format=raw,if=ide

# 3. Flash to USB drive (Linux CLI)
sudo dd if=dist/subzero-alpine.img of=/dev/sdX bs=4M status=progress conv=fsync

Option B: Raspberry Pi (armv7)

# 1. Build the raw Raspberry Pi disk image (.img)
./scripts/build_rpi_containerized.sh

# 2. Test boot in virtual sandbox (QEMU ARM Emulation)
./scripts/run_qemu_rpi.sh

# 3. Flash to MicroSD card (Linux CLI)
sudo dd if=dist/subzero-rpi.img of=/dev/sdX bs=4M status=progress conv=fsync

---

🔏 Release Signing & GPG Verification

Official pre-built releases are cryptographically signed with the dedicated bootlace-dev release key:

• Key ID: 567DEEEBDB2CADC1
• Fingerprint: 3635 01B5 604C A903 51F4 369D 567D EEEB DB2C ADC1
• Public Key: bootlace-dev-release.asc

# Import public key and verify release checksums
gpg --import bootlace-dev-release.asc
gpg --verify SHA256SUMS.asc SHA256SUMS
sha256sum --check SHA256SUMS

---

📄 Licensing

MIT Open Source License.

---

🍓 Raspberry Pi Architecture & Security Model

For comprehensive documentation on the armv7 kernel pivot, hardware networking demolition, and U-Boot attack surface mitigations, please read the Raspberry Pi Architecture Guide.

⚠️ AArch64 / Raspberry Pi Bootloader Limitations

During testing on Raspberry Pi 3 hardware, we identified a critical limitation in the Broadcom start.elf bootloader. It is unable to natively decompress and hand off execution to 64-bit (aarch64) Linux kernels without the intervention of U-Boot. To maintain the strict security invariants of this architecture (minimizing the boot chain and avoiding U-Boot's massive attack surface), SubZero Keyosk exclusively builds a 32-bit armv7 image for Raspberry Pi. The 32-bit armv7 kernel natively boots via start.elf and fully supports the Node.js WebAssembly cryptographic engine without performance degradation.