eCryptfs encrypted home - explanation

8

7

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?

ardabro

Posted 2014-12-10T10:37:34.393

Reputation: 383

Answers

9

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:

Xen2050

Posted 2014-12-10T10:37:34.393

Reputation: 12 097

In /etc/crypttab I have only one row for cryptswap; nothing special in fstab also. My home is encrypted. Still have no idea how does the system know that my home is encrypted and sth special is necessary at logon. – ardabro – 2014-12-10T14:03:46.677

I think it's automatically done when the home is looked at @login. Did you read through the archlinux help, nothing in there anywhere was helpful? But please define "sth special", me nor "professor google" are familiar with it. Short for "something special"? Like what? – Xen2050 – 2014-12-12T01:37:40.510

sth special is to take the key and mount encrypted directory which is extra path in login process. Arch wiki was very helpful. In addition I made some investigation in ecryptfs source code. But I still don't know where is the key "if" instruction in login process and what exactly does it check. – ardabro – 2014-12-12T08:35:24.207

That sounds a little more like how linux would find & use any home folder, I think some info is stored in /etc/passwd (home & shell at least), does that look different for an encrypted home user? I'll add a bit of info about the kernel keyring to my answer too, ecryptfs stores keys there apparently – Xen2050 – 2014-12-12T09:03:03.443

@ardabro updated answer a while ago, looks ready for upvote/select, for more details the next step is reading source code. – Xen2050 – 2015-01-11T10:26:13.863

1Sorry, I missed the update. Great explanation. Many thanks! – ardabro – 2015-01-11T20:46:58.790

You're welcome, it was a learning experience for me too, lots of interesting info in the man pages – Xen2050 – 2015-01-12T10:29:56.283

Asked: 2014-12-10T10:37:34.393

Viewed: 5 107 times

Active: 2018-01-01T13:54:55.247