CRYPTSETUP-PASSPHRASE-AGENT(1)

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

SYNOPSIS
cryptsetup-passphrase-agent

DESCRIPTION
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.

PASSPHRASE DERIVATION
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.

SYSTEMD INTEGRATION
The package provides two systemd units:

cryptsetup-passphrase-agent.path
    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

cryptsetup-passphrase-agent.service
    The service unit that runs the agent. It is activated automatically by the path unit and should not normally be enabled directly.

FILES

/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).

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

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

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