Man page - cryptsetup-passphrase-agent(1)

Packages contains this manual

Package: cryptsetup-passphrase-agent
apt-get install cryptsetup-passphrase-agent

Manuals in package:

cryptsetup-passphrase-agent(1)

Documentations in package:

cryptsetup-passphrase-agent

Manual

CRYPTSETUP-PASSPHRASE-AGENT

NAME
SYNOPSIS
DESCRIPTION
PASSPHRASE DERIVATION
SYSTEMD INTEGRATION
FILES
EXIT STATUS
SEE ALSO

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.