3e696dfb70
Some highlights from NEWS:
** bio: fix CTAP2 canonical CBOR encoding in fido_bio_dev_enroll_*();
gh#480.
** New API calls:
- fido_dev_info_set;
- fido_dev_io_handle;
- fido_dev_new_with_info;
- fido_dev_open_with_info.
** Documentation and reliability fixes.
** Support for TPM 2.0 attestation of COSE_ES256 credentials.
Relnotes: Yes
Sponsored by: The FreeBSD Foundation
401 lines
7.5 KiB
Groff
401 lines
7.5 KiB
Groff
.\" 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 FIDO2 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
|
|
.Ar device
|
|
.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 S
|
|
.Fl m
|
|
.Ar rp_id
|
|
.Ar device
|
|
.Nm
|
|
.Fl V
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
manages a FIDO2 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 CTAP 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 CTAP 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 CTAP 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 CTAP 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 CTAP 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 CTAP 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 CTAP 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 m Ar rp_id Ar device
|
|
Sets the list of relying party IDs that are allowed to retrieve
|
|
the minimum PIN length of
|
|
.Ar device .
|
|
Multiple IDs may be specified, separated by commas.
|
|
The user will be prompted for the PIN.
|
|
.It Fl S Fl u Ar device
|
|
Enables the CTAP 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 CTAP 2.1.
|
|
.Pp
|
|
Whether the CTAP 2.1
|
|
.Dq user verification always
|
|
feature is activated or deactivated after an authenticator reset
|
|
is vendor-specific.
|