in Oracle Solaris

Understanding ZFS Encryption – Tutorial

Using ZFS encryption is straightforward, we can protect our file system using a passphrase which can be specified during the file system mount operation or using a key file (wrapping key) that allow the file system to be mounted automatically.

Let’s quickly review some advantage and requirement for encrypted zfs file system.


  • Strong encryption: the file system is encrypted using AES (Advanced Encryption Standard) with various key length 128 (default is 128 in ccm mode) , 192 or 256.
  • Inheritance: all descendant file system are encrypted and we can use delegation for key management.
  • Hardware and software integration: zfs encryption is based on Oracle Solaris Cryptographic Framework which mean that it can take advantage of hardware or software optimization/acceleration.
  • ZFS command line integration: for ease of management and scripting

Before using zfs encryption we should note that there also some requirements:

    • zpool version: the zpool version should be 30 or higher
    • Root file system: the as of this writing, root file system cannot be encrypted
    • The zfs encryption property is read-only, you can not set it after the file system was created
    • Passphrase should be at least 8 characters in length

Let’s start by checking the current configuration of the our zpool.

root@sol01:~# zpool upgrade -v
This system is currently running ZFS pool version 35.

Enabling encryption can be done at the zfs pool or at the file system level, for the later, we use the following command during file system creation:

root@sol01:~# zfs create -o encryption=on datapool/project1

Ecrypted zfs file system will not be mounted automatically during the system boot phase, it must be done manually.

Automatically mounting an encrypted zfs file system

The zfs keysource property control how and where the key is stored (local or remote), the format can be one of this three value: raw, hex, passphrase and the location can be one of the following: prompt, file, pkcs11 or https.

root@sol01:~# zfs get all datapool/project1 | egrep "encr|key"
datapool/project1  encryption            on                     local
datapool/project1  keychangedate         Tue Jan 12 19:13 2016  local
datapool/project1  keysource             passphrase,prompt      local
datapool/project1  keystatus             available              -
datapool/project1  rekeydate             Tue Jan 12 19:13 2016  local

We will create a file system that will be mounted automatically during the boot process and we will change the encryption key length to 256.
First we need to generate an encryption key using the pktool utility:

root@sol01:~# pktool genkey keystore=file outkey=/projectx.key keytype=aes keylen=256

Then we create our encrypted file system using our generated key and reboot to see if it get mounted automatically.

root@sol01:~# zfs create -o encryption=aes-256-ccm -o keysource=raw,file:///projectx.key datapool/projectx
root@sol01:~# zfs get all datapool/projectx | egrep "encr|key"
datapool/projectx  encryption            aes-256-ccm               local
datapool/projectx  keychangedate         Tue Jan 12 20:38 2016     local
datapool/projectx  keysource             raw,file:///projectx.key  local
datapool/projectx  keystatus             available                 -
datapool/projectx  rekeydate             Tue Jan 12 20:38 2016     local
root@sol01:~# zfs unmount datapool/projectx
root@sol01:~# init 6

After the reboot we can see that the file system datapool/projectx get mounted and doesn’t require a passphrase in the other hand datapool/project1 doesn’t get mounted, we need to do it manually and specify the passphrase.

root@sol01:~# zfs mount /datapool/project1
Enter passphrase for 'datapool/project1': 
root@sol01:~# zfs mount datapool/project1x
cannot mount 'datapool/projectx': filesystem already mounted
root@sol01:~# zfs mount
rpool/ROOT/solaris              /
rpool/ROOT/solaris/var          /var
rpool/VARSHARE                  /var/share
datapool                        /datapool
datapool/projectx               /datapool/projectx
devops                          /devops
rpool/export                    /export
rpool/export/home               /export/home
rpool/export/home/jack          /export/home/jack
rpool/export/home/julie         /export/home/julie
rpool/export/home/julie/bug123  /export/home/julie/bug123
rpool/export/home/me            /export/home/me
rpool                           /rpool
rpool/newhome                   /rpool/newhome
rpool/newproject                /rpool/newproject
rpool/project1                  /rpool/project1
rpool/VARSHARE/zones            /system/zones
rpool/newhome/david             /var/home/david
rpool/VARSHARE/pkg              /var/share/pkg
rpool/VARSHARE/pkg/repositories  /var/share/pkg/repositories
datapool/project1               /datapool/project1

Copying zfs encrypted file system

We can use the zfs send and zfs recv command to send encrypted data only if the source and destination have encryption enabled. Sending unencrypted file system isn’t supported.
If we need to copy unencrypted data to an encrypted file system we should use the standard unix command like cp or rsync.

Example of sending encrypted file system:

root@sol01:~# zfs create -o encryption=on datapool/project007
Enter passphrase for 'datapool/project007': 
Enter again: 
root@sol01:~# zfs snapshot datapool/project1@backup 
root@sol01:~# zfs send datapool/project1@backup | zfs recv -Fv datapool/project007
receiving full stream of datapool/project1@backup into datapool/project007@backup
received 47.6KB stream in 1 seconds (47.6KB/sec)

As per Oracle Solaris documentation the datapool/project1 stream is not encrypted during the send process.


Find this useful! spread the word, share your knowledge

Write a Comment


  1. hi. is there any benefit to encrypting datasets residing on fibre channel LUNs or iSCSI disks? it make sense to do it on hard drives and USB disks, but i don’t see any benefit of doing it on remote storage. could you comment please? thanks

    • Hi, the majority of the storage array on the market provide data encryption which will offload (if enabled) the process to the storage array.
      At the zfs level, it will really depend on the business requirement, for me, as long as it’s respond to the business security policy and it’s supported by the vendor, i don’t see why wont use it. also keep in mind the performance impact of such encryption process.