An Encrypted File-backed File System on FreeBSD

The following is a compilation of information, largely based on the FreeBSD Handbook, Section 18.13 and Section 18.16. This post describes how a file-backed, encrypted file system can be built and used on FreeBSD.

Prerequisites

In order to follow the steps below, the following prerequisites must be met:

• md(4) in the Kernel
• gbde(4) in the Kernel, i.e. kldload geom_bde
• The /etc/gbde directory must exist

First time installation

After those requirements are fullfilled, it's time to take the first step which is creating a file that will serve as the basis for the file system. There is no support for growing images so you need to allocate all space now. This command creates a 128 MByte file filled with zeros:

$ dd if=/dev/zero of=encrypted.img bs=4k count=32768

Next, create a memory disk which is based on the the image file created above. As root, do:

# mdconfig -a -t vnode -f encrypted.img -u <unit>

In the example above, the parametr -u <unit> is optional and specifies a number which determines the number of the md(4) device. For example, if you use 4, then md4 will be created.

Now create a partition table which, e.g. one with an automatic layout:

# bsdlabel -w md<unit> auto

At this point, you have the equivalent of a hard disk w/ one or more FreeBSD partitions on it. Note that there is no filesystem, yet. In order to create an encrypted file system, an initialization step must be performed:

# gbde init /dev/md0c -i -L /etc/gbde/encrypted.lock

The initialization step opens an editor where the user is asked to enter a few parameters. Most notably it is probably sensible to change the sector_size to 4096, i.e. the page size on i386. When the editor is closed, the gbde(8) program asks for a password. This password will be used to encrypt the disk, so do not lose it. Note that the /dev/md0c parameter corresponds to the md(4) device which was previously created. The file of the lock name can be arbitrarily named as long as its ending is .lock. Also note that the lock file must be backed up as the file system cannot be easily accessed without the file.

Now the encrypted device can be attached by running

# gbde attach /dev/md0c -l /etc/gbde/encrypted.lock

You'll be prompted for the password set in the previous step. If the password is accepted, you'll end up with a new disk device at /dev/md0c.bde on which you can operate the same way as on a regular disk. That means you'll need to create a file system, first.

# newfs -U -O2 /dev/md0c.bde

Make sure you use the .bde device node and not the raw memory disk as you'd end up without encryption. When you're done, it's time to mount the file system:

# mkdir /encrypted
# mount /dev/md0c.bde /encrypted

Unmounting the encrypted file system

Unmounting the file system is easy, but the gbde(4) device needs to be detached before the md(4) device can be destroyed.

# umount /encrypted
# gbde detach /dev/md0c
# mdconfig -d -u 0

Re-mounting an encrypted file system

Re-mounting is simple, but note that the FreeBSD handbook suggests that the file system be checked for errors before mounting:

# mdconfig -a -t vnode -f encrypted.img
md0
# gbde attach /dev/md0c -l /etc/gbde/encrypted.lock
# fsck -p -t ffs /dev/md0c.bde
# mount /dev/md0c.bde encrypted