🌙 Null

The Minimal Bootloader

A Stripped-Down Limine Fork for LunaOS

🚀 Minimal • 🛡️ Proven • ⚡ Fast • 🌙 LunaOS-Native

Features • What We Changed • What We Kept • Philosophy

---

🎯 What is Null?

Null is a minimal bootloader for LunaOS - a stripped-down fork of Limine with ~4,300 lines of dead code removed. It does exactly one thing: boot LunaOS kernels via the Limine protocol.

The numbers:

• 🗑️ ~4,300 lines removed - Multiboot, Linux boot, Chainload, ISO9660
• 📦 19 files deleted - unused protocol handlers and filesystems
• ✅ 1 protocol supported - Limine (the only one LunaOS uses)
• 🔒 0 regressions - boot process untouched

💡 Philosophy: Use proven code. Remove unused code. Touch nothing else.

---

✨ Features

🚀 What Null Does

🖥️ Boot LunaOS 🔧 Limine protocol (full support) 📋 Boot menu (recovery/older kernels) 💾 UEFI & BIOS boot 🔀 SMP initialization

🌐 Network & Storage 📁 FAT32 filesystem 🌍 PXE/TFTP network boot 💿 EFI partition support 🔐 Post-quantum crypto (Dilithium/Kyber)

🚫 What Null Doesn't Do

❌ Removed Protocols Multiboot 1/2 Linux boot Chainload

❌ Removed Filesystems ISO9660 CD/DVD boot

💡 Why? 🎯 LunaOS uses Limine only 🛡️ Dead code = attack surface ⚡ Smaller = faster boot

---

🔧 What We Changed

Component	Lines Removed	Status
📄 multiboot1.c/h	~560	🗑️ Deleted
📄 multiboot2.c/h	~1,360	🗑️ Deleted
📄 linux_x86.c	~630	🗑️ Deleted
📄 linux_risc.c	~450	🗑️ Deleted
📄 chainload.c/h	~370	🗑️ Deleted
📄 iso9660.s2.c/h	~580	🗑️ Deleted
🔩 Assembly files	~220	🗑️ Deleted
📋 menu.c dispatch	~30	✂️ Simplified
📊 Total	~4,300	✅ Gone

---

🛡️ What We Kept

Component	Purpose	Status
🔧 Limine protocol	Boot LunaOS kernels	✅ Essential
📋 Boot menu	Recovery mode, kernel selection	✅ Essential
📁 FAT32	Read kernel from EFI partition	✅ Essential
🌐 PXE/TFTP	Network boot (sister resurrection)	💡 Useful
🔐 PQCrypto	Post-quantum signatures & encryption	✅ Essential
🗺️ Memory map	DO NOT TOUCH	🔒 Sacred
🔀 SMP boot	DO NOT TOUCH	🔒 Sacred
📄 Paging	DO NOT TOUCH	🔒 Sacred

---

🧠 Philosophy

🤔 Why Fork Limine?

We tried everything else:

Attempt	Duration	Result
🔨 Custom bootloader from scratch	1 week	😭 Crying, almost quit
🔧 "Reorganizing" Limine memory	1 day	💀 SMP disappeared
🦀 Translating to Rust	2 days	💥 Failed miserably

🎯 Conclusion: Use proven bootloader, strip bloat, move on.

📜 The Rules

1. 🚫 Never touch memory map - It works. Don't ask how.
2. 🚫 Never touch SMP boot - It works. Don't ask why.
3. 🚫 Never touch paging - It works. Just be grateful.
4. ✂️ Remove unused code - Less code = fewer bugs.
5. 📋 Keep the boot menu - Recovery mode saves lives.

---

🔐 Post-Quantum Cryptography

Null includes a complete post-quantum cryptographic stack for secure boot.

🚀 Quick Start (One Command)

./setup-pqcrypto.sh

This single command will:

1. Download pq-crystals reference implementations
2. Build luna_sign and luna_crypt tools
3. Generate signing and encryption keys
4. Embed keys into the bootloader
5. Build the bootloader

Crypto Primitives

Component	Algorithm	Security Level	Key Sizes
🔏 Signatures	Dilithium-3 (ML-DSA)	NIST Level 3 (128-bit)	PK: 1952B, SK: 4032B, Sig: 3309B
🔑 Key Encapsulation	Kyber-1024 (ML-KEM)	NIST Level 5 (256-bit)	PK: 1568B, SK: 3168B, CT: 1568B
🔒 Symmetric AEAD	ChaCha20-Poly1305	256-bit	Key: 32B, Nonce: 12B, Tag: 16B

How It Works

Signing protects against kernel replacement (integrity):

