ecryptfs-generate-tpm-key

ecryptfs-generate-tpm-key [OPTIONS] <key_path>

-p <tpm_owner_password>
    Specifies the password for the TPM owner. This is often required if the TPM is initialized and owned.

-u <tpm_user_password>
    Specifies the password for the TPM user, if different from the owner password.

-r <pcr_values>
    A comma-separated list of Platform Configuration Registers (PCRs) to seal the key against (e.g., '0,2,4'). The key will only unseal if the current values of these specific PCRs match those recorded during sealing.

-a
    Seals the key against all available Platform Configuration Registers (PCRs). While providing robust integrity checks, this can make the key more sensitive to any changes in the boot environment.

-l
    Lists the current values of the Platform Configuration Registers (PCRs) on the system. This option is useful for determining which PCRs are relevant to your system's boot process when choosing which ones to seal against.

-v
    Enables verbose output, providing more detailed information about the key generation and sealing process, which can be helpful for debugging.

<key_path>
    The mandatory file path where the newly generated and TPM-sealed private key will be stored. This file contains the sealed blob that eCryptfs can later use to unseal the key.

The ecryptfs-generate-tpm-key command is a crucial utility within the ecryptfs-utils package, designed to enhance the security of eCryptfs encrypted data. It performs two primary functions: first, it generates a new eCryptfs encryption key; second, and most importantly, it uses the Trusted Platform Module (TPM) to seal this newly generated key.

Sealing a key with the TPM means that the key is encrypted in such a way that it can only be unsealed (decrypted) by that specific TPM chip. Furthermore, the key can be bound to specific Platform Configuration Registers (PCRs). These PCRs contain cryptographic hashes reflecting the system's boot state, including components like the BIOS, bootloader, and kernel. This binding ensures that the key is only accessible if the system's integrity and configuration match the state at the time of sealing, providing strong hardware-backed protection against tampering.

The generated sealed key is typically stored in a file, which eCryptfs can later use to automatically unseal and retrieve the encryption key from the TPM, enabling features like automated login for encrypted home directories or full-disk encryption without requiring manual passphrase entry on every boot, provided the system's integrity is maintained.

Requires a functional and initialized TPM (Trusted Platform Module) chip on the system, with owner credentials potentially already set.
Any changes to the system's boot environment (e.g., BIOS/UEFI updates, kernel upgrades, bootloader modifications) that alter the sealed PCR values will prevent the key from being automatically unsealed, potentially locking access to encrypted data and requiring manual intervention or re-sealing.
The ecryptfs-utils package must be installed for this command to be available and functional.

Before using ecryptfs-generate-tpm-key, it is essential to ensure that your system's Trusted Platform Module (TPM) is properly initialized and 'owned'. This process typically involves setting a TPM owner password. The command might require this owner password to perform sealing operations, often specified using the -p option.

Platform Configuration Registers (PCRs) are special registers within the TPM that store cryptographic hashes of various system components and configurations (e.g., BIOS firmware, bootloader, kernel, loaded modules) measured during the boot process. When a key is sealed to specific PCR values, the TPM is configured to release or unseal that key only if the current system's PCR values precisely match those recorded at the time of sealing, thereby ensuring the integrity of the system's boot environment.

The ecryptfs-generate-tpm-key command is an integral part of the ecryptfs-utils package, a collection of tools designed to manage eCryptfs encrypted filesystems. Its development arose from the growing need to integrate eCryptfs with hardware-backed security features provided by TPM chips.

This integration aimed to enhance the security posture of encrypted data, particularly in scenarios involving full-disk encryption where master keys are typically stored in the kernel keyring. Commands like ecryptfs-generate-tpm-key and its counterpart, ecryptfs-unwrap-passphrase, were crucial in enabling features such as automated login for encrypted home directories on Linux distributions like Ubuntu, where the master passphrase could be automatically unsealed by the TPM only if the system's boot integrity was verified, significantly improving usability while maintaining robust security.

ecryptfs(7), ecryptfs-unwrap-passphrase(1), ecryptfs-mount-private(1), tpm_sealdata(8), tpm_unsealdata(8)