74 lines
4.7 KiB
ReStructuredText
74 lines
4.7 KiB
ReStructuredText
Native Encryption
|
|
=================
|
|
|
|
ZFSBootMenu can import pools or filesystems with native encryption enabled. If your boot environments are not encrypted
|
|
but, for example, ``/home`` is, you will not receive a decryption prompt during boot. To ensure that you can decrypt
|
|
your pool to load the kernel and initramfs, you'll need to you have the filesystem parameters configured correctly.
|
|
|
|
It's critical that ``keyformat`` is set to ``passphrase``, otherwise you'll be unable to enter the correct value in the
|
|
bootloader. OpenZFS currently supports only one key, but in a way which ZFSBootMenu can exploit: if you configure the
|
|
``keylocation`` value to a file on disk, put your passphrase in that, and then include that file into the FINAL
|
|
initramfs (the one in the ``/boot`` subdirectory of your encrypted root), you won't receive a second password prompt on
|
|
boot. When ZFSBootMenu attempts to unlock root filesystems, it will override any ``file://`` URI it encounters as a
|
|
``keylocation`` if that file is not accessible from within the bootloader image. This allows ZFSBootMenu to prompt for
|
|
passphrases when necessary.
|
|
|
|
.. note::
|
|
|
|
**Never** place encryption keys inside a custom ZFSBootMenu image! The ZFSBootMenu image will typically be installed
|
|
on an unencrypted partition with minimal or no access restrictions. If an encryption key is placed in such a location,
|
|
anybody with access to the system will be able to read your passphrase.
|
|
|
|
As an example, Consider a filesystem layout such as::
|
|
|
|
zfs get all zroot | egrep '(encryption|keylocation|keyformat)'
|
|
zroot encryption aes-256-gcm -
|
|
zroot keylocation file:///etc/zfs/zroot.key local
|
|
zroot keyformat passphrase -
|
|
zroot encryptionroot zroot -
|
|
|
|
On systems that use ``dracut``, the key for ``zroot`` can be added to initramfs images by running::
|
|
|
|
echo 'install_items+=" /etc/zfs/zroot.key "' > /etc/dracut.conf.d/zfs-keys.conf
|
|
|
|
For ``mkinitcpio``, add the key to the ``FILES`` array in ``mkinitcpio.conf``::
|
|
|
|
echo 'FILES+=(/etc/zfs/zroot.key)' >> /etc/mkinitcpio.conf
|
|
|
|
.. note::
|
|
|
|
When adding encryption keys to initramfs images, **always ensure** that the resulting images are not readable by any
|
|
user other than root. Recent versions of ``dracut`` and ``mkinitcpio`` ensure this by default with umask of ``0077``.
|
|
Users with read access to your initramfs image will be able to read your ZFS key file even if it has mode ``000`` in
|
|
the image; always confirm for your self that the initramfs is protected!
|
|
|
|
For convenience, ZFSBootMenu recognizes the ZFS property ``org.zfsbootmenu:keysource`` as the name of a filesystem that
|
|
should be searched for ZFS key files. When a boot environment specifies a ``file://`` URI as its ``keylocation``,
|
|
ZFSBootMenu will attempt to mount a filesystem indicated by the ``org.zfsbootmenu:keysource`` property (if it exists)
|
|
and search for the named ``keylocation`` therein. If found, ZFSBootMenu will copy the key into a cache within the
|
|
in-memory root filesystem so that subsequent operations that require reloading the key (for example, changing the
|
|
default boot environment or cloning a snapshot) will not prompt the user for passphrases.
|
|
|
|
When searching for a ``keylocation`` relative to the filesystem named by ``org.zfsbootmenu:keysource``, ZFSBootMenu will
|
|
first try to strip the ``mountpoint`` of the keysource filesystem from any ``keylocation`` URI that references the keys
|
|
to map the ``keylocation`` that would be observed on a running system to the proper location in the keysource. For
|
|
example, if the running system is set up so that ``zroot`` is the ``encryptionroot`` for all filesystems on a pool,
|
|
running the commands::
|
|
|
|
zfs create -o mountpoint=/etc/zfs/keys zroot/keystore
|
|
echo "MySecretPassphrase" > /etc/zfs/keys/zroot.key
|
|
chmod 000 /etc/zfs/keys/zroot.key
|
|
zfs set keylocation=file:///etc/zfs/keys/zroot.key zroot
|
|
zfs set org.zfsbootmenu:keysource=zroot/keystore zroot
|
|
echo 'install_optional_items+=" /etc/zfs/keys/zroot.key "' >> /etc/dracut.conf.d/zol.conf
|
|
|
|
will cause ZFSBootMenu to attempt to cache the key ``file:///etc/zfs/keys/zroot.key`` from ``zroot/keystore`` when
|
|
unlocking the ``zroot`` pool. Because ``zroot/keystore`` specifies ``mountpoint=/etc/zfs/keys``, ZFSBootMenu will first
|
|
try to strip ``/etc/zfs/keys`` from the ``keylocation`` URI, looking for the file ``zroot.key`` at the root of the
|
|
filesystem ``zroot/keystore``. If this fails, ZFSBootMenu will fall back to the full path, looking for
|
|
``etc/zfs/keys/zroot.key`` within the keysource filesystem. If either location is found, ZFSBootMenu will retain a cache
|
|
of the key should it be needed to unlock the pool again.
|
|
|
|
..
|
|
vim: softtabstop=2 shiftwidth=2 textwidth=120
|