Developer                           User's Machine
    │                                    │
    │  kernel.elf + secret key           │
    │      │                             │
    │  [luna_sign] ──────────────►  kernel.signed
    │                                    │
    │  BOOTX64.EFI ─────────────►   Bootloader verifies
    │  (has public key)                  signature before
    │                                    executing kernel

Encryption protects against kernel reading (confidentiality):

Developer                           User's Machine
    │                                    │
    │  kernel.signed + public key        │
    │      │                             │
    │  [luna_crypt] ─────────────►  kernel.enc
    │                                    │
    │  BOOTX64.EFI ─────────────►   Bootloader decrypts
    │  (has secret key)                  then verifies

Tool Usage

# Sign a kernel (appends 3309-byte Dilithium-3 signature)
./tools/pqcrypto/dilithium-ref/ref/luna_sign sign kernel.elf keys/signing.sec kernel.signed

# Verify a signed kernel
./tools/pqcrypto/dilithium-ref/ref/luna_sign verify kernel.signed keys/signing.pub

# Encrypt a file (Kyber-1024 + ChaCha20-Poly1305)
./tools/pqcrypto/kyber-ref/ref/luna_crypt encrypt kernel.signed keys/encryption.pub kernel.enc

# Decrypt a file
./tools/pqcrypto/kyber-ref/ref/luna_crypt decrypt kernel.enc keys/encryption.sec kernel.dec

File Formats

Signed kernel: [kernel data][Dilithium-3 signature (3309 bytes)]

Encrypted kernel (LUNAENC1 format):

┌─────────────────────────────────────────────────────────────────┐
│ Magic: "LUNAENC1" (8 bytes)                                     │
├─────────────────────────────────────────────────────────────────┤
│ Kyber-1024 Ciphertext (1568 bytes)                              │
├─────────────────────────────────────────────────────────────────┤
│ ChaCha20 Nonce (12 bytes)                                       │
├─────────────────────────────────────────────────────────────────┤
│ Poly1305 Authentication Tag (16 bytes)                          │
├─────────────────────────────────────────────────────────────────┤
│ Encrypted Data (variable length)                                │
└─────────────────────────────────────────────────────────────────┘
Header overhead: 1604 bytes

⚠️ Important Security Notes

1. Keys are per-developer - Each developer generates their own keypair
2. Bootloader + kernel are paired - A bootloader only verifies kernels signed with its embedded public key
3. Back up your secret keys - Store keys/*.sec files securely; if lost, you cannot sign new kernels
4. Never commit secret keys - .sec files are gitignored by default
5. Pre-built binaries are useless - A downloaded bootloader has someone else's keys embedded

Setup Script Options

./setup-pqcrypto.sh                 # Full setup (recommended)
./setup-pqcrypto.sh --tools-only    # Only build tools
./setup-pqcrypto.sh --keys-only     # Only generate keys
./setup-pqcrypto.sh --build-only    # Only rebuild bootloader
./setup-pqcrypto.sh --clean         # Clean and start fresh
./setup-pqcrypto.sh --no-kyber      # Signing only (no encryption)
./setup-pqcrypto.sh --help          # Show all options

---

🏗️ Building

With PQCrypto (Recommended)

./setup-pqcrypto.sh

Manual Build (No Crypto)

./bootstrap
./configure --enable-uefi-x86-64
make

See INSTALL.md for full build instructions.

---

🏷️ Versioning

Null follows the LunaOS unified versioning scheme:

• Version: 2025.12.100 (YYYY.MM.BBB)
• Increment: Bump BBB (100 → 101 → 102) per release
• Reset: Back to 100 each month

See VERSIONING.md for details.

---

📜 License

Licensed under the BSD 2-Clause License

Based on Limine by mintsuki and contributors.

See COPYING for full details.

---

🙏 Acknowledgments

Null is a minimal fork of the legendary Limine bootloader. We're deeply grateful to mintsuki and the Limine community for creating such a robust foundation.

What we took:

• 🔧 Proven boot process (memory, SMP, paging)
• 📦 Limine protocol implementation
• 📋 Boot menu system
• 📁 FAT32 and PXE support

What we gave back:

• 📚 A lesson in humility (don't rewrite bootloaders)

---

🌙 Part of LunaOS

Null is a core component of LunaOS - the first operating system built on the Coherence Paradigm.

The Coherence Paradigm

Null embodies the First Law of Computational Physics (LCP):

• 🎯 Minimum viable code - Only what's needed to boot LunaOS
• 🛡️ Proven foundations - Use Limine's battle-tested boot process
• 📉 Zero entropy increase - Remove code, don't add it

"The best bootloader is the one that gets out of the way."

---

🚀 Ready to boot?

./configure --enable-uefi-x86-64 && make

📖 Build Instructions • ⚙️ Configuration • 🐛 Issues

---

Made with 💜 by the LunaOS team

dε/dt ≤ 0