Install on macOS

DMG installer, macFUSE prerequisite, and the Apple Silicon kernel-extension setup that the FUSE mount path requires.

Prerequisites

LUKSbox does not use FUSE-T (the lightweight kext-free FUSE alternative some macOS apps use). The fuser Rust crate that backs LUKSbox's mount layer hard-requires the macFUSE libfuse2 ABI; FUSE-T only ships libfuse3. Switching would require swapping the Rust FUSE wrapper crate, which is on the roadmap but not done yet. If you don't need the mount subcommand, you can skip macFUSE entirely.

DMG installer (recommended)

1. Download luksbox-<version>-aarch64-apple-darwin.dmg (Apple Silicon) or luksbox-<version>-x86_64-apple-darwin.dmg (Intel) from GitHub Releases.
2. Verify the SHA-256 against the value in the release notes:

   shasum -a 256 luksbox-*-apple-darwin.dmg
   # Compare to the row in SHA256SUMS.txt or the Markdown table on
   # the release page.
   

   The .dmg is also Apple-notarised, so Gatekeeper validates the signature chain on first open - but the SHA-256 is your offline integrity check that doesn't depend on Apple's PKI.
3. Open the DMG, drag LUKSbox.app to /Applications, eject.
4. The .app is self-contained: libfido2 + transitive dependencies are bundled under Contents/Frameworks/. You do not need brew install libfido2.
5. Double-click LUKSbox.app. macOS shows the standard "downloaded from internet, are you sure?" prompt once; click Open. Subsequent launches are silent. See the First launch section below for what to expect and how to verify the signature locally.
6. Double-clicking a .lbx file in Finder opens it directly in LUKSbox.

First launch

The .dmg is codesigned with our Developer ID Application certificate (PENTHERTZ, team ID 456J2U7HQL) and notarised by Apple. Double-clicking the downloaded .dmg opens it directly, drag LUKSbox.app to Applications, double-click to run.

The first time you launch any app downloaded from the internet, macOS shows the standard system dialog:

"LUKSbox" is an app downloaded from the Internet. Are you sure you want to open it?

Click Open. This is the same prompt every Mac shows for any downloaded app on first launch - it's not a Gatekeeper warning, just a sanity check on the quarantine flag the browser set when you downloaded the .dmg. Subsequent launches go through without prompting.

You should not see:

• ""LUKSbox" cannot be opened because the developer cannot be verified" - that means the .dmg is unsigned, which it isn't
• "macOS cannot verify that this app is free of malware" - that means the .dmg is signed but not notarised; ours is both
• A right-click -> Open requirement
• A need to run xattr -dr com.apple.quarantine

If you do see one of those, you've downloaded an artifact from a release that predates the signing pipeline (v0.1.0 or earlier) or a binary you built locally without signing. The signing pipeline landed in v0.1.1; verify the SHA-256 against the release notes for v0.1.1 or later and re-download the official .dmg.

Verify the signing chain yourself (optional)

# Confirm the staple is attached and Apple's notary verdict was Accepted
xcrun stapler validate -v /Applications/LUKSbox.app

# Confirm Gatekeeper accepts it as a notarised Developer ID app
spctl --assess --type execute --verbose=4 /Applications/LUKSbox.app
# Expected:
#   /Applications/LUKSbox.app: accepted
#   source=Notarized Developer ID

Enabling macFUSE on Apple Silicon (M1 / M2 / M3 / M4)

This section is the gotcha most macOS users hit. You can skip it if you don't need the mount subcommand; the rest of LUKSbox (CLI, GUI, FIDO2 unlock, file extraction via get, hybrid PQ keyslots) works fine without it.

macFUSE installs a third-party kernel extension. On Apple Silicon Macs (any M-series chip), Apple's default System Integrity Protection posture refuses to load any kext signed by anyone other than Apple, including legitimate ones like macFUSE. To opt in to third-party kexts, you have to lower the boot policy via the Startup Security Utility - and that utility is only reachable from Recovery Mode.

The full one-time setup:

Step 1. Boot into Recovery Mode

1. Apple menu -> Shut Down. Wait for the Mac to fully power off.
2. Press and hold the Power button until "Loading startup options" appears (about 10 seconds).
3. Select Options, then click Continue. macOS Recovery loads; you may be asked to authenticate as an administrator user of the Mac.

Step 2. Open the Startup Security Utility

In the Recovery menu bar at the top of the screen: Utilities menu -> Startup Security Utility.

This is the "Utility mode" the macFUSE installer references in its warning dialog. It exists only inside Recovery; you cannot reach it from a normal boot.

Step 3. Lower the security policy

1. Pick the system disk you want to configure (usually "Macintosh HD").
2. Click Security Policy....
3. Select Reduced Security.
4. Tick the checkbox Allow user management of kernel extensions from identified developers.
5. Click OK, authenticate when prompted, restart.

Step 4. Approve the macFUSE kext

After reboot, install macFUSE from https://macfuse.io/ if you haven't already. macOS will block the kext on first install with a notification along the lines of "System extension blocked - allow in System Settings". Open System Settings -> Privacy & Security, scroll to the bottom, click Allow next to the "System software from developer Benjamin Fleischer was blocked from loading" entry. Authenticate. Restart again.

