Skip to content

About

The complete, audited way to encrypt Asahi Linux (Fedora Asahi Remix) with LUKS2: in place, in one command, no reinstall, no USB stick needed, macOS untouched. Apple Silicon M1/M2/M3. argon2id at 4 GiB (5x stock), resumable after a power cut, 12-point boot gate, audited three times, 100+ CI checks.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

AsahiLocker logo: a faceted pink and silver polyhedron bearing the Fedora mark and the Asahi Linux 'A', standing on a dark angular platform lit with magenta and blue neon

AsahiLocker — in-place LUKS2 disk encryption for Fedora Asahi Remix on Apple Silicon

CI License: MIT Free and open source Platform: Apple Silicon KDF: argon2id

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.md before running anything, and have a verified backup. See Risks.


Why AsahiLocker

  • 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 cryptsetup can write, by default. argon2id at 4 GiB x 10: five times the work per guess of a stock luksFormat on 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 /boot that 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.sh on 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.

Security at a glance

  • 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 cryptsetup will 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 luksFormat on the same Mac. A runtime guard refuses to write anything weaker than what cryptsetup would 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.


Quick start

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


What you get

  • 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 cryptsetup allows (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 plain luksFormat on the same machine, and the strongest does 5x. Before it writes anything the installer benchmarks what cryptsetup would 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 --list shows every install on the Mac and its state; luks-deploy.sh /dev/nvme0n1pN --defaults encrypts one, with /boot and 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.sh lists, 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-run that really is dry. The entire read-only half, including the exact cryptsetup reencrypt invocation 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-mkconfig from bricking an encrypted boot, and clears U-Boot's stale EFI entries — in the file they actually live in (ubootefi.var on the ESP), which a runtime efibootmgr delete never reaches.
  • Tested in CI on every push, on aarch64 runners, against a real loop device.

What's in here

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.

How the encrypted boot actually works on Apple Silicon

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 /boot is 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.

Partition layout, before and after

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.


Crypto parameters — AES-256-XTS and argon2id

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.

Choosing an argon2id profile

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.

The luks-deploy.sh KDF profile prompt, showing three argon2id profiles with unlock times benchmarked on the running machine, aggressive marked as the default

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.


Deployment options

Dry run

sudo ./bin/luks-deploy.sh --dry-run     # or LUKS_DRY_RUN=1

Runs 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.

Boot splash

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.

Recovery key

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-/boot research. See docs/CRYPTO.md → GRUB and argon2id.


How this differs from encrypting by hand

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.


Risks — read this

  • 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; /boot is 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.sh restores it, precisely so this prompt stays visible on the first encrypted boots.)

Requirements

  • 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 --arm on the system you want encrypted, reboot, type asahilocker — see docs/RAM-RESCUE.md. It needs gdisk and 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-usb as described in docs/LIVE-USB.md. If the stick looks dead at the U-Boot prompt, try usb start before 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.
  • AC power connected (the script enforces AC or >50% battery).
  • cryptsetup ≥ 2.4 (for reencrypt --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.


Frequently asked questions

Every question and its full answer is in docs/FAQ.md:


Documentation

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

Contributing

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.

Audit

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-case yes) ended the whole run, after every other prompt and a btrfs check of up to half an hour. cryptsetup stops 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 --help installed;
  • 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 by umount /mnt left the volume unlocked, with a stale record; and in a UTF-8 locale it tried /boot/efi before /boot, so a maintenance chroot silently had no EFI partition;
  • post-encryption-setup.sh warned 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.

Acknowledgements

  • 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 diskutil and a Startup Disk change. The IN USE exclusions, the hard self-target refusal, the neighbour-aware BOOT/EFI defaults, the SIBLING confirmation, 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.sh could 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 silent lsblk exit when / is rootfs, and the missing cracklib dictionary that made cryptsetup refuse every passphrase. docs/RAM-RESCUE.md and bin/ram-rescue.sh exist because of it.

License and contact

MIT — see LICENSE.

Copyright (c) 2026 William MacKinnon spilled-bowline0j@icloud.com

About

The complete, audited way to encrypt Asahi Linux (Fedora Asahi Remix) with LUKS2: in place, in one command, no reinstall, no USB stick needed, macOS untouched. Apple Silicon M1/M2/M3. argon2id at 4 GiB (5x stock), resumable after a power cut, 12-point boot gate, audited three times, 100+ CI checks.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages