fido2-luks-enroll.1

.\"                                      Hey, EMACS: -*- nroff -*-
.\" (C) Copyright 2015-2023 Markus Frosch <lazyfrosch@debian.org>, Nyancient <foxolotl@protonmail.com>
.\"
.\"     Cornelius Kölbel <cornelius@privacyidea>
.\"                      Add the prerequisites
.TH FIDO2-LUKS-ENROLL 1 "2023-04-10"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
fido2-luks-enroll - enroll your FIDO2 security token for use with LUKS
.SH SYNOPSIS
.B fido2-luks-enroll
.RI "[ \-d DEVICE ] [ \-c ]"
.SH DESCRIPTION
With this tool you can use a FIDO2 token with hmac-secret support to add a LUKS / cryptsetup key slot.
Currently, only a single FIDO2 token per encrypted device is supported. This program will refuse to
enroll a new token without first removing the old one, if one is already enrolled.

Your chosen PIN plus your FIDO2 token can generate a response that is
added as a key to the cryptsetup disk.

On the next boot you can insert your FIDO2 token into a USB slot and enter your
PIN to unlock the disk. Alternatively you can enter any other passphrase
that is valid for that disk.

Ths on-disk format of this program is 100% compatible with the FIDO2 functionality of systemd-cryptenroll,
ensuring a painless transition should Debian start to use it to unlock encrypted root disks.

.SH OPTIONS
The following options change the behavior of the tool.
.TP
.B \-h
Show summary of options.
.TP
.B \-c
Clear all FIDO2 LUKS slots before enrolling token.
.TP
.B \-n
Allow PIN-less authentication.
.TP
.B \-d
The disk device to work with (default: /dev/nvme0n1p3)

.SH BOOT SETUP
In order to decrypt your disk using your FIDO2 token at boot time, after enrolling your token
you also need to:
.IP \[bu]
Append
.B keyscript=/usr/share/fido2-luks/fido2-luks-keyscript
to the
.B OPTIONS
section of the
.B /etc/crypttab
entry corresponding to your encrypted root partition.
.IP \[bu]
Run
.B update-initramfs -u
to make the aforementioned changes take effect during boot.

.SH SEE ALSO
.BR cryptsetup (1),
.BR crypttab (5),
.BR fido2-luks-open (1),
.BR systemd-cryptenroll (1),
.BR systemd-cryptsetup (1),
.BR update-initramfs (1).