eCryptfs PAM-based Mount

Mike Halcrow <mhalcrow@us.ibm.com>


eCryptfs Mounting Overview

eCryptfs is set up in the Open Client to automatically mount on user
login. The default mount is an overlay mount on top of
~/Private/, and it uses a passphrase-based key.

eCryptfs requires that the user's mount passphrase be inserted into
the user session keyring in order to access the files under the
~/Private/ mount point. The mount passphrase is wrapped
(encrypted) with the user's login passphrase and is stored in the
~/.ecryptfs/wrapped-passphrase file. When the user logs in, the
eCryptfs PAM module intercepts the user's login passphrase, uses it to
decrypt the wrapped mount passphrase, and inserts the unwrapped mount
passphrase into the user session keyring.

Once the user has logged in, his ~/.bash_profile script is executed by
the Bash shell. A segment of code in ~/.bash_profile checks for the
existence of a ~/.ecryptfs/auto-mount file. If this file exists, then
code is executed to mount ~/Private/ via eCryptfs.

When the user changes his login credentials, the eCryptfs PAM module
unwraps the mount passphrase in ~/.ecryptfs/wrapped-passphrase with
the user's old passphrase and rewraps the mount passphrase into
~/.ecryptfs/wrapped-passphrase with the user's new passphrase.

For more information on eCryptfs, see the Linux Journal article on
eCryptfs at <http://www.linuxjournal.com/article/9400> or visit
the eCryptfs web site at <http://ecryptfs.sf.net>


Setup Overview

In order for these operations to complete successfully, the eCryptfs
PAM module needs to be inserted into the PAM stack in
/etc/pam.d/system-auth, an entry needs to be in /etc/fstab for the
user's ~/Private/ directory, the ~/.ecryptfs/auto-mount and
~/.ecryptfs/wrapped-passphrase files need to exist, and the mount code
needs to be in the user's ~/.bash_profile script.

The following shell script attempts to set all of this up
automatically:

http://downloads.sourceforge.net/ecryptfs/ecryptfs-setup-pam-wrapped.sh

Root executes this script in the following manner:

./ecryptfs-setup-pam-wrapped.sh user "mount_passphrase" "login_passphrase"

Where 'user' is the username, 'mount_passphrase' is the passphrase
used for encrypting files under the eCryptfs mount point, and
'login_passphrase' is the user's current login passphrase.


Setup Details

These instructions detail how to carry out the manual steps that the
ecryptfs-setup-pam-wrapped.sh tries to do for you automatically.

The following line needs to be added to /etc/pam.d/system-auth,
immediately below the line referencing the pam_unix.so module in the
auth context:

auth       required     pam_ecryptfs.so unwrap

The following line needs to be added to /etc/pam.d/system-auth,
immediately above the line referencing the pam_unix.so module in the
password context:

password   required     pam_ecryptfs.so

The following line needs to be added to /etc/fstab:

/home/user/Private /home/user/Private ecryptfs rw,ecryptfs_sig=deadbeefbaadf00d,ecryptfs_cipher=aes,ecryptfs_key_bytes=16,user,noauto, 0 0

Where 'user' is the username and 'deadbeefbaadf00d' is the mount
passphrase signature/identifier value. This signature is in /etc/mtab
after you perform a manual eCryptfs mount.

The following shell code needs to be appended to the user's
~/.bash_profile:

if test -e $HOME/.ecryptfs/auto-mount; then
  mount | grep "$HOME/Private type ecryptfs"
  if test $? != 0; then
    mount -i $HOME/Private
  fi
fi
ecryptfs-zombie-kill

The following file must exist:

~/.ecryptfs/auto-mount

The following file must contain the mount passphrase, encrypted with
the user's login passphrase:

~/.ecryptfs/wrapped-passphrase

The `ecryptfs-wrap-passphrase' command line utility can be used to
produce this file:

ecryptfs_wrap_passphrase ~/.ecryptfs/wrapped-passphrase "passphrase to wrap" "wrapping passphrase"

With these elements in place, the user should be able to log in and
have his eCryptfs mount point be created automatically.


Troubleshooting

      Problem: The ~/Private/ directory is not being mounted on login.
      Problem: The ~/Private/ directory is mounted on login, but
      the files under the ~/Private/ directory cannot be read.

            Solution: Your ~/.ecryptfs/wrapped-passphrase file may be
            incorrect. Run ecryptfs-wrap-passphrase to recreate it if
            that is the case. Otherwise, the PAM stack is not set up
            correctly. Otherwise, the code to mount your
            ~/Private directory is not in your ~/.bash_profile
            file.

      Problem: The ~/Private/ directory mounts on console login
      but not on GDM login.

            Solution: Make sure you have the most recent
            ecryptfs-utils package.

      Problem: Attempts to authenticate to the gnome-screensaver
      application result in a long pause and a failed attempt.

            Solution: Your PAM stack is not set up correctly. Make
            certain that /etc/pam.d/gnome-screensaver does not point
            to a file in the auth context that includes
            pam_ecryptfs.so.

      Problem: How to I backup my encrypted files?

            Solution: Unmount your ~/Private directory so that
            the lower filesystem files (in encrypted state) show up at
            that path location, and then copy the files in that
            directory to another storage device.

      Problem: How do I recover encrypted files from a backup?

            Solution: Place the encrypted files into a directory
            (e.g., /secret) and perform an eCryptfs mount (e.g., mount
            -t ecryptfs /secret /secret), using your mount passphrase
            when prompted. If you are unsure of which cipher to
            select, choose AES-128.

      Problem: Can I access the lower encrypted files of an active
      eCryptfs mount?

            Solution: This is not a good idea. See
            <http://ecryptfs.sourceforge.net/ecryptfs-faq.html#access_lower>