A Closer Look at the Changes in PC-BSD/TrueOS 9.2. Part 2

Directory encryption using PEFS

Last month we took a look at how PC-BSD is implementing ZFS boot-environments, which can be a life-saver for both servers and desktops. This month we will be looking at how PC-BSD uses the PEFS kernel level file system module to automatically encrypt your home directory and its contents, and how you can manually run PEFS for other sensitive data.

Starting in PC-BSD 9.2, the default encryption provider has been switched to PEFS, which has also been merged into the base operating system as the /boot/kernel/pefs.ko kernel module, the /usr/sbin/pefs command, and various libraries. The PEFS system is a kernel level stacked cryptographic file-system authored by Gleb Kurtsou. Because it is provided as a kernel module, it does not require any user-level daemons to function, and can run on top of existing file-systems such as ZFS in the case of PC-BSD or TrueOS. It includes other nice features such as random cipher tweak values on a per file basis, support for AES / Camellia in XTS mode, and more. Since it can sit on top of a ZFS file-system, this ensures that all the data stored by ZFS, including in snapshots, is encrypted and will stay encrypted when performing functionality such as a zfs send to a remote backup server. This is a key feature of performing snapshots/replication with PC-BSD’s new “Life-Preserver” utility. It enables you to safely transmit data to a remote machine (over SSH), without having to explicitly trust that the remote system will take the necessary steps to re-encrypt your ZFS data, as in the case of GELI encryption.

Another key feature of PEFS is its inclusion of a PAM module for login decryption of a user’s home-directory. So what does this look like? During the first time setup of PCBSD, or when adding additional users, you will now be presented with a new option to “Encrypt user files”.

Figure 1

By enabling the “Encrypt user files” option, a new PEFS mount-point will be created on top of your home-directory, in this case /usr/home/kmoore. The encryption key for this directory will be tied to your specified user password, so a password of good length and randomness is encouraged. When your user is not logged in, all the files in the home directory will appear encrypted to root and to any other users who happen to log into the machine.

Figure 2

After logging into the system as your user, your password will be automatically added to the PEFS key chain database and your encrypted directory will appear normally again.

Figure 3

So how does this work behind the scenes? Let us take a look at the command-line usage for PEFS and its implementation on PC-BSD. As an example, we will walk through the creation of a new /secret directory on the system, where our user perhaps wants to keep more encrypted data with a different passphrase from his login. To get started, we will first create the new directory and initialize it with the pefs command.

Figure 4

Since this is a first-time initialization, and the PEFS directory is not yet mounted, we are going to use the -f flag to skip the file-system checks. The -Z flag is also used so we can create a new key-chain with only a single “parent” passphrase. This key-chain passphrase can then be verified at decryption time to ensure it was not mistyped.


In addition to a single password, PEFS also supports creating parent / child keys in the keychain; giving the parent keys the ability to unlock the child keys, but not visa-versa. This allows you a method of creating security levels in your encrypted data. For more information on this, take a look at the following wiki page: https://wiki.freebsd.org/PEFS.

With the initial chain created, if you take a look at the / secret directory, you will see that the ‘.pefs.db’ key chain database file has been created, which is the only file that will need to exist underneath the PEFS mounted directory.

Figure 5

Now all that is left to do is to mount the PEFS file-system, and add the passphrase we just created. We can then look and still see the .pefs.db file, and see that the “pefs” file-system has been mounted successfully. This may be a good time to copy the ‘.pefs.db’ file to a secure location, in case of accidental deletion. Note the usage of the -c flag on pefs addkey. This will enable a test ensuring that the passphrase entered is indeed the correct one from the key database.

Figure 6

With PEFS now mounted and ready, it is always a good practice to test your new setup before you begin using it with critical data. Next we will create a test file, verify it, remove our active encryption key, verify the encryption, and decrypt the directory again (Figure 7).

Figure 7

Lastly, we can setup the /secret directory to automatically have PEFS mounted at reboot. To enable this, you can add the directory you wish to re-mount with PEFS to the /var/db/pefs/auto_mounts file. (You can safely create this file if it does not exist).

Figure 8

This method is preferred over a traditional entry in /etc/fstab, particularly, to ensure that your PEFS directories get mounted last and on top of other late-mounted file-systems, such as ZFS datasets. With this in place, you are now ready to begin using your encrypted directory normally. As a fail-safe, the directory is automatically mounted read-only, until you unlock it again via the pefs addkey -c command.

We have taken a quick look at PEFS: How it’s used on PC-BSD and how you can manually configure it via the command-line. For more information please read the excellent wiki article referenced below, or check out the source via GitHub. Traditional FreeBSD users may also find PEFS in the ports collection under sysutils/pefs-kmod.

About the Author

Kris Moore is the founder and lead developer of the PC-BSD project. He is also the co-host of the weekly BSD Now video podcast with Allan Jude of ScaleEngine. When not at home programming, he travels around the world giving talks and tutorials on various BSD related topics at Linux and BSD conferences alike. He currently lives in Tennesee (USA) with his wife and five children and enjoys video gaming in his (very limited) spare time.

This article was re-published with the permission of BSD Magazine.  To Learn More about iXsystem’s commitment to open source check us out here:   https://www.ixsystems.com/about-ix/


ESG Labs: TrueNAS Technical Report
Download Enterprise Storage Guide Button
iXsystems values privacy for all visitors. Learn more about how we use cookies and how you can control them by reading our Privacy Policy.