kevinveenbirkenbach/linux-image-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(image): distro-agnostic remote unlock via initramfs backends + Debian support

Browse Source 
Split the mkinitcpio-only remote-LUKS-unlock path into an InitramfsBackend
ABC with a get_backend() dispatch, and add the initramfs-tools backend for
Debian / Raspberry Pi OS.

- base.py: six-step backend contract; encryption.py becomes a thin,
  distro-neutral sequencer (get_backend by distribution).
- initramfs_tools.py: crypttab `none luks,initramfs`, cmdline rewritten to
  root=/dev/mapper + ip=::::host:eth0:dhcp, dropbear-initramfs
  authorized_keys, update-initramfs -k all (no build-host uname leak).
- shipped hooks (configuration/initramfs-tools/*): single-hop non-anonymous
  onion, libnss DNS baking, sed-not-source DHCP, kill-tor-before-pivot.
- shared offline onion keygen in keygen.py; tor.py removed (logic moved to
  mkinitcpio.py).
- raspios added to the apt distro family (session.py, raspberry.py).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-Birkenbach
2026-07-22 17:00:26 +02:00
parent 2a4b606cdb
commit 9b7a34989d
18 changed files with 634 additions and 263 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
tests/e2e/test_tor_unlock_e2e.py
View File

@@ -3,7 +3,7 @@
It reproduces the operator-visible half of the decryption process that the
"tor" mkinitcpio hook drives at boot:
1. generate the v3 onion keys offline (as lim.image.tor does in the chroot),
1. generate the v3 onion keys offline (as lim.image.initramfs.keygen does in the chroot),
2. start a real Tor onion service from a torrc mirroring the baked-in one,
forwarding the virtual port 22 to a local dropbear stand-in,
3. connect to the .onion address through Tor and deliver the passphrase,
@@ -24,7 +24,7 @@ import time
import pytest
from lim.image import tor as tor_module
from lim.image.initramfs import keygen
from tests.e2e import tor_harness
# The offline checks only need the tor binary (no network) and are
@@ -32,9 +32,7 @@ from tests.e2e import tor_harness
# onion round-trip needs the public Tor network, so it stays opt-in behind
# LIM_E2E_TOR=1 to keep an external, occasionally-flaky dependency out of the
# blocking gate.
_needs_tor = pytest.mark.skipif(
shutil.which("tor") is None, reason="needs the tor binary"
)
_needs_tor = pytest.mark.skipif(shutil.which("tor") is None, reason="needs the tor binary")
_needs_tor_network = pytest.mark.skipif(
shutil.which("tor") is None or os.environ.get("LIM_E2E_TOR") != "1",
reason="needs the tor binary and LIM_E2E_TOR=1 (live Tor network, slow)",
@@ -52,7 +50,7 @@ def workdir(tmp_path):
def test_offline_keygen_matches_production_flags():
"""Guard: the harness keygen mirrors the flags production actually runs."""
script = tor_module._KEYGEN_SCRIPT
script = keygen._KEYGEN_SCRIPT
assert "--DisableNetwork 1" in script
assert "HiddenServicePort" in script
assert "22 127.0.0.1:22" in script
@@ -62,9 +60,7 @@ def test_offline_keygen_matches_production_flags():
@_needs_tor
def test_onion_keygen_is_deterministic_and_offline(workdir):
"""Keys generate without network and the .onion address is stable."""
address = tor_harness.generate_onion_keys(
workdir / "onion", workdir / "data"
)
address = tor_harness.generate_onion_keys(workdir / "onion", workdir / "data")
assert address.endswith(".onion")
assert len(address) == len("v" * 56) + len(".onion") # v3 = 56 base32 chars
for name in ("hs_ed25519_secret_key", "hs_ed25519_public_key", "hostname"):

160
tests/unit/test_tor.py
View File

@@ -3,7 +3,9 @@ import pytest
from lim import config
from lim.device import Device
from lim.errors import LimError
from lim.image import encryption, tor
from lim.image.initramfs import get_backend, keygen, mkinitcpio
from lim.image.initramfs.initramfs_tools import InitramfsToolsBackend
from lim.image.initramfs.mkinitcpio import MkinitcpioBackend
from lim.image.plan import ImagePlan
from lim.image.session import ImageSession
@@ -13,17 +15,45 @@ def plan():
return ImagePlan(distribution="arch", raspberry_pi_version="4", tor_unlock=True)
@pytest.fixture
def debian_plan():
return ImagePlan(distribution="raspios", root_filesystem="ext4", tor_unlock=True)
def _write_onion_hostname(root, address="abcdefghijklmnop.onion"):
onion_dir = root / tor.ONION_DIR
onion_dir = root / keygen.ONION_STAGING_DIR
onion_dir.mkdir(parents=True)
(onion_dir / "hostname").write_text(f"{address}\n")
class TestConfigureTorUnlock:
def _session(tmp_path, mapper="cryptroot"):
session = ImageSession(Device("mmcblk0"))
session.root_partition_uuid = "ROOT-UUID"
session.root_mapper_name = mapper
session.root_mapper_path = f"/dev/mapper/{mapper}"
session.boot_mount_path = tmp_path / "boot"
session.boot_mount_path.mkdir()
return session
class TestBackendDispatch:
def test_arch_and_manjaro_use_mkinitcpio(self):
assert isinstance(get_backend("arch"), MkinitcpioBackend)
assert isinstance(get_backend("manjaro"), MkinitcpioBackend)
def test_raspios_uses_initramfs_tools(self):
assert isinstance(get_backend("raspios"), InitramfsToolsBackend)
def test_unknown_distribution_raises(self):
with pytest.raises(LimError, match="No initramfs backend"):
get_backend("gentoo")
class TestMkinitcpioTorUnlock:
def test_installs_hooks_and_returns_address(self, tmp_path, plan, fake_runner):
_write_onion_hostname(tmp_path, "stableaddress.onion")
address = tor.configure_tor_unlock(plan, tmp_path)
address = MkinitcpioBackend().install_tor_unlock(plan, tmp_path)
assert address == "stableaddress.onion"
package_installs = [
@@ -35,74 +65,53 @@ class TestConfigureTorUnlock:
assert len(fake_runner.find("install", "tor_install", "etc/initcpio/install/tor")) == 1
assert len(fake_runner.find("install", "tor_hook", "etc/initcpio/hooks/tor")) == 1
assert len(fake_runner.find("install", "torrc", "etc/tor/initramfs-torrc")) == 1
# Existing keys must be kept: no keygen chroot run.
assert fake_runner.find("chroot", "DisableNetwork") == []
def test_generates_keys_when_missing(self, tmp_path, plan, fake_runner):
with pytest.raises(LimError, match="produced no"):
tor.configure_tor_unlock(plan, tmp_path)
# FakeRunner executes nothing, so the hostname file never appears —
# but the keygen chroot script must have been issued exactly once.
MkinitcpioBackend().install_tor_unlock(plan, tmp_path)
keygen_calls = [
(kind, cmd, input_text)
for kind, cmd, input_text in fake_runner.calls
input_text
for _, _, input_text in fake_runner.calls
if input_text and "DisableNetwork" in input_text
]
assert len(keygen_calls) == 1
assert "HiddenServiceDir" in keygen_calls[0][2]
def test_hook_resources_exist(self):
source_dir = config.CONFIGURATION_PATH / "initcpio"
for name in ("tor_install", "tor_hook", "torrc"):
assert (source_dir / name).is_file()
assert "HiddenServiceDir" in keygen_calls[0]
class TestInitcpioHookHardening:
"""Guards for review findings in the shipped initramfs hooks."""
"""Guards for review findings in the shipped mkinitcpio hooks."""
def _read(self, name):
return (config.CONFIGURATION_PATH / "initcpio" / name).read_text()
def test_hook_resources_exist(self):
for name in ("tor_install", "tor_hook", "torrc"):
assert (config.CONFIGURATION_PATH / "initcpio" / name).is_file()
def test_install_bakes_the_dns_resolver(self):
# Without the NSS module the NTP hostname never resolves and the clock
# stays at 1970, so Tor rejects the consensus and never publishes.
assert "libnss_dns.so.2" in self._read("tor_install")
def test_hook_never_sources_dhcp_lease_files(self):
# Sourcing /tmp/net-*.conf would run attacker-controlled DHCP option
# strings as root before the LUKS root is unlocked.
hook = self._read("tor_hook")
assert '. "$conf"' not in hook
assert "sed -n 's/^IPV4DNS" in hook
def test_hook_attempts_ntp_without_gating_on_dhcp_dns(self):
# NTP must run even when tor_ntp is an IP literal (no DNS needed).
hook = self._read("tor_hook")
assert "skipping NTP sync" not in hook
assert "skipping NTP sync" not in self._read("tor_hook")
class TestBootloaderNetworking:
class TestMkinitcpioBootloader:
"""The cmdline.txt boot path (RPi4-class) must set ip= for remote unlock."""
def _session(self, tmp_path):
session = ImageSession(Device("mmcblk0"))
session.root_partition_uuid = "ROOT-UUID"
session.root_mapper_name = "cryptroot"
session.root_mapper_path = "/dev/mapper/cryptroot"
session.boot_mount_path = tmp_path / "boot"
session.boot_mount_path.mkdir()
return session
def test_cmdline_txt_gets_network_params(self, tmp_path, plan):
root = tmp_path / "root"
(root / "etc").mkdir(parents=True)
(root / "etc" / "hostname").write_text("myhost\n")
session = self._session(tmp_path)
(session.boot_mount_path / "cmdline.txt").write_text(
"root=/dev/mmcblk0p2 rw rootwait\n"
)
session = _session(tmp_path)
(session.boot_mount_path / "cmdline.txt").write_text("root=/dev/mmcblk0p2 rw rootwait\n")
encryption._configure_bootloader(plan, session, root)
MkinitcpioBackend().configure_bootloader(plan, session, root)
content = (session.boot_mount_path / "cmdline.txt").read_text()
assert "ip=::::myhost:eth0:dhcp" in content
@@ -118,20 +127,85 @@ class TestMkinitcpioHooksLine:
path.write_text(
"MODULES=()\n"
"BINARIES=()\n"
f"HOOKS=({encryption.MKINITCPIO_HOOKS_PREFIX} "
f"{encryption.MKINITCPIO_HOOKS_SUFFIX})\n"
f"HOOKS=({mkinitcpio.MKINITCPIO_HOOKS_PREFIX} "
f"{mkinitcpio.MKINITCPIO_HOOKS_SUFFIX})\n"
)
return path
def test_tor_hook_between_netconf_and_dropbear(self, tmp_path, plan, fake_runner):
path = self._mkinitcpio_conf(tmp_path)
encryption._configure_mkinitcpio(plan, tmp_path)
MkinitcpioBackend().configure_initramfs(plan, tmp_path)
assert "netconf tor dropbear encryptssh" in path.read_text()
def test_no_tor_hook_when_disabled(self, tmp_path, plan, fake_runner):
plan.tor_unlock = False
path = self._mkinitcpio_conf(tmp_path)
encryption._configure_mkinitcpio(plan, tmp_path)
MkinitcpioBackend().configure_initramfs(plan, tmp_path)
content = path.read_text()
assert "netconf dropbear encryptssh" in content
assert " tor " not in content
class TestInitramfsToolsBackend:
"""The Debian / Raspberry Pi OS backend."""
def test_crypttab_uses_initramfs_option(self, tmp_path, debian_plan):
root = tmp_path / "root"
(root / "etc").mkdir(parents=True)
session = _session(tmp_path)
InitramfsToolsBackend().register_encrypted_root(debian_plan, session, root)
crypttab = (root / "etc/crypttab").read_text()
assert "cryptroot UUID=ROOT-UUID none luks,initramfs" in crypttab
assert "/dev/mapper/cryptroot" in (root / "etc/fstab").read_text()
def test_cmdline_points_at_mapper_with_network(self, tmp_path, debian_plan):
root = tmp_path / "root"
(root / "etc").mkdir(parents=True)
(root / "etc" / "hostname").write_text("pi\n")
session = _session(tmp_path)
(session.boot_mount_path / "cmdline.txt").write_text(
"console=serial0,115200 root=PARTUUID=abcd-02 rootfstype=ext4 rootwait\n"
)
(session.boot_mount_path / "config.txt").write_text("dtparam=audio=on\n")
InitramfsToolsBackend().configure_bootloader(debian_plan, session, root)
cmdline = (session.boot_mount_path / "cmdline.txt").read_text()
assert "root=/dev/mapper/cryptroot" in cmdline
assert "root=PARTUUID=abcd-02" not in cmdline
assert "ip=::::pi:eth0:dhcp" in cmdline
assert cmdline.count("\n") == 1 # cmdline must stay a single line
assert "auto_initramfs=1" in (session.boot_mount_path / "config.txt").read_text()
def test_install_tor_unlock_places_initramfs_tools_scripts(
self, tmp_path, debian_plan, fake_runner
):
_write_onion_hostname(tmp_path, "debianonion.onion")
address = InitramfsToolsBackend().install_tor_unlock(debian_plan, tmp_path)
assert address == "debianonion.onion"
assert len(fake_runner.find("install", "tor_hook", "hooks/tor")) == 1
assert len(fake_runner.find("tor_premount", "init-premount/tor")) == 1
assert len(fake_runner.find("tor_bottom", "init-bottom/tor")) == 1
apt = [
text
for _, _, text in fake_runner.calls
if text and "apt install" in text and "tor busybox" in text
]
assert len(apt) == 1
class TestInitramfsToolsHookHardening:
def _read(self, name):
return (config.CONFIGURATION_PATH / "initramfs-tools" / name).read_text()
def test_hook_files_exist(self):
for name in ("tor_hook", "tor_premount", "tor_bottom", "torrc"):
assert (config.CONFIGURATION_PATH / "initramfs-tools" / name).is_file()
def test_hook_bakes_dns_resolver(self):
assert "libnss_dns.so.2" in self._read("tor_hook")
def test_premount_does_not_source_lease_files(self):
premount = self._read("tor_premount")
assert '. "$conf"' not in premount
assert "sed -n 's/^IPV4DNS" in premount