eZFS2FA+ is a hardened encrypted ZFS dataset interactive workflow offering two-factor authentication for sensitive services on FreeBSD systems, with Linux compatibility built in.
💡 The idea is simple: protected services do not start at boot. Their secrets live inside an OpenZFS encrypted dataset that remains locked until the operator explicitly unlocks it.
🔐 The key is wrapped using a FIDO Alliance compatible hardware token (like the keys manufactured by Yubico), a passphrase, or both (recommended).
🥇 FreeBSD is the first-class target. On FreeBSD, transient raw key material is handled through 𝚖𝚍𝚖𝚏𝚜 -𝙼, using 𝚖𝚊𝚕𝚕𝚘𝚌-backed 𝚖𝚍(𝟺) storage.
🐧 On Linux, the same workflow uses 𝚛𝚊𝚖𝚏𝚜.
🚫 In both cases, the raw ZFS key is kept out of normal filesystems or swappable memory. Wiped immediately after use, it never touches hard storage.
ℹ️ This tool supports multiple enrolled keys, a single JSON state file for wrapped-key backup, service-start checks, delayed forced locking, and optional lock-time snapshots.
👌🏻 This design protects data at rest and against offline theft scenarios. It is built for the real risk of a portable system being lost, stolen, or imaged while powered off.
With eZFS2FA+, there is no framework lock-in:
for example, you can securely zfs send your raw encrypted dataset to any target.
Just export the ZFS raw encryption key to decrypt it in that new location, even if it doesn't use the eZFS2FA+ framework.
The dependencies are minimal: python3 plus cryptography library, plus:
- Preferred on all OS: python-fido2.
- FreeBSD/Linux fallback: libfido2 CLI tools.
- Windows path: python-fido2 with native WebAuthn.
- python311
- py311-cryptography
- python-fido2 https://github.com/Yubico/python-fido2
- libfido2
- python3
- python3-cryptography
- python-fido2 https://github.com/Yubico/python-fido2
- fido2-tools
- zfsutils-linux (assumed installed already for ZFS users)
- util-linux
This section is for the adventurers: it requires the experimental OpenZFS for Windows port and some manual work, it isn't plug-N-play!
-
python-fido2 https://github.com/Yubico/python-fido2
-
python -m pip install fido2 -
or
py -3 -m pip install fido2
python ezfs2fa.py doctor
While the package can be used standalone without installation, it can be installed, including a manpage generated from the included markdown documentation.
On the target system, run the following:
git clone https://github.com/BillieBadin/eZFS2FA
cd eZFS2FA
doas sh ./install.sh # FreeBSD
or
sudo sh ./install.sh # FreeBSD / Linux
ezfs2fa --helpSecret buffers are wiped in-memory on a best-effort basis with mutable byte arrays. As with all Python code, runtime internals can still retain transient immutable copies.
ALWAYS make backups of the JSON file with the wrappers. It contains vital information and useless without at least a full wrapper per encrypted dataset: passphrase and/or hardware key; without them or an raw ZFS key, the data is unrecoverable.
If you upgrade from legacy wrapper records, upgrade them explicitly with:
ezfs2fa upgrade-wrappers
ezfs2fa pack creates an unencrypted tar.gz archive of that JSON file.
While the material in that file has no raw keys, encrypting that archive or storing it in an encrypted media is recommended prior to placing it on shared/offsite storage.
An export of the ZFS raw key is also strongly recommended.
It provides a native recovery path, fully independant from the wrapping technology used in eZFS2FA+.
That key material oviously needs to be handled with utmost care, and be stored in a very secure and safe offline location.
This project is licensed under the MIT Licence. See LICENSE.
Copyright (c) 2026 Billie Badin, SIGORYX Engineering