The complete, audited way to encrypt Asahi Linux. One command, the
strongest key derivation cryptsetup can write, and a machine that boots
afterwards — checked before you are allowed to reboot.
Encrypt the root filesystem of an already-installed Fedora Asahi Remix system on Apple Silicon — in place, without reinstalling, without wiping macOS, and without a second copy of your data.
luks-deploy.sh converts your existing btrfs root partition into a LUKS2
container holding that same filesystem. Your files, subvolumes, snapshots and
btrfs UUID all survive; the partition simply gains an encryption layer. It then
rewrites every piece of boot configuration that has to change (crypttab,
fstab, /etc/kernel/cmdline, GRUB defaults, all BLS entries, dracut
config, all initramfs images) and refuses to let you reboot until a 12-point
verification gate passes.
Built for every M-series Mac that Fedora Asahi Remix boots — laptop or desktop: MacBook Air and Pro, Mac mini, Mac Studio, iMac and the 2023 Mac Pro, across M1, M2 and M3 and their Pro / Max / Ultra variants. Nothing in the tooling is model-specific: partitions, subvolumes, the boot layout, the disk's sector size and the initramfs contents are all read at run time. Which machines are verified, which are expected to work, and what changes on a desktop (a Bluetooth keyboard cannot type the passphrase; there is no battery to ride out a mains dip) is in docs/COMPATIBILITY.md. M4 is not claimed: the kernel ships its device trees, but Asahi does not boot it yet.
New here? The one-page guide, Encrypt Asahi Linux with LUKS2, in place, walks through the whole job start to finish.
Official source. The official AsahiLocker is github.com/doug445/AsahiLocker. Releases are published only here, and the guide only at doug445.github.io/AsahiLocker. This tool rewrites your root partition, so take it from the source.
Use the official tooling for every route. Wrappers, forks and repackaged
copies are outside this project's tests and audits, and they can be missing
fixes that decide whether the machine boots. One measured example: a rescue
image that finds the root partition by its filesystem UUID cannot find it
again after a power cut in mid-encryption, because that UUID disappears the
moment the LUKS header is written — and a half-encrypted root does not boot
until the encryption is resumed. The built-in
ram-rescue.sh finds the root by GPT partition UUID and
resumes. If another build has left you there, nothing is lost: boot the
official RAM rescue or a live USB and run luks-deploy.sh; it finds the
interrupted encryption and finishes it.
This is destructive-by-nature tooling. It rewrites a live root filesystem. Read
docs/INSTALL.mdbefore running anything, and have a verified backup. See Risks.
- It is the whole job, not a wrapper around one command. Encrypt in place, rewrite every boot file, rebuild every initramfs, verify, and recover: start to finish, with three ways to run it — including a built-in RAM rescue that needs no USB stick and no second install.
- The strongest key derivation
cryptsetupcan write, by default. argon2id at 4 GiB x 10: five times the work per guess of a stockluksFormaton the same Mac. Measured on your machine, enforced at run time. No profile, flag or code path goes below stock, and none uses pbkdf2. - Built so that a mistake does not cost you the machine. A 12-point gate
checks every boot file before you may reboot. A run that is interrupted,
power cut included, resumes when you run the same command again. A
mistyped passphrase is asked for again. The script refuses the system it is
running from and a directory it is about to mount over, and stops at a
/bootthat belongs to a different install. - Audited in full three times. Every script, every test, every document. Nothing counted as a finding until it had been reproduced, and every finding was fixed. The record, with what was found, is under Audit.
- More than 100 automated checks on every push. The real encrypt,
hard-kill, repair and resume sequence against a loop device; a refused
passphrase; the partition menus on a two-install disk;
luks-mount.shon a plain and an encrypted install; the command line of every script. Since 2.1.0 every release has also been run end to end in a virtual machine on the official Fedora Asahi Remix image: encrypt, pass the gate, boot. - In daily use on three Macs. The author's M2 MacBook Air, M1 Pro MacBook Pro and M2 Max MacBook Pro were encrypted with it and have asked for the passphrase at every boot since; docs/COMPATIBILITY.md says exactly what is known about every other M-series Mac, and how.
- Documented like it matters. Every prompt and what to answer, every file it changes, every failure mode and the way out, every number and where it was measured.
- Free, MIT-licensed, actively developed. Good ideas get built in and credited by name.
- AES-256-XTS with a 512-bit key, in 4096-byte encryption sectors that match Apple's NVMe.
- argon2id at 4 GiB x 10 iterations, by default. 4 GiB is the most memory
cryptsetupwill let a keyslot cost. Every single guess at your passphrase has to fill 4 GiB, ten passes over: a 24 GB GPU holds about six guesses at once. - 5x the work per guess of a stock
luksFormaton the same Mac. A runtime guard refuses to write anything weaker than whatcryptsetupwould pick on its own. pbkdf2 is never used. - You pay the KDF once per boot; an attacker pays it for every guess. About 9.5 s at power-on on an M2 Max, after which the disk runs at full AES speed. With an 8-word diceware passphrase, an offline attack runs past 10^20 years.
- sha512 everywhere it counts: the keyslot AF splitter and the volume-key digest, pinned on every keyslot this tool writes, so none silently falls back to sha256.
- A 256-bit recovery key in its own keyslot and a LUKS header backup, so a forgotten passphrase or a damaged header is not the end of your data.
- Verified before you reboot. A 12-point gate refuses to hand you a machine that will not boot.
The numbers, their sources and the FileVault comparison: docs/CRYPTO.md.
Encrypting needs a system that is not the one being encrypted. Boot any one of these three, then run the same two commands:
| Boot from | Needs | Guide |
|---|---|---|
| The built-in RAM rescue | Nothing extra: no USB stick, no second install | docs/RAM-RESCUE.md |
| A Fedora Asahi live USB | A USB stick that your Mac's U-Boot can see | docs/LIVE-USB.md |
| A second, minimal Asahi install | ~20 GB of disk, set up from macOS | docs/SECOND-INSTALL.md |
git clone https://github.com/doug445/AsahiLocker.git
# RAM rescue: build it on the system you want encrypted, then reboot into it.
# At its prompt, `asahilocker` runs everything below for you.
sudo ./AsahiLocker/bin/ram-rescue.sh build --arm && sudo reboot
# From a live USB or a second install:
sudo ./AsahiLocker/bin/luks-deploy.sh --list # find your install
sudo ./AsahiLocker/bin/luks-deploy.sh /dev/nvme0n1p6 --defaults
# Reboot, type your passphrase, then finish on the encrypted system:
sudo ./AsahiLocker/bin/post-encryption-setup.sh
sudo ./AsahiLocker/boot-guards/install.sh--defaults takes the recommended answer to every question that has one: the
btrfs check, the aggressive KDF, a recovery key. /boot and EFI come from
your install's own /etc/fstab. What stays is what protects you: you type
ENCRYPT, confirm Caps Lock is off, and choose the passphrase. Mistype the
passphrase, or pick one cryptsetup refuses as too weak, and it asks again
instead of making you start over. If anything is interrupted, power cut
included, run the same command again and it picks up where it stopped.
Every script answers --help, and none of them needs root for that.
Full walkthrough: docs/INSTALL.md
- In-place btrfs → LUKS2 conversion. No reinstall, no backup-and-restore round trip, no second disk. Subvolumes, snapshots and the btrfs UUID survive.
- Pinned argon2id, never pbkdf2. AES-256-XTS with argon2id at 4 GiB by
default, the maximum
cryptsetupallows (2 and 1 GiB on request). Memory-hard by design, so GPU and ASIC cracking stays expensive. - Every profile is stronger than
cryptsetup's own defaults — enforced, not asserted. The weakest profile on offer does 1.125x the work of a plainluksFormaton the same machine, and the strongest does 5x. Before it writes anything the installer benchmarks whatcryptsetupwould have chosen unaided and refuses to ship weaker: a named profile below that bar is raised past it, pinned parameters below it are fatal. There is no flag to opt out. - Benchmarked on your machine. The installer measures your hardware and shows real unlock-latency estimates before you pick a KDF profile.
- Every boot file rewritten, then verified.
crypttab,fstab,/etc/kernel/cmdline, GRUB defaults, all BLS entries, dracut config and all initramfs images — behind a 12-point gate that refuses to let you reboot into a broken system. - Resumable after any interruption. LUKS2 re-encryption is journaled with checksum resilience; re-run the script and it detects the interrupted state and finishes it.
- One command when you want it.
luks-deploy.sh --listshows every install on the Mac and its state;luks-deploy.sh /dev/nvme0n1pN --defaultsencrypts one, with/bootand EFI proven from that install's own fstab instead of guessed from partition order. - No USB stick needed. The built-in RAM rescue (
ram-rescue.sh) boots your own kernel from RAM and encrypts in place, and survives a power cut midway. - Maintenance built in.
luks-mount.shlists, unlocks, mounts and chroots into any other Asahi install on the Mac, encrypted or not, then locks it all up again on exit. - A
--dry-runthat really is dry. The entire read-only half, including the exactcryptsetup reencryptinvocation it would issue, with nothing modified. - Recovery you can actually use. Optional 64-hex recovery key in a second keyslot, plus a labeled bundle with the LUKS header and every changed config.
- Asahi-specific boot guards. Stops a stray
grub2-mkconfigfrom bricking an encrypted boot, and clears U-Boot's stale EFI entries — in the file they actually live in (ubootefi.varon the ESP), which a runtimeefibootmgrdelete never reaches. - Tested in CI on every push, on aarch64 runners, against a real loop device.
| Path | What it is |
|---|---|
bin/luks-mount.sh |
Maintenance for the other installs on the Mac: list them and their state, mount one (unlocking it if encrypted) with /boot and EFI taken from its own fstab, chroot into it with everything put back on exit, umount, status. Refuses the partitions of the running system. Also in the RAM rescue, as luks-mount. |
bin/luks-deploy.sh |
The main event. In-place LUKS2 encryption of the installed btrfs root, run from a live USB, a second minimal Asahi install or a RAM-only rescue. Auto-detects everything, excludes the partitions of whatever system it is running from and refuses them as targets, cross-checks the selected boot/EFI partitions against the target's own fstab, self-repairs failed initramfs/BLS steps, fixes SELinux labels, and gates the reboot behind 12 verification checks. Fully resumable: re-run it after any interruption and it finishes the encryption (--resume-only) or redoes just the config phase. |
bin/ram-rescue.sh |
Builds, arms, reports on and removes the RAM-only rescue: this Mac's own kernel with an initramfs carrying luks-deploy.sh, every tool it needs and the cracklib dictionary, in a GRUB entry of its own. Encrypts the root in place with no USB stick and no second install; finds the partitions by GPT partition UUID, so it resumes after a power cut. |
bin/post-encryption-setup.sh |
Run once on the newly-encrypted system. Saves a recovery bundle, creates snapper subvolumes on the encrypted volume, enables the boot guards, verifies the result. Idempotent. |
bin/luks-tune.sh |
An ncurses front-end (dialog, falling back to whiptail) for inspecting and re-costing the argon2id parameters of keyslots on volumes that already exist. Shows the measured unlock time and what the cost buys against a GPU fleet before you commit, backs the header up first, and hands the passphrase prompt to cryptsetup rather than reading it. Pins --hash sha512 so a re-cost cannot walk a slot's AF hash back to cryptsetup's sha256 default. Never creates or destroys a keyslot, never changes a passphrase, never touches data. --dry-run prints the command and changes nothing. |
bin/save-luks-recovery-bundle.sh |
Labeled recovery bundle: a fresh, verified header backup of every LUKS volume on the machine (not just root), the public luksDump of each, the partition table of every disk holding one (sfdisk --dump, so a header backup is never a puzzle about offsets), crypttab/fstab/every command-line carrier/boot entries/EFI boot variables, sha256 sums, and a README with the repair steps for this machine's initramfs style and the checks to make before any header is restored. Refreshes a stale /boot emergency copy (keeping the old one). Key files named in crypttab are listed, never copied. --dry-run writes nothing. Key material — never attach it to a bug report. |
bin/post-encryption.conf.example |
Optional config for the above — snapper subvolumes and any extra units you want enabled post-encryption. |
boot-guards/ |
Two small Asahi-specific boot guards, plus an installer: ESP stub guard (stops a stray grub2-mkconfig from bricking an encrypted boot) and stale EFI entry cleaner (removes U-Boot's leftover entries for unplugged USB installers — from ubootefi.var on the ESP, where they actually live; uboot-efivar.py reads and edits that file). |
extras/ |
Optional luks-fetch-cache: an aligned LUKS/BitLocker status readout for fastfetch. Public header metadata only, no key material. |
tests/ |
loopback-core-test.sh: runs the exact encrypt/resume/recovery-key sequence against a throwaway file-backed loop device — including a hard-kill mid-reencrypt followed by cryptsetup repair + --resume-only, and a passphrase refused at cryptsetup's prompt, which must leave the device untouched. multi-install-selection-test.sh: builds a sparse two-install disk and checks the partition menus exclude the running system, recommend the right root, and pair boot/EFI with it. Both run in CI on every push (aarch64); safe to run locally with sudo. luks-mount-test.sh: builds a three-partition loop image laid out like an Asahi install, plain and encrypted, and checks luks-mount.sh mounts /boot and EFI parent first from the install's own fstab, honours --ro, and leaves nothing mounted or unlocked however the directory is spelled. cli-smoke-test.sh needs no root: every script answers --help, refuses an option it does not know, and stops in one line without sudo. uboot-efivar-test.sh covers the U-Boot variable-file editor. |
docs/ |
COMPATIBILITY · INSTALL · LIVE-USB · SECOND-INSTALL · RAM-RESCUE · RECOVERY · CRYPTO · FAQ · U-Boot bootflow · Internals · Fleet deployment · Encrypted /boot research · Release history |
tools/boot-probe/ |
Research only, not part of any install. Builds throwaway LUKS containers and a self-contained GRUB 2.14 image to measure what argon2id can actually do inside GRUB under U-Boot. Touches no real volume. See BOOT-ENCRYPTION-STATUS.md. |
iBoot → m1n1 stage 1 → m1n1 stage 2 → U-Boot → shim → GRUB → Linux
│ │
provides the UEFI environment │
│
reads BLS entries from /boot/loader/entries/
↓
kernel + initramfs load
↓
initramfs reads rd.luks.uuid from the
kernel cmdline, prompts for your
passphrase, opens LUKS, mounts root
U-Boot is the firmware/UEFI layer on Apple Silicon; GRUB is the bootloader running on top of it. Both are in the chain on Fedora Asahi Remix.
/boot stays unencrypted (plain ext4) so GRUB can read kernels and
initramfs images. The encrypted root is unlocked by the initramfs, not by
GRUB — see docs/INTERNALS.md.
Encrypting
/bootis being researched, and the work so far is written up in docs/BOOT-ENCRYPTION-STATUS.md — including measurements on real hardware showing GRUB's argon2id is 8.5× slower than the kernel's, and a reproducible hard reset past a certain computation length. It is not shipped, not enabled, and has no flag; every released version encrypts root only. Contributions and probe results from other Apple Silicon machines are wanted — the open questions are listed at the end of that document.
nvme0n1
p1 APFS iBootSystemContainer
p2 APFS macOS ← untouched
p3 APFS
p4 vfat EFI → /boot/efi ← stays plain
p5 ext4 BOOT → /boot ← stays plain
p6 btrfs fedora → / and /home ← becomes LUKS2(btrfs)
p7 APFS RecoveryOS
Partition numbers are auto-detected; this is just the common Asahi shape.
Pinned explicitly rather than left to cryptsetup's auto-benchmark, so every box
you deploy to ends up identical instead of picking a machine-dependent memory
cost and sha256.
| Parameter | Value |
|---|---|
| Cipher | aes-xts-plain64, 512-bit key (AES-256-XTS) |
| KDF | argon2id (always — no profile selects pbkdf2) |
| Memory cost | 4 / 2 / 1 GiB, by profile |
| Iterations (time cost) | 10 / 8 / 9 — aggressive / moderate / fast |
| Parallelism | 4 threads |
| Hash | sha512 — sets both the AF splitter hash and the LUKS2 volume-key digest |
| Encryption sector | 4096 bytes when the btrfs sectorsize allows it (it does on every Asahi install), else 512. Apple NVMe is a 4096-byte-sector disk and btrfs writes 4096-byte blocks; cryptsetup's default of 512 made every filesystem block eight XTS blocks with eight IVs. Verified in place for 4096-byte and 512-byte devices alike; LUKS_SECTOR_SIZE=512 pins the old value. cryptsetup refuses 4096-byte sectors on a partition whose size is not a multiple of 4096 — and on a 512-byte-sector GPT disk the last partition never is (GPT reserves 33 sectors at the end of the disk). The script then asks: type ALIGN to move the partition's end down by those few bytes (the table is backed up first; type, name, GUID and attributes are kept; the filesystem, already 32 MiB smaller, loses nothing), or press Enter for 512-byte sectors. LUKS_ALIGN_PARTITION=yes|no answers it non-interactively. On Apple's 4096-byte-sector NVMe the question never comes up |
The KDF re-runs in the initramfs at every boot, so its memory cost must be allocatable there — and you pay its full cost as unlock latency on every boot.
The installer benchmarks your machine and offers three profiles, with an
estimate for each taken from your own hardware rather than someone else's. All
three are argon2id — no profile selects pbkdf2 — and all three are stronger
than what cryptsetup picks for itself, which a runtime guard enforces rather
than assumes.
| Profile | Memory | Iterations | Threads | At boot, M2 Max | KDF alone, M2 Max | vs stock |
|---|---|---|---|---|---|---|
aggressive (default) |
4 GiB | 10 | 4 | 9.5 s (measured) | 7.3 s | 5x |
moderate |
2 GiB | 8 | 4 | ~4.2 s | 3.2 s | 2x |
fast |
1 GiB | 9 | 4 | ~2.7 s | 2.0 s | 1.125x |
At boot: aggressive measured from the boot journal (the gap between
systemd-cryptsetup taking the passphrase and the volume opening); the others
scaled from it. KDF alone: cryptsetup open --test-passphrase, median of five
runs, re-clocked 2026-11-20 with cryptsetup 2.8.8. Boot runs about 1.3x the KDF
alone. luks-tune.sh also offers paranoid (4 GiB x 12): 8.6 s KDF alone,
~11.3 s at boot.
Times shown are from an M2 Max. Your machine is benchmarked at run time, so the numbers you see will be your own.
Pick aggressive unless you have a reason not to. You pay the KDF once per
boot; an attacker with an image of your disk pays it once per guess. Memory cost
only has to be allocatable in the initramfs, which has the machine to itself, so
every profile is safe on any Asahi-supported Mac including an 8 GiB M1.
docs/CRYPTO.md has the rest: the full case for
aggressive and what a paranoid profile would buy, changing the KDF on a
volume that already exists,
why nothing here uses pbkdf2, how this
compares with FileVault on the same
disk,
how much your passphrase actually
contributes, and the GRUB
argon2id constraints.
sudo ./bin/luks-deploy.sh --dry-run # or LUKS_DRY_RUN=1Runs the entire read-only half — detection, selection menus, fstab
cross-checks, the KDF benchmark, the state backup to the deployment drive —
prints exactly what a real run would do (including the full
cryptsetup reencrypt invocation), and exits before the point of no return.
Nothing on the target is modified.
The deploy strips rhgb quiet from the boot args, because with the splash
active the first LUKS passphrase prompt hides behind it and the boot looks
hung. post-encryption-setup.sh restores both tokens after the first
encrypted boot (via a marker in /var/lib/asahilocker/). Opt out
with LUKS_KEEP_SPLASH=1.
During deployment the script offers to enroll a recovery key: 64 random hex
characters in a second LUKS keyslot, saved to the deployment drive (pin the
choice with LUKS_RECOVERY_KEY=yes|no). If the passphrase is ever forgotten,
the recovery key still unlocks the volume — type it at the boot prompt, or use
it as a --key-file from a live USB. It is enrolled before the header backup
is taken, so the backup contains the slot. Move it to secure offline storage
after deployment — anyone holding it can unlock the disk.
GRUB's own argon2id limits — the 4 GiB overflow, the firmware-dependent ceiling below it — do not constrain the root volume, because GRUB never unlocks it. They only matter for a volume GRUB itself must open, such as the encrypted-
/bootresearch. See docs/CRYPTO.md → GRUB and argon2id.
The manual route — cryptsetup reencrypt followed by editing crypttab,
fstab, the kernel cmdline, GRUB defaults and the BLS entries yourself — works,
and there are guides for it. What this kit adds is the part those guides leave
to you:
Manual cryptsetup reencrypt |
AsahiLocker | |
|---|---|---|
| Partition selection | You identify root/boot/EFI yourself | Auto-detected, fstype-checked, and cross-checked against the target's own fstab |
| KDF parameters | cryptsetup auto-benchmarks — machine-dependent, and picks sha256 |
Pinned argon2id + sha512, identical on every box, chosen from a menu benchmarked on your hardware |
| Boot config | You edit crypttab, fstab, cmdline, GRUB defaults and every BLS entry by hand |
All rewritten, including every BLS entry and every initramfs image |
| Did it work? | You find out at reboot | 12-point verification gate refuses the reboot until it passes |
| Interrupted run | You debug the header state yourself | Detected and resumed automatically; cryptsetup repair path handled |
| SELinux | Relabel it yourself or boot to AVC denials | Relabelled and verified |
| Undo / recovery | Whatever you thought to save | Header backups plus a labeled bundle of every changed file |
| The Asahi footguns | grub2-mkconfig clobbering the ESP stub; stale U-Boot EFI entries |
Boot guards install to prevent both |
If you want to understand what it changes before trusting it, --dry-run prints
every action, and docs/INTERNALS.md documents each one.
- No TPM on Apple Silicon. There is nowhere to seal a key, so you type the passphrase at every boot. That is by design, not a limitation of this tooling.
- Forget the passphrase and the data is gone — unless you enrolled the optional recovery key and can still find it. There is no backdoor. Back up the recovery bundle, keep the recovery key offline, and remember the passphrase.
- Have a verified backup before you start. Not "a backup" — one you have actually restored from or browsed. In-place re-encryption rewrites every sector of the root partition.
- You cannot brick the Mac. Apple Silicon DFU / System Recovery always works, and macOS is on separate APFS partitions this tooling never touches. An interrupted encryption is not fatal either: LUKS2 re-encryption is journaled with checksum resilience, and re-running the script detects the interrupted state and resumes it automatically. The header backups cover the remaining worst case of a damaged header.
- LUKS protects data at rest, not boot integrity. Only m1n1 stage 1 is
cryptographically verified on Asahi;
/bootis unencrypted and unsigned. An attacker with repeated physical access could tamper with the initramfs. - The passphrase prompt can hide behind boot text. If the machine looks hung
right after GRUB, it is probably waiting — type the passphrase and press Enter.
(The deploy strips the boot splash, and
post-encryption-setup.shrestores it, precisely so this prompt stays visible on the first encrypted boots.)
- An already-installed Fedora Asahi Remix system with a btrfs root.
- Somewhere to run the encryption from — the script refuses to encrypt the
filesystem it is booted from, and there is no override for that one.
Any of the three works:
- the built-in RAM rescue: nothing to plug in and nothing to install.
ram-rescue.sh build --armon the system you want encrypted, reboot, typeasahilocker— see docs/RAM-RESCUE.md. It needsgdiskand about 200 MiB free on/boot. - a Fedora Asahi live USB. A stock Fedora ISO will not boot on Apple
Silicon; build one with
asahi-fedora-usbas described in docs/LIVE-USB.md. If the stick looks dead at the U-Boot prompt, tryusb startbefore anything else — an unenumerated, unpowered port is the usual cause. - a second, minimal Asahi install on the internal disk, for machines that genuinely will not boot USB. The deploy script excludes the running install's partitions from every menu and refuses them as targets, so the shared-disk hazard is handled — see docs/SECOND-INSTALL.md.
- the built-in RAM rescue: nothing to plug in and nothing to install.
- AC power connected (the script enforces AC or >50% battery).
cryptsetup≥ 2.4 (forreencrypt --encrypt),btrfs-progs,dracut,grubby— all present in the live environment.- 15–60 minutes, depending on partition size.
AsahiLocker is for Fedora Asahi Remix on Apple Silicon (aarch64) only. The boot guards, the ESP stub handling and the U-Boot documentation all assume the m1n1 → U-Boot → GRUB chain, and Apple Silicon is the only platform it is developed and tested on.
If you are not on Apple Silicon, use LinuxLocker instead — the same in-place LUKS2 approach, written for everything else: it detects the distro, filesystem and boot stack, handles systemd-boot as well as GRUB, and rebuilds and re-signs Unified Kernel Images for Secure Boot.
Every question and its full answer is in docs/FAQ.md:
- Can I encrypt Fedora Asahi Remix after installing it?
- Does this touch or wipe macOS?
- Why do I have to type a passphrase at every boot? Can't it use the Secure Enclave?
- Which KDF does this use, and can I change it?
- Why is
/bootleft unencrypted? - What happens if the encryption is interrupted — power loss, a crash, a closed lid?
- Will a quantum computer break this?
- Can I run it unattended across several machines?
- Will this work on an M1 with only 8 GB of RAM?
- Does it work on anything other than Asahi?
- How do I check what I actually ended up with?
- Changing your KDF after installation
Seven of these are also published as pages of the guide site, easier to read and search: live USB · U-Boot bootflow · second install · which Macs · argon2id and AES-XTS · recovery · FAQ.
| Doc | Covers |
|---|---|
| COMPATIBILITY.md | Every M-series Mac, laptop and desktop, tiered by evidence — and what a desktop changes at the passphrase prompt |
| TESTED-SYSTEMS.md | The machines behind the ✅ claims — hardware, layout, what was verified and what was found |
| INSTALL.md | Step-by-step install, start to finish, with what each prompt means |
| LIVE-USB.md | Building a Fedora Asahi live USB, and the three ways to boot it |
| SECOND-INSTALL.md | The other route: encrypting from a second minimal Asahi install when the machine will not boot USB — and removing it cleanly afterwards |
| RECOVERY.md | Interrupted encryption, unbootable system, corrupt header, undoing a shrink |
| CRYPTO.md | The argon2id profiles in full: why aggressive, retuning an existing volume, never pbkdf2, the FileVault comparison, passphrase strength, GRUB's own limits |
| FAQ.md | The questions people actually ask, answered at length |
| UBOOT-BOOTFLOW.md | Getting to the U-Boot prompt and booting the live USB |
| INTERNALS.md | Every config file changed, the 12-point gate, self-repair, why /boot stays plain |
| FLEET.md | Deploying across several M-series boxes, and the UUID-uniqueness footgun |
| BOOT-ENCRYPTION-STATUS.md | Research, not a feature. Encrypted /boot: what has been measured, what broke, what is still unknown — and where help is wanted |
| BOOT-ENCRYPTION-DESIGN.md | Design only, nothing implemented. The intended encrypted-/boot architecture: the two unlock options and their trade-offs, retrofit rules, detached headers, release plan |
AsahiLocker is actively developed, and good ideas end up in it. If you have one, open a feature request or start a discussion. Any good free and open-source idea that keeps to the security rules gets built into AsahiLocker itself and credited by name under Acknowledgements. That is how the RAM-only rescue arrived. There is no need to maintain a separate tool for it.
Bug reports and patches are welcome — open an issue or a pull request.
Because this tooling rewrites a live root filesystem and its bootloader, a
description of what went wrong is rarely enough to act on.
CONTRIBUTING.md has copy-pasteable commands for the
things that are: a read-only diagnostic bundle, running the loopback suite and
the CI lint checks locally, dry-running the deploy, and verifying the GRUB
argon2 constraint on your own machine. It also covers building GRUB 2.14 with
argon2 into a local prefix, for anyone working on the /boot question.
AsahiLocker has been code-audited in full three times, for coding excellence — every script, the test suites and the documentation, checked for correctness, safety and code quality, as independent code review of in-place LUKS2 full-disk encryption on Apple Silicon. One rule held every time: nothing counted as a finding until it had been reproduced — against the code, on a loop device, in a virtual machine running the official Fedora Asahi Remix image, or on a running Mac.
2026-09-05 — Claude Fable 5.1 (Anthropic). The first complete audit of the encryption path for Fedora Asahi Remix. Findings shipped as v1.10.0–v1.10.2 — the recovery-keyslot AF-hash fix, the busy-device guard, the harden-only guarantee — and v1.11.0 marks the audited state.
2026-09-21 — Claude Fable 5.1 (Anthropic). A second full audit, scheduled for the week the second-install route landed, so the new code met a reviewer before it met anyone's disk. Nine findings, each reproduced and then fixed, shipped as v2.0.0 — among them a closing banner that pointed at a mountpoint the exit trap had already released, and a live-desktop path that udisks automounting could block. The same pass verified the tooling against every M-series Mac the Asahi kernel boots — MacBook Air, MacBook Pro, Mac mini, Mac Studio, iMac and Mac Pro, M1 through M3 — and recorded the result, machine by machine, in docs/COMPATIBILITY.md.
2026-11-20 — Claude Fable 5.2 (Anthropic). A third full audit, by
Anthropic's most capable generally available model, in the week 2.1.0 and 2.2.0
added the RAM rescue, luks-mount.sh and one-command encryption. It read every
script, test and document for ease of use as much as for safety: what a person
actually meets when they mistype, forget sudo, or run a script from the wrong
place. Thirteen findings, each reproduced before it was fixed — on a loop device
or in a KVM guest running the official Fedora Asahi Remix 45 image, released
script and fixed script side by side — and the fixed tree then encrypted that
guest from the RAM rescue, passed the 12-point gate and booted. Among them:
- a passphrase mistyped at
cryptsetup's prompt (two entries that differ, one refused as too weak, a lower-caseyes) ended the whole run, after every other prompt and abtrfs checkof up to half an hour.cryptsetupstops there before writing anything; the script now proves that on the partition and asks again; - a partition menu whose input had closed went round its loop for ever, writing to the deploy log on every pass: 1.5 GB in six minutes;
- both installers treated any argument they did not know as "install", so
install.sh --helpinstalled; - run from a drive mounted on
/mnt, the script mounted the target over its own directory and stopped after the encryption, unable to write the header copy; and on any exit, a dry run included, it unmounted whatever the operator had on/mnt; luks-mount.sh mount /dev/X /mnt/followed byumount /mntleft the volume unlocked, with a stale record; and in a UTF-8 locale it tried/boot/efibefore/boot, so a maintenance chroot silently had no EFI partition;post-encryption-setup.shwarned that it "could not confirm crypt support" in the initramfs of every correctly encrypted system;- from an install that AsahiLocker had itself encrypted, a second install could not be encrypted at all: the first one's mapper name was reported as a leftover from a previous run, with no way forward on offer.
The rest: a forgotten sudo that produced a log file and a page of recovery
advice for an encryption that never started, a silent exit in the
sector-alignment path, a summary that reported 4096-byte sectors for a
512-byte volume, and two tracebacks in uboot-efivar.py. Every script now
answers --help without root and refuses an option it does not know, and
four additions to the tests keep all of it that way: tests/cli-smoke-test.sh,
tests/luks-mount-test.sh, the refused passphrase in the loopback suite, and
the closed-stdin menu.
The fixes shipped as v2.2.1, and v3.0.0 marks the audited state, as
v1.11.0 and v2.0.0 marked the first two. A major number, because the scripts
are deliberately stricter than before: an option a script does not know is an
error, luks-mount.sh umount acts only on what it mounted, and a run from a
place that cannot work is refused before it starts.
The design decisions are the author's; the audits check that the code keeps them. Nothing here has changed hands.
- Noah Petherbridge — for writing up a real
end-to-end run of this tooling on an M3 MacBook Air in September 2026
("Asahi Linux with LUKS Encryption", 19 Sept 2026, on
kirsle.net), including the parts that did not go
smoothly. That write-up is where the
second-install route came from: the observation that the machine would not
boot a USB stick, that the deploy script assumed a live USB and defaulted its
partition menus to the rescue install it was running from, and that the
cleanup afterwards needs
diskutiland a Startup Disk change. TheIN USEexclusions, the hard self-target refusal, the neighbour-awareBOOT/EFIdefaults, theSIBLINGconfirmation, the recovery-bundle warning and docs/SECOND-INSTALL.md all exist because of it. - kernelzeroday — for the RAM-only
rescue. PR #5 and
asahi-ram-rescue showed
that
luks-deploy.shcould encrypt a root in place from the target's own initramfs, with no USB stick and no second install, on a MacBook Air M1 and a MacBook Pro 13" M1. Those runs turned up the two bugs that stopped it: the silentlsblkexit when/isrootfs, and the missing cracklib dictionary that made cryptsetup refuse every passphrase. docs/RAM-RESCUE.md andbin/ram-rescue.shexist because of it.
MIT — see LICENSE.
- Author: William MacKinnon (doug445)
- Email: spilled-bowline0j@icloud.com
- Repository: https://github.com/doug445/AsahiLocker
Copyright (c) 2026 William MacKinnon spilled-bowline0j@icloud.com

