Hardened encrypted ZFS datasets with FIDO2 hardware-token two-factor authentication β FreeBSD-first, Linux-compatible, zero lock-in.
eZFS2FA+ is a hardened FreeBSD-first interactive workflow for wrapping encrypted OpenZFS dataset keys with FIDO2-backed two-factor authentication β with full Linux compatibility built in.
The core idea: protected services do not start at boot. Their secrets live inside encrypted OpenZFS datasets that remain locked until the operator explicitly unlocks them with a FIDO2-compatible hardware token (such as those made by Yubico), a passphrase, or both.
On FreeBSD, the transient raw key material is held in
mdmfs -M
(malloc-backed md(4) storage) β never touching swappable memory or hard storage. On Linux, the equivalent is ramfs. The raw key is wiped immediately after the dataset is unlocked.
Created by Billie Badin of SIGORYX Engineering, developed on Pi-BSD running on an untethered battery-powered stack. MIT licensed. Code in the open.
"This is what FreeBSD-first looks like when someone actually means it."
The threat model is stated honestly. eZFS2FA+ protects against a powered-off machine being lost, stolen, or imaged β not against a live compromise at unlock time. The right line to draw, drawn out loud. One sees that less often than one would hope.
The zero lock-in principle is structural, not promotional. Back up the ZFS raw key offline and the framework becomes optional. The user keeps their own dataset.
The development platform is Pi-BSD on an untethered battery-powered stack. The kind of small, deliberate, hand-built work that one used to see more of β a nod to Wabi-Sabi (δΎε―) design philosophy.
eZFS2FA+ states its threat model explicitly β a quality that Vivian Voss specifically praises. The boundaries are clear:
A powered-off machine being lost, stolen, or forensically imaged. Without the enrolled FIDO2 token (and passphrase if configured), the encrypted ZFS dataset cannot be decrypted.
A live, fully compromised root or kernel at the time of unlock. If an attacker has root access when you unlock the dataset, the key can be extracted from memory.
Transient ZFS key held in malloc-backed kernel memory. Never swapped, never written to disk. Wiped immediately after dataset unlock. Uses FreeBSD's native md(4) primitive.
Linux-equivalent of mdmfs -M. An in-kernel filesystem that cannot be swapped to disk. Holds the transient ZFS key during the unlock window. Design respects BSD primitives rather than pretending the two systems are interchangeable.
The ZFS encryption key is wrapped (encrypted) using a FIDO2 hardware token (e.g., YubiKey), a passphrase, or both. The raw key is never stored directly.
All wrapped key copies for enrolled tokens live in a single JSON file. Easily backed up for disaster recovery. The raw key is never in this file β only the wrapped form, safe to store.
The raw ZFS key can be backed up independently and used with standard zfs send to any target. Once the key is secured offline, eZFS2FA+ becomes optional β the user retains full ownership of their dataset.
Developed on Pi-BSD running on a battery-powered ARM single-board computer. A deliberate, minimal development environment β as Vivian Voss notes, the kind of hand-built work one used to see more of.
Enrol several FIDO2 tokens so any one can unlock the dataset. Supports backup-key workflows without compromising the zero lock-in principle.
Dependent services are held until the dataset is explicitly unlocked by the operator. No accidental service startup with a locked dataset.
Configurable timer that forces the dataset to re-lock after a defined period, limiting the window during which the key is accessible.
Automatically take a ZFS snapshot at lock time, providing a consistent restore point before the dataset is secured again.
Support for encrypted ZFS removable media (including mirrored configurations) is coming soon. Proxmox Server Solutions integration is also in progress.
Simple setup: git clone + doas sh ./install.sh (FreeBSD) or sudo sh ./install.sh (Linux). Python 3, cryptography, and libfido2/fido2-tools required.
On FreeBSD: install python3, py-cryptography, and libfido2 via ports or pkg. On Linux: install python3-cryptography and fido2-tools. Then clone the repo:
git clone https://github.com/BillieBadin/eZFS2FA.git
Execute the installation script with appropriate privileges:
# FreeBSD doas sh ./install.sh # Linux sudo sh ./install.sh
Follow the interactive workflow to enrol your FIDO2-compatible hardware token. You may also enrol a passphrase, or use both (recommended for maximum protection). The wrapped key is stored in the JSON state file.
Configure the encrypted ZFS dataset to remain locked at boot. Set up service-start checks so that dependent services only start after the dataset is unlocked. Optionally configure delayed forced locking and lock-time snapshots.
To unlock the dataset, present your FIDO2 token (and passphrase if configured). The transient ZFS key is materialised in malloc-backed md(4) (FreeBSD) or ramfs (Linux), the dataset is unlocked, the key is immediately wiped. Dependent services may then start.
Open authentication standard enabling hardware-token-based authentication. In eZFS2FA+, a FIDO2 token wraps the ZFS encryption key.
FreeBSD command creating a malloc-backed memory filesystem. Non-swappable, non-persistent β ideal for transient cryptographic key storage.
Open-source ZFS filesystem with native encryption. eZFS2FA+ secures OpenZFS-encrypted datasets by wrapping their keys with FIDO2 tokens.
Linux in-memory filesystem that cannot be swapped. Used by eZFS2FA+ on Linux for transient key storage, analogous to mdmfs -M on FreeBSD.
A ZFS key encrypted by a FIDO2 token or passphrase. Stored safely in the JSON state file; the raw key only recoverable by presenting the original credential.
The raw ZFS key in usable form, held only in volatile RAM during the unlock window and wiped immediately after use.
Design principle ensuring that users can always recover their data without eZFS2FA+, by maintaining an offline backup of the raw ZFS key.
Formal statement of what a security system protects against and what it does not. eZFS2FA+'s: offline attack protection, not live root compromise protection.
Multi-Factor Authentication β two or more independent credentials. eZFS2FA+ implements MFA for ZFS unlock via FIDO2 token (something you have) + passphrase (something you know).
FreeBSD for Raspberry Pi and ARM SBCs. Used as eZFS2FA+'s development platform β a deliberate, minimal, untethered stack embodying Wabi-Sabi (δΎε―) design.
Interactive D3.js force-directed visualization of the eZFS2FA+ knowledge graph. Click any node to explore its entity description via URIBurner; click edge labels to resolve predicate IRIs. Double-click a node to pin/unpin it.