After that second reboot the kext is loaded and persists across all future boots. luksbox mount works directly with no further prompting.

Why the two reboots?

macOS deliberately makes kext loading a multi-step user-confirmed process to defend against malware that sneaks in a malicious kernel extension. The first reboot (after lowering the policy in Recovery) tells macOS "I'm willing to consider third-party kexts"; the second (after approving in System Settings) actually loads the specific macFUSE kext. Both prompts are permanent for that kext on that Mac; you don't have to repeat this for macFUSE updates that are signed with the same developer ID.

Intel Macs

Intel Macs don't need the Recovery Mode dance. Install macFUSE, approve the kext warning in System Settings -> Privacy & Security when it appears, reboot once, done.

Verifying the download

curl -LO https://github.com/penthertz/LUKSbox/releases/latest/download/SHA256SUMS.txt
shasum -a 256 -c SHA256SUMS.txt

The release notes on each GitHub Release page show the SHA-256 of every artifact in a Markdown table for at-a-glance comparison without downloading the manifest.

Known macOS quirks

• Daemonized mount from a multithreaded process can hit a documented macOS / fork() corner case. LUKSbox's CLI is single-threaded specifically to avoid this; the GUI uses a spawned helper for the mount step.
• Quarantine xattr on hand-extracted binaries: if you cp the CLI binary out of the .app's Contents/MacOS/ to somewhere on $PATH and macOS still shows the "downloaded from internet" prompt every time you run it, clear the xattr once with xattr -d com.apple.quarantine /path/to/luksbox. The standard drag-the-.app-to-Applications path doesn't trigger this; only cp-out-of-DMG-into-PATH does.
• macFUSE blocks at first mount, not at install: if you skipped the Apple Silicon setup above and try luksbox mount anyway, the FUSE mount call fails with a permission error (the kext isn't loaded). Run through the Recovery Mode steps then retry.

Skipping macFUSE entirely

If you don't want to lower the boot security policy on Apple Silicon, you can use LUKSbox without the mount subcommand:

• GUI: open vaults directly in the LUKSbox window. The built-in browser lets you navigate, extract, and re-encrypt files inside the vault without ever mounting it as a drive.
• CLI: luksbox ls, luksbox get, luksbox put, luksbox cat, luksbox mkdir, luksbox rm all work without macFUSE. Only luksbox mount requires the kext.

For a vast majority of single-user use cases, this is the recommended posture: the kext-free path keeps your Mac at the default Apple security level.

TPM-style hardware-bound keyslots on macOS

LUKSbox's hardware-bound keyslot kinds (Tpm2Sealed and the fused Tpm2Fido2) are Linux-only for now. The macOS-native equivalent - Secure Enclave-backed wrapping via SecKey / CryptoKit - is on the roadmap (see SECURITY.md Tier 3 item 10) but not yet shipped. Estimated ~2 weeks of work once Apple Developer enrollment completes (the cert is needed to sign binaries that call into the Secure Enclave APIs without Gatekeeper friction).

For the moment, macOS users get passphrase / FIDO2 / hybrid-PQ keyslots. All three work identically to the Linux versions; only the at-rest hardware-binding feature is missing. If you copy a vault between Linux (with a TPM slot enrolled) and macOS, the TPM slot is invisible to macOS but other slots in the same vault unlock normally.

Memory protection on macOS (current state + roadmap)

The Linux build of LUKSbox stores the unlocked Master Volume Key in memfd_secret(2) pages, which are unmappable from any other process even by root. macOS has no equivalent syscall, so the macOS build falls back to a regular heap allocation with these mitigations layered on top:

• mlockall(MCL_CURRENT | MCL_FUTURE) to keep keys out of swap (when RLIMIT_MEMLOCK permits; the install script doesn't raise this).
• setrlimit(RLIMIT_CORE, 0) to suppress coredumps that would contain the key.
• Zeroize-on-drop to wipe the key bytes when their containing scope exits.
• Constant-time compares on every key equality check.

This is "as good as a disciplined Mac app" - same posture as 1Password's and Bitwarden's macOS apps - and on a single-user Mac with FileVault enabled it covers the realistic threats. A same-machine root attacker (or a process holding the com.apple.security.cs.debugger entitlement) can still read the unlocked MVK from the LUKSbox process memory; on Linux the memfd_secret pages would refuse to map even for root.

On the roadmap: macOS-native MVK storage in the Secure Enclave (the SEP coprocessor on Apple Silicon and T2 Intel Macs). Keys would live inside the enclave hardware boundary, never exposed to the main CPU; AEAD operations would happen through Apple's SecKey / CryptoKit APIs over IPC. Trade-offs the design has to handle: per-chunk IPC overhead (throughput drops from ~590 MB/s in-process AES-NI to a few hundred MB/s through the enclave), the Secure Enclave doesn't natively support AES-256-GCM-SIV (only AES-GCM and ChaCha20-Poly1305), and SEP-bound MVKs aren't portable between Macs (would need a key-wrapping mode to keep the vault file movable). Tracked in SECURITY.md Tier 3 item 10. Estimated ~2 weeks of design + implementation; not blocking the 1.0 milestone but the right macOS-native posture.