pam_ecryptfs

This module is configured within PAM service files, not executed directly from the command line.
The typical usage in a PAM configuration file looks like this:
service type control pam_ecryptfs.so [options]

For example:
session optional pam_ecryptfs.so
auth optional pam_ecryptfs.so passwd_auth

ecryptfs_private=
    Specifies the absolute path to the user's eCryptfs private directory. Defaults to ~/.Private if not specified.

passwd_auth
    Instructs the module to use the user's login passphrase to derive the key for unlocking the eCryptfs private directory. This is a common and often required option for seamless integration.

unlink_on_unmount
    When specified, the mount point directory will be unlinked (removed) after the eCryptfs filesystem is unmounted. Use with caution as this deletes the empty directory.

no_unmount_on_logout
    Prevents the module from automatically unmounting the eCryptfs directory when the user logs out. The directory will remain mounted.

auto_unmount
    Ensures that the eCryptfs directory is automatically unmounted when the user's session ends. This is often the default and desired behavior.

verbose
    Enables more verbose logging output from the module, useful for debugging and understanding its operations.

syslog
    Directs the module's log messages to syslog, making them visible in system logs (e.g., /var/log/auth.log).

pam_ecryptfs is a Pluggable Authentication Module (PAM) designed to seamlessly integrate eCryptfs encrypted directories, most commonly user home directories, with the login and logout processes. When configured in PAM service files (e.g., /etc/pam.d/common-auth or /etc/pam.d/common-session), it facilitates the automatic mounting of a user's eCryptfs private directory upon successful authentication and its subsequent unmounting upon session termination.

This module leverages the user's login passphrase, or a derived key, to unlock the eCryptfs master passphrase, ensuring data privacy and security. It typically operates as a session module, handling the mount and unmount operations, but can also be used as an auth module for specific authentication-related tasks. Its primary role is to simplify the management of encrypted home directories, making them transparent to the end-user while maintaining robust encryption.

Performance Overhead: Encryption and decryption add computational overhead, which can slightly impact filesystem performance.
Key Management: If the login passphrase used to derive the eCryptfs key is changed or forgotten, careful key management (e.g., passphrase re-wrapping) is necessary to avoid data loss.
Data Recovery: Recovery of data from a corrupted or inaccessible eCryptfs directory can be challenging without the correct master passphrase or mount options.
Pre-setup Required: pam_ecryptfs assumes that eCryptfs has been properly set up for the user's directory beforehand (e.g., using ecryptfs-migrate-home). It does not set up the encryption itself.
Troubleshooting Complexity: Issues related to PAM and eCryptfs can be complex to diagnose, often requiring examination of system logs and PAM configuration files.

pam_ecryptfs primarily functions as a session module, responsible for mounting the eCryptfs private directory at session start and unmounting it at session end. However, it can also be configured as an auth module in specific scenarios, particularly when the authentication process itself needs to interact with the eCryptfs keyring.

This module is configured by adding lines to service-specific PAM configuration files located in /etc/pam.d/ (e.g., login, sshd, common-session, common-auth). Its effective behavior depends on the chosen PAM control flags (e.g., requisite, required, sufficient, optional) and its placement relative to other modules in the PAM stack.

pam_ecryptfs was developed as an integral part of the eCryptfs project, aiming to provide seamless encrypted home directories for Linux users. It gained significant adoption, particularly within Ubuntu, where it was offered as a default or recommended option for encrypting user home directories during installation for several releases. Its development has been closely tied to the evolution of the eCryptfs filesystem itself, focusing on simplifying the user experience of encrypted data.

ecryptfs(7), ecryptfs-migrate-home(8), pam.conf(5), pam(8), mount(8), umount(8)