ZFS Native Encryption v0.8

I have seen many sites writing about all the cool new features in ZFS on Linux v0.8. However googling around I have found no documentation about how to actually use the new encryption feature. So While I absolutely LOVE zfs. I am disappointed in the state of documentation.

OpenZFS wiki still talks about ZFS Encryption development talk coming in 2016.

After digging through the man pages I found the information I need. However It’s not so convenient especially for new users to ZFS. The rest of this article I will try to create the missing document for my own reference in the future and probably why you are reading this now.

Limitations

  • ZFS Encryption requires v0.8 or newer.
  • The pool on disk format must be upgraded to match the ZFS version.
  • ZFS encryption is turned on at the time of dataset creation and cannot be applied to old datasets. (See below for workaround).
  • Encryption algorithm can’t be changed after dataset creation.

What options do we have?

There are several options to choose from when we create a new dataset. The two mandatory options for encryption are keyformat and algorithm.

Key options include:

  • raw
  • hex
  • passphrase

Encryption algorithm options include:

  • aes-128-ccm
  • aes-192-ccm
  • aes-256-ccm
  • aes-128-gcm
  • aes-192-gcm
  • aes-256-gcm

Create a encrypted dataset using a password:

zfs create tank/TopSecret -o encryption=on -o keyformat=passphrase

After running the above command we will be asked to type in our password.

Note: If we use encryption=on and don’t choose an algorithm ZFS will default to aes-256-ccm.

Managing keys:

So we have copied our super secret data to our pool. Now how do we secure it? first we have to unmount the dataset. After that we have to unload the key from ram.

zfs unmount tank/TopSecret
zfs unload-key tank/TopSecret

Now if we try to mount the dataset we don’t have access anymore.

zfs mount tank/TopSecret
cannot mount 'tank/TopSecret': encryption key not loaded

To access or data after we have unloaded the key or a reboot of the system has happened we have to load the key again.

zfs mount -l tank/TopSecret
************

Note: Using -l allows us to load the key and mount all with one command.

Data migration

As talked about in the limitations section we can’t turn on encryption to an already existing dataset. So we will have to copy our data. Rsync would do or we can use a zfs send. By sending our existing dataset into a encrypted one it will become encrypted by inheritance.

zfs snapshot tank/oldData@send
zfs send tank/oldData@send | zfs recv tank/TopSecret/oldData

Note: We can’t receive snapshot history in this way. It only works with a single snapshot. So we will have to abandon them

Thanks for reading this basic intro to ZFS encryption. I hope this was helpful. More information can be found in the ZFS man page. If I have made any mistakes or you have any feedback for improvements to this article please use the contact page.