diff --git a/docs/zlevis/implementation.md b/docs/zlevis/implementation.md new file mode 100644 index 0000000..e83a2a4 --- /dev/null +++ b/docs/zlevis/implementation.md @@ -0,0 +1,53 @@ +## Mkinitfs + +[Mkinitfs](https://gitlab.alpinelinux.org/alpine/mkinitfs) is the `initramfs` generator of [Alpine Linux](https://alpinelinux.org/). Among the usual operations to setup `zlevis`, i.e. writing the encryption key of the ZFS root pool to the TPM after the creation of the ZFS root pool, enabling the `zlevis-hook` in `mkinitfs.conf` and installing `zlevis` on the host system, we require to make an adaptation to the `initramfs-init` script of `mkinitfs`. + +Particularly, in the `prepare_zfs_root()` function we need to add the option `zlevis decrypt "$_root_pool" | zfs load-key -L prompt "$_root_pool"`: + + +``` shell title="/usr/share/mkinitfs/initramfs-init" hl_lines="19" linenums="385" +# Do some tasks to make sure mounting the ZFS pool is A-OK +prepare_zfs_root() { + local _root_vol=${KOPT_root#ZFS=} + local _root_pool=${_root_vol%%/*} + + # Force import if this has been imported on a different system previously. + # Import normally otherwise + if [ "$KOPT_zfs_force" = 1 ]; then + zpool import -N -d /dev -f $_root_pool + else + zpool import -N -d /dev $_root_pool + fi + + + # Ask for encryption password + if [ $(zpool list -H -o feature@encryption $_root_pool) = "active" ]; then + local _encryption_root=$(zfs get -H -o value encryptionroot $_root_vol) + if [ "$_encryption_root" != "-" ]; then + zlevis decrypt "$_root_pool" | zfs load-key -L prompt "$_root_pool" || eval zfs load-key $_encryption_root + fi + fi +} +``` + +Retaining the fallback to `eval zfs load-key` with the `||` operator. + +Furthermore, we need to configure the `zlevis-hook` by notifying `mkinitfs` which binaries and libraries to add into the `initramfs`: + +``` shell title="/etc/mkinitfs/features.d/zlevis.files" +/usr/bin/zlevis +/usr/bin/zlevis-decrypt +/usr/bin/tpm2* +/usr/bin/jose +/usr/lib/libtss2-tcti* +``` + +and to notify what kernel drivers are required: + +``` shell title="/etc/mkinitfs/features.d/zlevis.modules" +kernel/drivers/char/tpm* +``` + +## Dracut + +Work in progress. \ No newline at end of file