eCryptfs encrypted home - explanation

Question

I'm trying to understand how ecryptfs works internally and documentation on ecryptfs.org doesn't help. Maybe someone is able to explain how does it really works. Of course I'm aware of these hidden .Private / .ecryptfs directory structure. My questions are more detailed:

• How does the system know that my home is encrypted and decrypt it when I'm logging in?
• How does it search for key directories (those with encrypted data, mountpoint for it (sometimes it is home, sometimes /home/Private), directory with wrapped passphrase etc). These directories are typically put in /home/.ecryptfs/ and linked into home. Which location is the key? Are the ".ecryptfs" and ".Private" directory names reserved and hardcoded or configurable?
• About keyring: supposing I have multiple keys in my keyring - how does it match proper key with certain encrypted directory?

Answer 1

This describes the standard encrypted home setup. If you want to use different passphrases or folders, encryption algorithm, key size, etc... you can use mount.ecryptfs directly.

When you create a user with an encrypted home, or use ecryptfs-migrate-home on an existing user, it uses eCryptfs and sets up a directory /home/.ecryptfs/ containing folders with the new user's "real home", /home/.ecryptfs/user/ containing:

• your actual encrypted files in /home/.ecryptfs/user/.Private/, and the eCryptfs config directory /home/.ecryptfs/user/.ecryptfs/ containing:

  • auto-mount - if it exist, it tells ecryptfs-mount-private to run on login, mounting the private (home) folder. See man ecryptfs-mount-private

  • auto-umount - if it exist, it tells ecryptfs-umount-private to run on logout, unmounting the private (home) folder. See man ecryptfs-umount-private

  • Private.mnt - a configuration file read by mount.ecryptfs_private at login that defines where your encrypted directory should be mounted. If you've encrypted your home directory, this will be $HOME.
  • Private.sig - contains the signature of the mountpoint passphrase. It provides a safe, secure mechanism for eCryptfs to determine if you're using the correct key or not. (See Q about Private.sig and Private.mnt)
  • wrapped-passphrase - the actual (random) eCryptfs passphrase, encrypted ("wrapped") with your login passphrase

The regular home directory at /home/user/ only contains links to /home/.ecryptfs/user/.ecryptfs and /home/.ecryptfs/user/.Private and two more links to a help file & /usr/share/ecryptfs-utils/ecryptfs-mount-private.desktop (just runs ecryptfs-mount-private).

eCryptfs sets up PAM (see files in /etc/pam.d/) to automatically look for encrypted home folders in /home/.ecryptfs/ and mount & umount encrypted home folders on login / logout, depending on whether or not the auto-mount and auto-umount files exist. See the eCryptfs source code and the .deb package's preinst and postrm scripts (linked above) for more details, and this clip from man ecryptfs-setup-private:

[T]he pam_ecryptfs.so module to the PAM stack which will automatically use the login passphrase to unwrap the mount passphrase, add the passphrase to the user's kernel keyring, and automatically perform the mount. See pam_ecryptfs(8).

• This Ubuntu help page has directions on how to "automatically mount an ecryptfs encrypted filesystem at boot... using a /root/.ecryptfsrc file containing mount options, along with a passphrase file residing on a USB key."

Once unwrapped, the keys are stored in your user kernel keyring, you can take a look at it with keyctl show, since if it used the root keyring (sudo keyctl show) an administrator could find out the passphrase. You can use ecryptfs-unwrap-passphrase to see the actual ecryptfs passphrase. eCryptfs decrypts your files using the matching key signature (ecryptfs options ecryptfs_sig=(fekek_sig) and ecryptfs_fnek_sig) in the file Private.sig.

---

More Info

Ubuntu has good help files like Encrypted files in your Home and eCryptfs in the Ubuntu Server guide.

Arch Linux has some generally excellent help, see https://wiki.archlinux.org/index.php/System_Encryption_with_eCryptfs

And see the man pages for ecryptfs (online there or on your system) and all it's tools, especially ecryptfs-setup-private.

You can add a new user with an encrypted home using adduser --encrypt-home (For more information, refer to the -b option of ecryptfs-setup-private) and take a look at how the files are set up for yourself. And to really get your feet wet with all the details you probably never wanted to know see the source code:

• ecryptfs-setup-private from Dustin Kirlkand's mirror at github

• Ubuntu source code of ecryptfs-utils (in utopic release)

• From eCryptfs in Launchpad :

  • The ecryptfs-utils userspace code is stored in Launchpad/Bazaar, and can be obtained with:
    https://code.launchpad.net/~ecryptfs/ecryptfs/trunk

  • The ecryptfs kernel code is stored in Git/Kernel.org, and can be obtained with:
    https://git.kernel.org/?p=linux/kernel/git/tyhicks/ecryptfs.git;a=summary