luksbox enroll

Add a new keyslot to an existing vault.

luksbox enroll [OPTIONS] <PATH>

Adds a new keyslot. You authenticate with an existing keyslot first (to recover the MVK), then provide the new credential to wrap that MVK under a fresh KEK.

Two separate choices:

• How you unlock the vault: passphrase prompt by default, or --fido2 / --tpm2 / --tpm2-fido2 / --sep for those slot kinds.
• What you add: --kind <KIND>, passphrase by default.

So luksbox enroll my.lbx --fido2 unlocks with FIDO2 and adds a passphrase slot. To add a FIDO2 slot, use --kind fido2.

Examples

Add a backup passphrase to a FIDO2-only vault

luksbox enroll my.lbx --fido2 --kind passphrase
# Touch your YubiKey to unlock with slot 0
# Enter the new passphrase (twice) for the new slot

Add a second YubiKey for redundancy

luksbox enroll my.lbx --kind fido2 --fido2-device /dev/hidraw4
# Unlock with the existing passphrase slot
# Touch the new YubiKey twice (enroll + assert)

--fido2-device applies to every FIDO2 operation in the command, so unlock with a passphrase here; luksbox list-fido2-devices shows the device paths.

More than one FIDO2 key plugged in

On Linux and macOS, with more than one FIDO2 authenticator plugged in, LUKSbox no longer picks one for you (0.6.0+): the PIN would go to whichever device answers first. The command stops with "2 FIDO2 authenticators are present; select one explicitly". Pass --fido2-device <PATH> (paths from luksbox list-fido2-devices), or unplug the keys you are not using.

FIDO2 PIN on Windows

On Windows, LUKSbox does not ask for the FIDO2 PIN (0.6.1+): Windows asks for it in its own security-key prompt, and LUKSBOX_FIDO2_PIN is ignored there. Earlier versions also asked in the terminal, so you typed it twice.

Hybrid-PQ slots

enroll refuses hybrid-pq, hybrid-pq-fido2 and their 1024 variants. To add one of those to an existing vault, use the wizard (luksbox wizard, open the vault, Manage keyslots, "Add a passphrase + ML-KEM-768 keyslot" and so on) or the GUI's Add passphrase + ML-KEM / Add FIDO2 + ML-KEM keyslot buttons. Both write the new .kyber seed file for you.

The TPM and Secure Enclave hybrid kinds (hybrid-pq-tpm2, hybrid-pq-sep, ...) can be enrolled on an existing vault. enroll writes their new .kyber seed to the --pq-hybrid path. If the vault's only slots are already hybrid ones, name the existing seed with --unlock-pq-hybrid <PATH>:

luksbox enroll my.lbx --kind hybrid-pq-tpm2 --pq-hybrid /media/usb/tpm.kyber

# Vault made with `create --kind hybrid-pq`: unlock with its seed,
# write a new one for the new slot
luksbox enroll my.lbx --kind hybrid-pq-tpm2 \
    --unlock-pq-hybrid /media/usb/my.kyber --pq-hybrid /media/usb/tpm.kyber

Passphrase cost

The new slot's passphrase gets the strongest Argon2id cost already used by a passphrase slot of the vault (0.6.0+), or the interactive preset if there is none. Earlier versions always used interactive, so a slot added to a --kdf sensitive vault (1 GiB) got only 256 MiB, and the weakest slot is the one an attacker picks. --kdf <preset> picks the cost explicitly; it only applies to kinds with a passphrase factor (passphrase, sep-passphrase, hybrid-pq-sep-passphrase, ...).

Scripts: LUKSBOX_NEW_PASSPHRASE

LUKSBOX_PASSPHRASE is the unlock passphrase only. Since 0.6.0, enroll no longer reuses it as the new secret: it prints a note and prompts. Give the new passphrase in LUKSBOX_NEW_PASSPHRASE:

LUKSBOX_PASSPHRASE="$current" LUKSBOX_NEW_PASSPHRASE="$backup" \
    luksbox enroll my.lbx --kind passphrase

The PIN of a new tpm2-pin slot and the passphrase of a new .kyber seed file are read the same way.

Key flags

The new slot goes into the first empty index.

A vault holds up to 8 keyslots. Trying to enroll into a full vault fails with "no free keyslot".