Man page - cryptsetup-passphrase-agent(1)

Packages contas this manual

Manual

CRYPTSETUP-PASSPHRASE-AGENT(1) User Commands CRYPTSETUP-PASSPHRASE-AGENT(1)

cryptsetup-passphrase-agent - non-interactive systemd password agent for encrypted disks

cryptsetup-passphrase-agent

cryptsetup-passphrase-agent is a systemd password agent that automatically responds to cryptsetup passphrase requests without user interaction. It watches /run/systemd/ask-password/ for password requests and responds only to cryptsetup requests, ignoring all others.

This is useful for headless servers or embedded systems with encrypted disks that need to be unlocked automatically during boot.

Passphrases are derived uniquely for each block device using:

1. Device Innate ID
The unique hardware identifier for the block device is retrieved using block-device-id(7). For eMMC and SD cards, this is the CID (Card Identification register) read from /sys/block/*/device/cid. For NVMe drives, the serial number is used.
2. HMAC-SHA256 via Firmware OTP Key
The device ID is hashed using HMAC-SHA256 with an OTP (One-Time Programmable) key stored in the Raspberry Pi firmware via librpifwcrypto. The raw key material never leaves the firmware, ensuring the passphrase cannot be derived without physical access to the specific device.

This hardware-bound cryptographic derivation ensures each device receives a unique passphrase tied to both the storage media and the host hardware.

The package provides two systemd units:

A path unit that watches /run/systemd/ask-password/ and activates the service when password requests appear. Enable with:
systemctl enable cryptsetup-passphrase-agent.path
The service unit that runs the agent. It is activated automatically by the path unit and should not normally be enabled directly.

/run/systemd/ask-password/
Directory watched for systemd password requests.
/sys/block/*/device/cid
MMC Card Identification register (source of device innate ID for eMMC/SD).

The agent runs continuously until terminated. Exit status is zero on clean shutdown, non-zero on error.

systemd-ask-password(1), cryptsetup(8), systemd.path(5)

The systemd Password Agents protocol: https://systemd.io/PASSWORD_AGENTS/

January 2026 cryptsetup-passphrase-agent