Antarctica Starts Here.

A couple of weeks back I wrote about migrating Windbringer to a new laptop, but something I didn't go into a lot of detail about was migrating the encrypted volumes over. There were a few reasons for this, chief among them that I didn't want to put more information than I already had in that post for the sake of organization. Web search is a clusterfuck these days and I wanted to make potentially helpful information as easy to track down as possible. Anyway.

Surprising nobody who's known me for longer than an hour, the hard drives in all of my systems are encrypted at the disk level. I also partition off my work and research into other encrypted volumes inside of them to add an additional layer of protection. The chief advantage of this is that I can lock and unlock those volumes as needed. Without going into too much detail and going off in a tangent, eCryptFS is the older file system level encryption system in Linux which hasn't been actively supported for quite a while. Last year I migrated to the newer and actively supported ¹ mechanism called fscrypt, though I didn't write it up because the migration process amounted to "make a new encrypted directory structure, rsync the old one to the new one, test, lock the old one and erase it." There just wasn't anything I could say that would help anyone.

However now there is, vis a vis, how to mount and unlock an fscrypt directory structure on an external device (read: Windbringer's old hard drive) to copy the data over. The way fscrypt is implemented it's not as straight forward as plugging the drive in, typing in a password, and running rsync. But neither is it terribly difficult once you know a few things about how fscrypt works.

Assuming for the moment that you've set up fscrypt once or twice you may or may not be aware of a directory structure that fscrypt creates:

(pelican) {13:50:34 @ Sun May 05}
[drwho @ windbringer ~] () $ ls -alF /.fscrypt/
drwxr-xr-x root root 4.0 KB Mon Apr  8 21:43:56 2024  ./
drwxr-xr-x root root 4.0 KB Mon Apr  8 21:43:56 2024  ../
drwxrwxrwt root root 4.0 KB Mon Apr  8 21:46:32 2024  policies/
drwxrwxrwt root root 4.0 KB Thu Apr 11 12:29:37 2024  protectors/

If I'm reading the documentation correctly, the contents of /.fscrypt/policies/ are small binary files that contain the configuration used by fscrypt - the API version, the algorithms used to encrypt the filenames and file contents, flags for various settings, and instructions for finding the actual keying material. The keys used for encryption are kept in the /.fscrypt/protectors/ subdirectory and are the important thing. The executive summary ² is that you have to copy the keying material in /.fscrypt/protectors/ from the old drive onto the new one, then unlock the old one, and then copy its now-accessible contents over.

If you take a look in that directory you'll see at least one file that has sixteen hexadecimal digits as its filename. The contents of that file are the encryption key that fscrypt uses to encrypt and decrypt files. For every fscrypt-protected directory you set up, there should be one such file. The thing to keep in mind is that it's a file like any other, which can be copied, deleted (by accident), and backed up. ³ It looks something like this:

(pelican) {15:04:37 @ Sun May 05}
[drwho @ windbringer ~] () $ ls -alF /.fscrypt/protectors/
drwxrwxrwt root  root  4.0 KB Thu Apr 11 12:29:37 2024  ./
drwxr-xr-x root  root  4.0 KB Mon Apr  8 21:43:56 2024  ../
.rw------- drwho drwho 147 B  Thu Apr 11 12:29:37 2024  444359b3745a03fe

That is pretty much what it looks like on Windbringer right now (I changed the filename but that's it). When I set up Windbringer's new shell I also created a brand-new fscrypt directory ~/Research/ once I had the OS set up, and that's the keying material to encrypt its contents. What I then did was connect Windbringer's old SSD to an M.2 NVME to USB 3 adapter (affiliate link), plug the adapter into the new laptop (whereupon it showed up in the file manager as a LUKS volume), type in the passphrase to unlock it, and navigated to the /.fscrypt directory:

(pelican) {15:06:22 @ Sun May 05}
[drwho @ windbringer ~] () $ ls -alF /mnt/.fscrypt/protectors/
drwxrwxrwt root  root  4.0 KB Thu Apr 11 12:29:37 2024  ./
drwxr-xr-x root  root  4.0 KB Mon Apr  8 21:43:56 2024  ../
.rw------- drwho drwho 147 B  Thu Apr  1 12:29:37 2024  c8cd1123252c3a7d

That's the keying material that needs to be copied over thusly:

(pelican) {15:06:59 @ Sun May 05}
[drwho @ windbringer ~] () $ cp /mnt/.fscrypt/protectors/c8cd1123252c3a7d /.fscrypt/protectors

(pelican) {15:07:05 @ Sun May 05}
[drwho @ windbringer ~] () $ ls -alF /.fscrypt/protectors/
drwxrwxrwt root  root  4.0 KB Thu Apr 11 12:29:37 2024  ./
drwxr-xr-x root  root  4.0 KB Mon Apr  8 21:43:56 2024  ../
.rw------- drwho drwho 147 B  Thu Apr 11 12:29:37 2024  444359b3745a03fe
.rw------- drwho drwho 147 B  Thu Apr  1 12:29:37 2024  c8cd1123252c3a7d

Now the fun part, actually migrating everything:

# Unlock the old fscrypt directory.
# This implicitly tries all of the keys in /.fscrypt/protectors.  The right
# one will unlock the directory and return a success, the rest will fail,
# return a failure, and try the next one in the directory.  If the right key
# isn't there it'll try all of the ones it finds and eventually fail.
(pelican) {15:08:07 @ Sun May 05}
[drwho @ windbringer ~] () $ fscrypt unlock /mnt/home/drwho/Research
Enter custom passphrase for protector "Research":
"Research" is now unlocked and ready for use.

# rsync the old directory into the new one.
(pelican) {15:08:20 @ Sun May 05}
[drwho @ windbringer ~] () $ rsync -av /mnt/home/drwho/Research/ /home/drwho/Research/

# Go get some coffee, this is going to take a while.

# We're done.  Relock the old directory to clean up.
(pelican) {19:42:52 @ Sun May 05}
[drwho @ windbringer ~] () $ fscrypt lock /mnt/home/drwho/Research

That was all it took. Tricky, even daunting until you dig into it a little bit.