ecryptfs-wrap-passphrase

ecryptfs-wrap-passphrase [OPTION...]

Common usage for wrapping a passphrase:
ecryptfs-wrap-passphrase --wrap-passphrase-file=FILE [--keyring=KEYRING_DESCRIPTION]

Common usage for unwrapping a passphrase (less frequent directly by user):
ecryptfs-wrap-passphrase --unwrap-passphrase-file=FILE [--keyring=KEYRING_DESCRIPTION]

-w, --wrap-passphrase-file=FILE
    Specifies the path to the file where the encrypted passphrase will be written.

-u, --unwrap-passphrase-file=FILE
    Specifies the path to the file containing a wrapped passphrase that should be unwrapped. (Typically handled by mount helpers).

-k, --keyring=KEYRING_DESCRIPTION
    Specifies the kernel keyring to use for encrypting/decrypting the passphrase. Common values include 'login' (default) or a specific key description.

-d, --dry-run
    Performs a simulated run without actually modifying files or keyrings, printing what would happen.

-v, --verbose
    Increases the verbosity of output, providing more detailed information about the operation.

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

The ecryptfs-wrap-passphrase command is a utility within the eCryptfs filesystem suite designed to automate the process of mounting encrypted directories. It functions by taking an eCryptfs mount passphrase, encrypting it, and then storing the wrapped (encrypted) passphrase into a specified file on disk. This encryption is typically performed using a key stored in the Linux kernel's keyring service, most commonly the user's Login Keyring.

The primary use case for ecryptfs-wrap-passphrase is to enable seamless, automatic decryption and mounting of eCryptfs volumes without requiring the user to manually input the passphrase each time. This is particularly useful for scenarios like encrypted home directories in Linux distributions, where the system needs to access the encrypted data upon user login without prompting for an additional passphrase. By utilizing the keyring, the passphrase remains protected while allowing the eCryptfs mount helper to retrieve and unwrap it when needed, provided the relevant key is present in the keyring.

While ecryptfs-wrap-passphrase enhances convenience, it introduces security considerations. The wrapped passphrase file, though encrypted, still resides on disk. Its security depends entirely on the strength of the keyring used to encrypt it. If the keyring itself is compromised or if an attacker gains access to the system while the keyring is unlocked (e.g., after user login), they might be able to unwrap the passphrase. It is crucial to ensure strict file permissions (e.g., 0600) on the wrapped passphrase file to prevent unauthorized reading. This command does not provide full disk encryption; it only encrypts the eCryptfs specific mount point.

The command relies heavily on the Linux kernel's keyring service. When wrapping a passphrase, ecryptfs-wrap-passphrase retrieves a key from the specified keyring (or the default Login Keyring). This key is then used to encrypt the eCryptfs mount passphrase. Conversely, for unwrapping, the same key from the keyring is used to decrypt the stored passphrase. This mechanism ensures that the passphrase itself is never stored in plain text on disk and is protected by the security of the kernel keyring, which is typically managed by the system's authentication process (e.g., PAM).

For automatic mounting of eCryptfs directories, such as /home/$USER, the ecryptfs-wrap-passphrase utility is run once by the user to create the wrapped passphrase file (often ~/.ecryptfs/wrapped-passphrase). During subsequent logins or system boots, the mount.ecryptfs_private helper script (or similar eCryptfs mount helpers) reads this wrapped file. It then queries the kernel's Login Keyring for the necessary key to unwrap the passphrase. Once unwrapped, the passphrase is used by the mount helper to decrypt and mount the eCryptfs filesystem, allowing the user to seamlessly access their encrypted data without manual intervention.

The ecryptfs-wrap-passphrase utility is an integral part of the eCryptfs project, which originated primarily from IBM Linux Technology Center efforts. eCryptfs was designed as a robust stacked cryptographic filesystem for Linux, aiming for enterprise-level security and features. The concept of wrapping passphrases using kernel keyrings was a significant development to streamline the user experience, especially for scenarios like encrypted home directories, which became a popular feature in distributions like Ubuntu, where eCryptfs was used extensively for this purpose for many years.

ecryptfs(7), mount.ecryptfs_private(8), ecryptfs-utils(7), keyctl(1), keyrings(7), mount(8)