ecryptfs-unwrap-passphrase

ecryptfs-unwrap-passphrase [wrapped_passphrase_file]

wrapped_passphrase_file
    Optional.
Specifies the path to the file containing the encrypted (wrapped) passphrase. If omitted, the command typically defaults to reading the wrapped passphrase from ~/.ecryptfs/wrapped-passphrase.

The ecryptfs-unwrap-passphrase command is a crucial utility within the eCryptfs ecosystem, primarily used for decrypting passphrases that have been "wrapped" (encrypted) by eCryptfs.

When a user's home directory (or other data) is encrypted with eCryptfs, the actual mount passphrase is often not stored in plaintext for security reasons. Instead, it's encrypted using another key, typically derived from the user's login passphrase, and stored in a file like ~/.ecryptfs/wrapped-passphrase.

This command's purpose is to retrieve the original, plaintext passphrase from this wrapped file. It achieves this by prompting the user for the necessary decryption key (usually the login passphrase) and then performing the decryption. The decrypted passphrase is then printed to standard output.

While it can be invoked directly, ecryptfs-unwrap-passphrase is more commonly called internally by other eCryptfs scripts and tools, such as ecryptfs-mount-private or ecryptfs-recover-private, which need to access the plaintext passphrase to mount the encrypted directories. It's an essential component for automated and secure handling of eCryptfs encrypted data.

Key Requirement: The command requires the correct decryption key (typically the user's login passphrase) to successfully unwrap the passphrase. If the wrong key is provided, decryption will fail.

Security Risk: Since the command outputs the plaintext passphrase to standard output, care must be taken to prevent it from being logged or exposed. It should not be used in environments where its output could be compromised.

User Permissions: This command should generally be run by the user whose passphrase is being unwrapped, as it operates on user-specific encrypted data and interacts with the user's kernel keyring.

While ecryptfs-unwrap-passphrase can be executed directly, its primary role is as an internal helper for other eCryptfs commands and scripts. For instance, ecryptfs-mount-private often invokes it to retrieve the passphrase needed to mount a user's encrypted private directory after a login.

Upon successful decryption, the command prints the plaintext passphrase to stdout. It is typically piped to another command or variable that consumes it immediately, rather than being displayed on the terminal for general user interaction.

The ecryptfs-unwrap-passphrase command is an integral part of the eCryptfs utilities (ecryptfs-utils package), which were primarily developed by Dustin Kirkland at Canonical. eCryptfs itself was introduced as a robust solution for filesystem-level encryption, particularly for home directories, within Ubuntu and other Linux distributions.

This specific command has been a stable component since the early days of eCryptfs's widespread adoption, enabling the secure and automated handling of user passphrases required for mounting encrypted data without exposing them directly to the user or to persistent storage in plaintext.

ecryptfs-mount-private(1), ecryptfs-recover-private(1), ecryptfsd(8), mount.ecryptfs(8), ecryptfs(7)