ecryptfs-add-passphrase

ecryptfs-add-passphrase [OPTION...]

-h, --help
    Displays a help message and exits.

-v, --verbose
    Prints verbose debugging information, useful for troubleshooting.

-f FILENAME, --file=FILENAME
    Reads the passphrase from the first line of the specified FILENAME instead of prompting the user interactively.
Caution: Storing passphrases in plain files is generally not recommended for security reasons.

-s, --system-wide
    Adds the passphrase to the system-wide keyring instead of the user-specific session keyring. This makes the passphrase available to all users and processes on the system, which can be useful in specific server configurations, but also poses a higher security risk.

The ecryptfs-add-passphrase command is a utility designed to add a user-provided passphrase to the eCryptfs keyring within the Linux kernel. This passphrase is crucial for eCryptfs to decrypt and encrypt files on an eCryptfs mounted filesystem. When a user mounts an eCryptfs directory, the kernel needs to have the correct decryption key (derived from the passphrase) in its keyring to access the encrypted data. This command prompts the user interactively for a passphrase or can read it from a specified file. It's commonly used in conjunction with commands like ecryptfs-mount-private or the standard mount command when dealing with eCryptfs encrypted directories, ensuring that the necessary decryption key is available in the kernel's keyring before a mount operation can succeed.

The command adds the passphrase to the kernel's keyring; it does not directly perform any mount or decryption operations.
If an incorrect passphrase is added, it will still be stored in the keyring but will not allow decryption of the eCryptfs filesystem.
The passphrase must be present in the keyring before attempting to mount an eCryptfs filesystem that requires it.
Using the --file option can be a security risk as it involves storing the passphrase in plain text on disk.

eCryptfs relies on the Linux kernel's keyring service to manage cryptographic keys. When a passphrase is added, it's converted into a key and stored in a keyring associated with the current user's session or, if specified, the system-wide keyring. This allows the kernel to access the necessary decryption keys without constantly prompting the user.

While ecryptfs-add-passphrase can be run independently, it's often implicitly called or its function performed by higher-level scripts like ecryptfs-mount-private when setting up or accessing encrypted home directories, simplifying the user experience by handling key management automatically.

The ecryptfs-add-passphrase command is part of the eCryptfs utilities, which have been a core component of Linux's stacked cryptographic filesystem since its initial development in the mid-2000s, primarily driven by developers at IBM and later Canonical. It's designed to manage the critical passphrases that enable eCryptfs to function, evolving alongside the filesystem to provide robust data encryption capabilities for home directories and other sensitive data.

ecryptfs(7), ecryptfs-mount-private(1), ecryptfs-insert-wrapped-passphrase-into-keyring(1), mount(8)