LUKSbox v0.4.0
/ Documentation / Keyslots / TPM 2.0 keyslots

TPM 2.0 keyslots

Bind a vault to the local machine's TPM. Optional PIN, fused TPM + FIDO2, hybrid TPM + post-quantum.

A TPM 2.0 keyslot binds the vault to the specific TPM chip in the machine where you enroll it. The chip seals the wrap-KEK against its own endorsement seed; the seed never leaves the chip and is re-derived deterministically on every operation. The vault opens on that machine; it does not open on any other machine, even with the same passphrase or FIDO2 device.

Today TPM 2.0 keyslots are Linux only. Windows TBS support is tracked behind a tss-esapi 8.0 migration; macOS does not expose a TPM, use a Secure Enclave keyslot there instead (since v0.4.0). The same .lbx file remains portable everywhere, only the TPM slot is OS-specific.

When to use a TPM slot

You want Use
Unlock without a hardware key on the daily-use machine TPM (no PIN) + a passphrase backup
Hardware-bound + something the user knows TPM + PIN
Two-factor "must have YubiKey AND must be on this machine" Fused TPM + FIDO2 (single slot, both required)
Post-quantum on top of TPM binding Hybrid TPM + ML-KEM-768 / 1024
All of the above Hybrid TPM + FIDO2 + ML-KEM-768 / 1024

Always pair a TPM slot with a backup slot. A TPM keyslot becomes permanently unrecoverable if:

The CLI / GUI / wizard all surface a warning before creating a TPM-only vault.

Variants

Slot kind Inputs at unlock Notes
Tpm2Sealed TPM only Plain TPM seal; no PIN. Binds to chip + boot policy (no PCR sealing yet).
Tpm2SealedPin TPM + PIN TPM userAuth is the PIN. Wrong PINs count toward the chip's dictionary-attack lockout (typically about 32 attempts then a multi-hour cooldown), so even short PINs are practical.
Tpm2Fido2 TPM + FIDO2 hmac-secret (fused) Single slot, both factors required; HKDF mixes TPM-unsealed value with FIDO2 hmac-secret.
HybridPqKemTpm2 TPM + ML-KEM-768 decap Hybrid PQ on top of TPM binding.
HybridPqKem1024Tpm2 TPM + ML-KEM-1024 decap Same with category-5 KEM.
HybridPqKemTpm2Fido2 TPM + FIDO2 + ML-KEM-768 decap Three-factor + PQ.
HybridPqKem1024Tpm2Fido2 TPM + FIDO2 + ML-KEM-1024 decap Strongest TPM-bound option.

Linux: TPM access without root

Unprivileged users need read/write access to /dev/tpmrm0 (the in-kernel resource manager). Three things have to be true:

  1. The tss system group exists.
  2. /dev/tpm0 / /dev/tpmrm0 are owned root:tss with mode 0660 (this is what the udev rule does).
  3. Your user is a member of the tss group.

The .deb (since v0.2.0) Recommends tpm-udev which provides (1) + (2). The .rpm Recommends tpm2-tss which does the equivalent on Fedora / RHEL / openSUSE. Installing via apt / dnf gets both for you by default. You then only have to do (3) yourself, Debian / Fedora convention forbids silent privileged- group additions in package scripts:

sudo usermod -aG tss "$USER"
# Log out and back in (or `newgrp tss`) for the new group to take
# effect in your shell session.
id | tr , '\n' | grep tss   # confirm
ls -l /dev/tpmrm0           # expected: crw-rw---- 1 root tss ...

If you installed via the tarball, or passed --no-install-recommends / --setopt=install_weak_deps=False, neither the group nor the udev rule exists. Use the bundled installer:

./install.sh --tpm-setup     # creates the group + udev rule + adds you

Or do it by hand:

sudo groupadd --system tss
sudo usermod -aG tss "$USER"
sudo tee /etc/udev/rules.d/60-tpm.rules > /dev/null <<'EOF'
KERNEL=="tpm[0-9]*",   MODE="0660", GROUP="tss"
KERNEL=="tpmrm[0-9]*", MODE="0660", GROUP="tss"
EOF
sudo udevadm control --reload-rules
sudo udevadm trigger
# Log out + back in.

Verify:

tpm2_getrandom --hex 8     # if you have tpm2-tools installed
luksbox info my.lbx        # should not error on TPM slots

The full playbook with troubleshooting is in docs/TPM_LINUX_PERMISSIONS.md.

CLI, create a TPM-bound vault

# Plain TPM (no PIN)
luksbox create my.lbx --kind tpm2

# TPM + PIN
luksbox create my.lbx --kind tpm2-pin

# Fused TPM + FIDO2 (both required to unlock)
luksbox create my.lbx --kind tpm2-fido2

# Hybrid TPM + ML-KEM-768
luksbox create my.lbx --kind hybrid-pq-tpm2 \
    --pq-hybrid /media/usb/my.kyber

# Strongest: hybrid TPM + FIDO2 + ML-KEM-1024
luksbox create my.lbx --kind hybrid-pq-tpm2-fido21024 \
    --pq-hybrid /media/usb/my.kyber

After create, the wizard / GUI offer to add a backup keyslot. The CLI emits the same warning and asks you to confirm. To enroll a backup later:

luksbox enroll my.lbx --kind passphrase

TUI / GUI

The interactive wizard and the GUI create flow both expose every TPM variant through the same factor-then-variant picker. The GUI's recent-vaults list shows a TPM-binding badge so you know which vaults are machine-bound before you try to open them on a different host.

<- PreviousSecure Enclave keyslots (macOS)