Yubikey for Debian root on native encrypted ZFS

README.md

Information

Following instructions enable 2FA via Yubikey challenge-response for Debian root native encrypted ZFS.

For general setup please follow the instructions in the OpenZFS Documentation.

Prepare Yubikey

Install management tools.

$ apt install yubikey-manager yubikey-personalization

Set up slot 2 in challenge-response mode with a generated key and enable touch to generate a response.

$ ykman otp chalresp --touch --generate 2

Prepare initramfs hook

Create the zfs-initramfs hook /etc/zfs/initramfs-tools-load-key.

trap 'stty echo' INT

stty -echo
printf "ZFS rpool challenge: "
read CHALLENGE
stty echo
printf "\n"

echo $CHALLENGE | ykchalresp -2 -i- | $ZFS load-key "${ENCRYPTIONROOT}"

Create the initramfs-tools hook /etc/initramfs-tools/hooks/yubikey-zfs

#!/bin/sh

set -e

PREREQ="zfs-initramfs"

prereqs()
{
    echo "$PREREQ"
}

case $1 in
    prereqs)
    prereqs
    exit 0
    ;;
esac

. /usr/share/initramfs-tools/hook-functions

copy_exec /usr/bin/ykchalresp
copy_exec /usr/bin/ykinfo

exit 0

Update initramfs

$ update-initramfs -u -v

Enroll Yubikey challenge-response

$ echo $CHALLENGE | ykchalresp -2 -i- | zfs change-key rpool

Hi!

I followed your directions, except I did not encrypt the root filesystem but I created an encrypted filesystem rpool/encrypted under it.
I used your code as-is

I believe I should be prompted for the challenge at some point during boot, but I am not.
If I run the script /etc/zfs/initramfs-tools-load-key after setting the ZFS and the ENCRYPTIONROOT variables after login I can then mount the encrypted filesystem.

Is there anything else/more that I should do?

This is my system configuration

# cat /etc/devuan_version 
excalibur/ceres

# cat /etc/debian_version 
13.0

# dpkg -l | grep zfs
ii  libzfs6linux:amd64                                       2.3.2-2                                  amd64        OpenZFS filesystem library for Linux - general support
ii  zfs-dkms                                                 2.3.2-2                                  all          OpenZFS filesystem kernel modules for Linux
ii  zfs-initramfs                                            2.3.2-2                                  all          OpenZFS root filesystem capabilities for Linux - initramfs
ii  zfs-zed                                                  2.3.2-2                                  amd64        OpenZFS Event Daemon
ii  zfsutils-linux                                           2.3.2-2                                  amd64        command-line tools to manage OpenZFS filesystems

# uname -r
6.12.35+deb13-amd64

Thanks in advance.

Hi,

thanks for your interest. I've created a Debian package https://github.com/tschaefer/yubikey-zfs-initramfs. Maybe you can checkout, if the enrollment works with that. If not feel free to get in touch with me again.

Cheers.

Tank you. I teste the deb package also, but it does not work either. The boot goes on without asking any challenge nor to touch the key, and of course the filesystem doesn't get mounted roberto resecco Il Sab 19 Lug 2025, 17:17 Tobias Schäfer ***@***.***> ha scritto:

…

***@***.**** commented on this gist. ------------------------------ Hi, thanks for your interest. I've created a Debian package https://github.com/tschaefer/yubikey-zfs-initramfs. Maybe you can checkout, if the enrollment works with that. If not feel free to get in touch with me again. Cheers. — Reply to this email directly, view it on GitHub <https://gist.github.com/tschaefer/e3e5454c114f19a323f7c926118a80de#gistcomment-5682597> or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACXMXUIW243A6BJNBDM7TV33JJOOXBFKMF2HI4TJMJ2XIZLTSKBKK5TBNR2WLJDUOJ2WLJDOMFWWLO3UNBZGKYLEL5YGC4TUNFRWS4DBNZ2F6YLDORUXM2LUPGBKK5TBNR2WLJDHNFZXJJDOMFWWLK3UNBZGKYLEL52HS4DFVRZXKYTKMVRXIX3UPFYGLK2HNFZXIQ3PNVWWK3TUUZ2G64DJMNZZDAVEOR4XAZNEM5UXG5FFOZQWY5LFVEYTEOJRG44TAMJUU52HE2LHM5SXFJTDOJSWC5DF> . You are receiving this email because you commented on the thread. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub> .

I regret your set up will not work.
I checked the related zfs-initramfs script /usr/share/initramfs-tools/scripts/zfs, if it doesn't find the encryptionroot from the zfs dataset presented in the kernel cmdline options root=ZFS=rpool/ROOT/debian, it will not run the above hook.
Put simply, the entire pool must be encrypted.

For further info see /usr/share/doc/zfs-initramfs-2.3.3/README.md.gz.