.\" Copyright (c) 2018-2021 Yubico AB. All rights reserved.
.\" Use of this source code is governed by a BSD-style
.\" license that can be found in the LICENSE file.
.\"
.Dd $Mdocdate: September 13 2019 $
.Dt FIDO2-TOKEN 1
.Os
.Sh NAME
.Nm fido2-token
.Nd find and manage a FIDO 2 authenticator
.Sh SYNOPSIS
.Nm
.Fl C
.Op Fl d
.Ar device
.Nm
.Fl D
.Op Fl d
.Fl i
.Ar cred_id
.Ar device
.Nm
.Fl D
.Fl b
.Op Fl d
.Fl k Ar key_path
.Ar device
.Nm
.Fl D
.Fl b
.Op Fl d
.Fl n Ar rp_id
.Op Fl i Ar cred_id
.Ar device
.Nm
.Fl D
.Fl e
.Op Fl d
.Fl i
.Ar template_id
.Ar device
.Nm
.Fl D
.Fl u
.Op Fl d
.Ar device
.Nm
.Fl G
.Fl b
.Op Fl d
.Fl k Ar key_path
.Ar blob_path
.Ar device
.Nm
.Fl G
.Fl b
.Op Fl d
.Fl n Ar rp_id
.Op Fl i Ar cred_id
.Ar blob_path
.Ar device
.Nm
.Fl I
.Op Fl cd
.Op Fl k Ar rp_id Fl i Ar cred_id
.Ar device
.Nm
.Fl L
.Op Fl bder
.Op Fl k Ar rp_id
.Op device
.Nm
.Fl R
.Op Fl d
.Ar device
.Nm
.Fl S
.Op Fl adefu
.Ar device
.Nm
.Fl S
.Op Fl d
.Fl i Ar template_id
.Fl n Ar template_name
.Nm
.Fl S
.Op Fl d
.Fl l Ar pin_length
.Ar device
.Nm
.Fl S
.Fl b
.Op Fl d
.Fl k Ar key_path
.Ar blob_path
.Ar device
.Nm
.Fl S
.Fl b
.Op Fl d
.Fl n Ar rp_id
.Op Fl i Ar cred_id
.Ar blob_path
.Ar device
.Nm
.Fl S
.Fl c
.Op Fl d
.Fl i Ar cred_id
.Fl k Ar user_id
.Fl n Ar name
.Fl p Ar display_name
.Ar device
.Nm
.Fl V
.Sh DESCRIPTION
.Nm
manages a FIDO 2 authenticator.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl C Ar device
Changes the PIN of
.Ar device .
The user will be prompted for the current and new PINs.
.It Fl D Fl i Ar id Ar device
Deletes the resident credential specified by
.Ar id
from
.Ar device ,
where
.Ar id
is the credential's base64-encoded id.
The user will be prompted for the PIN.
.It Fl D Fl b Fl k Ar key_path Ar device
Deletes a
.Dq largeBlob
encrypted with
.Ar key_path
from
.Ar device ,
where
.Ar key_path
must hold the blob's base64-encoded encryption key.
A PIN or equivalent user-verification gesture is required.
.It Fl D Fl b Fl n Ar rp_id Oo Fl i Ar cred_id Oc Ar device
Deletes a
.Dq largeBlob
corresponding to
.Ar rp_id
from
.Ar device .
If
.Ar rp_id
has multiple credentials enrolled on
.Ar device ,
the credential ID must be specified using
.Fl i Ar cred_id ,
where
.Ar cred_id
is a base64-encoded blob.
A PIN or equivalent user-verification gesture is required.
.It Fl D Fl e Fl i Ar id Ar device
Deletes the biometric enrollment specified by
.Ar id
from
.Ar device ,
where
.Ar id
is the enrollment's template base64-encoded id.
The user will be prompted for the PIN.
.It Fl D Fl u Ar device
Disables the FIDO 2.1
.Dq user verification always
feature on
.Ar device .
.It Fl G Fl b Fl k Ar key_path Ar blob_path Ar device
Gets a FIDO 2.1
.Dq largeBlob
encrypted with
.Ar key_path
from
.Ar device ,
where
.Ar key_path
must hold the blob's base64-encoded encryption key.
The blob is written to
.Ar blob_path .
A PIN or equivalent user-verification gesture is required.
.It Fl G Fl b Fl n Ar rp_id Oo Fl i Ar cred_id Oc Ar blob_path Ar device
Gets a FIDO 2.1
.Dq largeBlob
associated with
.Ar rp_id
from
.Ar device .
If
.Ar rp_id
has multiple credentials enrolled on
.Ar device ,
the credential ID must be specified using
.Fl i Ar cred_id ,
where
.Ar cred_id
is a base64-encoded blob.
The blob is written to
.Ar blob_path .
A PIN or equivalent user-verification gesture is required.
.It Fl I Ar device
Retrieves information on
.Ar device .
.It Fl I Fl c Ar device
Retrieves resident credential metadata from
.Ar device .
The user will be prompted for the PIN.
.It Fl I Fl k Ar rp_id Fl i Ar cred_id Ar device
Prints the credential id (base64-encoded) and public key
(PEM encoded) of the resident credential specified by
.Ar rp_id
and
.Ar cred_id ,
where
.Ar rp_id
is a UTF-8 relying party id, and
.Ar cred_id
is a base64-encoded credential id.
The user will be prompted for the PIN.
.It Fl L
Produces a list of authenticators found by the operating system.
.It Fl L Fl b Ar device
Produces a list of FIDO 2.1
.Dq largeBlobs
on
.Ar device .
A PIN or equivalent user-verification gesture is required.
.It Fl L Fl e Ar device
Produces a list of biometric enrollments on
.Ar device .
The user will be prompted for the PIN.
.It Fl L Fl r Ar device
Produces a list of relying parties with resident credentials on
.Ar device .
The user will be prompted for the PIN.
.It Fl L Fl k Ar rp_id Ar device
Produces a list of resident credentials corresponding to
relying party
.Ar rp_id
on
.Ar device .
The user will be prompted for the PIN.
.It Fl R
Performs a reset on
.Ar device .
.Nm
will NOT prompt for confirmation.
.It Fl S
Sets the PIN of
.Ar device .
The user will be prompted for the PIN.
.It Fl S Fl a Ar device
Enables FIDO 2.1 Enterprise Attestation on
.Ar device .
.It Fl S Fl b Fl k Ar key_path Ar blob_path Ar device
Sets
.Ar blob_path
as a FIDO 2.1
.Dq largeBlob
encrypted with
.Ar key_path
on
.Ar device ,
where
.Ar blob_path
holds the blob's plaintext, and
.Ar key_path
the blob's base64-encoded encryption.
A PIN or equivalent user-verification gesture is required.
.It Fl S Fl b Fl n Ar rp_id Oo Fl i Ar cred_id Oc Ar blob_path Ar device
Sets
.Ar blob_path
as a FIDO 2.1
.Dq largeBlob
associated with
.Ar rp_id
on
.Ar device .
If
.Ar rp_id
has multiple credentials enrolled on
.Ar device ,
the credential ID must be specified using
.Fl i Ar cred_id ,
where
.Ar cred_id
is a base64-encoded blob.
A PIN or equivalent user-verification gesture is required.
.It Fl S Fl c Fl i Ar cred_id Fl k Ar user_id Fl n Ar name Fl p Ar display_name Ar device
Sets the
.Ar name
and
.Ar display_name
attributes of the resident credential identified by
.Ar cred_id
and
.Ar user_id ,
where
.Ar name
and
.Ar display_name
are UTF-8 strings and
.Ar cred_id
and
.Ar user_id
are base64-encoded blobs.
A PIN or equivalent user-verification gesture is required.
.It Fl S Fl e Ar device
Performs a new biometric enrollment on
.Ar device .
The user will be prompted for the PIN.
.It Fl S Fl e Fl i Ar template_id Fl n Ar template_name Ar device
Sets the friendly name of the biometric enrollment specified by
.Ar template_id
to
.Ar template_name
on
.Ar device ,
where
.Ar template_id
is base64-encoded and
.Ar template_name
is a UTF-8 string.
The user will be prompted for the PIN.
.It Fl S Fl f Ar device
Forces a PIN change on
.Ar device .
The user will be prompted for the PIN.
.It Fl S Fl l Ar pin_length Ar device
Sets the minimum PIN length of
.Ar device
to
.Ar pin_length .
The user will be prompted for the PIN.
.It Fl S Fl u Ar device
Enables the FIDO 2.1
.Dq user verification always
feature on
.Ar device .
.It Fl V
Prints version information.
.It Fl d
Causes
.Nm
to emit debugging output on
.Em stderr .
.El
.Pp
If a
.Em tty
is available,
.Nm
will use it to prompt for PINs.
Otherwise,
.Em stdin
is used.
.Pp
.Nm
exits 0 on success and 1 on error.
.Sh SEE ALSO
.Xr fido2-assert 1 ,
.Xr fido2-cred 1
.Sh CAVEATS
The actual user-flow to perform a reset is outside the scope of the
FIDO2 specification, and may therefore vary depending on the
authenticator.
Yubico authenticators do not allow resets after 5 seconds from
power-up, and expect a reset to be confirmed by the user through
touch within 30 seconds.
.Pp
An authenticator's path may contain spaces.
.Pp
Resident credentials are called
.Dq discoverable credentials
in FIDO 2.1.
.Pp
Whether the FIDO 2.1
.Dq user verification always
feature is activated or deactivated after an authenticator reset
is vendor-specific.