ecryptfs-insert-wrapped-passphrase-into-keyring

ecryptfs-insert-wrapped-passphrase-into-keyring [ -w WRAPPED_PASSPHRASE_FILE ] [ -S ] [ -m MASTER_PASSPHRASE ] [ -v ]

-w WRAPPED_PASSPHRASE_FILE
    Specifies the path to the file containing the eCryptfs wrapped passphrase that needs to be unwrapped and inserted into the keyring.

-S
    Instructs the command to read the unwrapped (plaintext) passphrase directly from standard input (stdin) instead of attempting to unwrap a file. This is useful for passing the passphrase securely from another process.

-m MASTER_PASSPHRASE
    Provides the master passphrase used to unwrap and decrypt the WRAPPED_PASSPHRASE_FILE. If not provided, the user may be prompted interactively for the master passphrase.

-v
    Enables verbose output, providing more detailed information about the command's execution, which can be helpful for debugging.

The ecryptfs-insert-wrapped-passphrase-into-keyring command is a utility within the eCryptfs filesystem suite. Its primary function is to decrypt a previously 'wrapped' (encrypted) passphrase and insert the resulting plaintext passphrase into the kernel keyring. This process is crucial for automating the mounting of eCryptfs encrypted directories, especially user home directories, without requiring manual passphrase entry at mount time.

Typically, the command is used to take a wrapped passphrase from a file (e.g., `~/.ecryptfs/wrapped-passphrase`) and, using a master passphrase (often the user's login password), unwrap it. Once unwrapped, the passphrase becomes available in the kernel keyring, allowing eCryptfs mount helpers (like mount.ecryptfs_private) to automatically retrieve the necessary key for decryption and mounting. This enables seamless access to encrypted data during system boot or user login.

Using the -m option on the command line can expose the master passphrase in shell history or process listings, posing a security risk. It's generally safer to allow the command to prompt for the master passphrase interactively or pass it via standard input using the -S option if automating.

The inserted passphrase remains in the kernel keyring until explicitly removed, the system reboots, or the keyring expires. Proper management of keys in the keyring is essential for security and ensuring data accessibility.

This command is frequently utilized in system startup scripts, PAM configurations, or /etc/fstab entries (often indirectly via mount.ecryptfs_private) to automatically decrypt and mount eCryptfs volumes. By inserting the passphrase into the kernel keyring before the mount operation, eCryptfs can access the necessary cryptographic keys without user interaction.

The command interacts with the Linux kernel's keyring service. The unwrapped passphrase is added as a key, typically associated with the user's session or the system, which eCryptfs then looks up by its key description to unlock the encrypted data. The key remains in the keyring until removed or the system is rebooted.

The ecryptfs-insert-wrapped-passphrase-into-keyring command is part of the eCryptfs project, which was initially developed by Canonical Ltd. and IBM. eCryptfs emerged as a stacked cryptographic filesystem for Linux, designed to provide per-file encryption, primarily for user home directories. This command specifically addressed the need for automated mounting of these encrypted directories, especially during system boot or user login, where prompting for a passphrase would be inconvenient or impossible. Its development was driven by the goal of making encrypted home directories practical and easy to manage in distributions like Ubuntu, where it became a standard feature.

ecryptfs(7), ecryptfs-unwrap-passphrase(1), ecryptfs-wrap-passphrase(1), mount.ecryptfs_private(8), keyctl(1)