github doug445/AsahiLocker v3.0.0
AsahiLocker 3.0.0

59 minutes ago

AsahiLocker 3.0.0: audited a third time, in one command, and built not to strand you

The complete, audited way to encrypt Asahi Linux. Encrypt an installed Fedora Asahi Remix system in place, in one command, with the strongest key derivation cryptsetup can write. No reinstall, no USB stick needed, macOS untouched, and a 12-point gate that refuses to hand you a machine that will not boot.

3.0.0 marks the state after the third full audit of every script, test and document, as 1.11.0 and 2.0.0 marked the first two. The code is that of 2.2.1, released earlier today. It carries a major number because the scripts are deliberately stricter than before; what that means for you is below.

Nothing changes in how a volume is encrypted, in the KDF, or in any volume an earlier release made. If you are already encrypted, there is nothing to redo.

The evidence

  • Three full audits. One rule each time: nothing counts as a finding until it has been reproduced. The third reproduced thirteen findings on the released code — on a loop device, or in a KVM guest running the official Fedora Asahi Remix 45 image, old script and new side by side — fixed every one, then encrypted that guest from the RAM rescue and booted it.
  • More than 100 automated checks on every push, in five suites: the real encrypt, hard-kill, repair and resume sequence; a refused passphrase; the partition menus on a two-install disk; luks-mount.sh on a plain and an encrypted install; the command line of every script.
  • 5x the work per guess of a stock luksFormat on the same Mac, by default: argon2id at 4 GiB x 10. Measured on your machine and enforced at run time. Never pbkdf2.
  • In daily use on three Macs: the author's M2 MacBook Air, M1 Pro MacBook Pro and M2 Max MacBook Pro.

A mistyped passphrase no longer costs you the run

cryptsetup asks for the new passphrase before it writes anything, and stops if the two entries differ, if it refuses the passphrase as too weak, or if its YES is not in capitals. That used to end the whole run, after every other prompt and a btrfs check of up to half an hour. Now the script checks the partition to prove nothing was written (no LUKS header, btrfs still in place) and asks again. Three attempts, each through the Caps Lock check.

It tells you when you are about to go wrong, before anything happens

  • Running it on the system you are sitting in? It gives you the command for the built-in RAM rescue: no USB stick, no second install.
  • Running it from a drive mounted on /mnt, or from the partition about to be encrypted? Refused up front. Before, the script mounted the target over its own directory and stopped after the encryption.
  • Forgot sudo? One line. Before: a log file and a page of recovery advice for an encryption that never started.
  • Stopped before anything changed? It says exactly that. Recovery advice is kept for when it applies, and names your device.
  • Encrypting a second install from one AsahiLocker already encrypted? It names the fix (LUKS_MAPPER_NAME) instead of dead-ending.

What is stricter

The reason for the major number. If you drive these scripts from your own:

  • An option a script does not know is an error. Both installers used to treat any unknown argument as "install", so install.sh --help installed. Every script now answers --help without root and refuses the rest.
  • luks-mount.sh umount acts only on what luks-mount.sh mount recorded. It used to unmount any mountpoint it was given.
  • luks-deploy.sh refuses to start from under /mnt or from the partition it is about to encrypt.
  • A partition menu with no input stops. With stdin closed it used to loop for ever, writing to the deploy log on every pass (1.5 GB in six minutes). For unattended runs, pin the partitions: LUKS_TARGET_ROOT, LUKS_TARGET_BOOT, LUKS_TARGET_EFI.

luks-mount.sh

  • In a UTF-8 locale it tried /boot/efi before /boot, so a maintenance chroot silently had no EFI partition. Fixed, and a failed mount is now reported.
  • mount /dev/X /mnt/ followed by umount /mnt left the volume unlocked. A directory is now one place however you spell it.

Also fixed

  • post-encryption-setup.sh warned that it "could not confirm crypt support" in the initramfs of every correctly encrypted system.
  • The exit trap unmounted whatever you had on /mnt, on a dry run too.
  • A silent exit in the sector-alignment path; a summary that reported 4096-byte sectors for a 512-byte volume; two tracebacks in uboot-efivar.py.
  • luks-tune.sh checks custom memory and thread limits before the header backup and the passphrase, not after.

Tests

  • New: tests/cli-smoke-test.sh — the command line of every script, no root needed (26 checks).
  • New: tests/luks-mount-test.sh — a loop-image install laid out like an Asahi disk, plain and encrypted (13 checks).
  • loopback-core-test.sh gains a stage proving that a refused passphrase writes nothing (43 checks); multi-install-selection-test.sh gains the closed-stdin menu (12).
  • The 2.2.0 scripts fail the new command-line, menu and luks-mount.sh checks; 3.0.0 passes all of them.

Docs

  • README: why AsahiLocker, in numbers; the three ways to run it; the audit record.
  • INSTALL.md: the prompt table matches the script again, including the prompt that waits for you after the encryption finishes, and the RAM rescue is offered at Step 1.
  • RECOVERY.md: one-command shortcuts with luks-mount.sh, and a corrected recipe for restoring the ESP stub.
  • TESTED-SYSTEMS.md: the virtual-machine runs, and what a VM cannot show.
  • The guide site is regenerated from these.

Get it

git clone https://github.com/doug445/AsahiLocker.git
sudo ./AsahiLocker/bin/ram-rescue.sh build --arm && sudo reboot     # then type: asahilocker

Upgrading: git pull. A rescue image built with an earlier release carries the old scripts; sudo ./bin/ram-rescue.sh build rebuilds it.

Tested: every finding reproduced, then verified fixed; the full --defaults run from the RAM rescue with a mismatched passphrase first, the 12-point gate, an encrypted boot, post-encryption-setup.sh, the boot guards and ram-rescue.sh remove, all in a KVM guest on the official Fedora Asahi Remix 45 image. The RAM rescue and luks-mount.sh have still not been run on Apple hardware by this project.

Audit by Claude Fable 5.2 (Anthropic). Full record: README, Audit.

Don't miss a new AsahiLocker release

NewReleases is sending notifications on new releases.