1.\" Copyright (c) 2018-2022 Yubico AB. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions are 5.\" met: 6.\" 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in 11.\" the documentation and/or other materials provided with the 12.\" distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 15.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 16.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 17.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 18.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 19.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 20.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 24.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" SPDX-License-Identifier: BSD-2-Clause 27.\" 28.Dd $Mdocdate: April 11 2022 $ 29.Dt FIDO2-TOKEN 1 30.Os 31.Sh NAME 32.Nm fido2-token 33.Nd find and manage a FIDO2 authenticator 34.Sh SYNOPSIS 35.Nm 36.Fl C 37.Op Fl d 38.Ar device 39.Nm 40.Fl D 41.Op Fl d 42.Fl i 43.Ar cred_id 44.Ar device 45.Nm 46.Fl D 47.Fl b 48.Op Fl d 49.Fl k Ar key_path 50.Ar device 51.Nm 52.Fl D 53.Fl b 54.Op Fl d 55.Fl n Ar rp_id 56.Op Fl i Ar cred_id 57.Ar device 58.Nm 59.Fl D 60.Fl e 61.Op Fl d 62.Fl i 63.Ar template_id 64.Ar device 65.Nm 66.Fl D 67.Fl u 68.Op Fl d 69.Ar device 70.Nm 71.Fl G 72.Fl b 73.Op Fl d 74.Fl k Ar key_path 75.Ar blob_path 76.Ar device 77.Nm 78.Fl G 79.Fl b 80.Op Fl d 81.Fl n Ar rp_id 82.Op Fl i Ar cred_id 83.Ar blob_path 84.Ar device 85.Nm 86.Fl I 87.Op Fl cd 88.Op Fl k Ar rp_id Fl i Ar cred_id 89.Ar device 90.Nm 91.Fl L 92.Op Fl bder 93.Op Fl k Ar rp_id 94.Op device 95.Nm 96.Fl R 97.Op Fl d 98.Ar device 99.Nm 100.Fl S 101.Op Fl adefu 102.Ar device 103.Nm 104.Fl S 105.Op Fl d 106.Fl i Ar template_id 107.Fl n Ar template_name 108.Ar device 109.Nm 110.Fl S 111.Op Fl d 112.Fl l Ar pin_length 113.Ar device 114.Nm 115.Fl S 116.Fl b 117.Op Fl d 118.Fl k Ar key_path 119.Ar blob_path 120.Ar device 121.Nm 122.Fl S 123.Fl b 124.Op Fl d 125.Fl n Ar rp_id 126.Op Fl i Ar cred_id 127.Ar blob_path 128.Ar device 129.Nm 130.Fl S 131.Fl c 132.Op Fl d 133.Fl i Ar cred_id 134.Fl k Ar user_id 135.Fl n Ar name 136.Fl p Ar display_name 137.Ar device 138.Nm 139.Fl S 140.Fl m 141.Ar rp_id 142.Ar device 143.Nm 144.Fl V 145.Sh DESCRIPTION 146.Nm 147manages a FIDO2 authenticator. 148.Pp 149The options are as follows: 150.Bl -tag -width Ds 151.It Fl C Ar device 152Changes the PIN of 153.Ar device . 154The user will be prompted for the current and new PINs. 155.It Fl D Fl i Ar id Ar device 156Deletes the resident credential specified by 157.Ar id 158from 159.Ar device , 160where 161.Ar id 162is the credential's base64-encoded id. 163The user will be prompted for the PIN. 164.It Fl D Fl b Fl k Ar key_path Ar device 165Deletes a 166.Dq largeBlob 167encrypted with 168.Ar key_path 169from 170.Ar device , 171where 172.Ar key_path 173holds the blob's base64-encoded 32-byte AES-256 GCM encryption key. 174A PIN or equivalent user-verification gesture is required. 175.It Fl D Fl b Fl n Ar rp_id Oo Fl i Ar cred_id Oc Ar device 176Deletes a 177.Dq largeBlob 178corresponding to 179.Ar rp_id 180from 181.Ar device . 182If 183.Ar rp_id 184has multiple credentials enrolled on 185.Ar device , 186the credential ID must be specified using 187.Fl i Ar cred_id , 188where 189.Ar cred_id 190is a base64-encoded blob. 191A PIN or equivalent user-verification gesture is required. 192.It Fl D Fl e Fl i Ar id Ar device 193Deletes the biometric enrollment specified by 194.Ar id 195from 196.Ar device , 197where 198.Ar id 199is the enrollment's template base64-encoded id. 200The user will be prompted for the PIN. 201.It Fl D Fl u Ar device 202Disables the CTAP 2.1 203.Dq user verification always 204feature on 205.Ar device . 206.It Fl G Fl b Fl k Ar key_path Ar blob_path Ar device 207Gets a CTAP 2.1 208.Dq largeBlob 209encrypted with 210.Ar key_path 211from 212.Ar device , 213where 214.Ar key_path 215holds the blob's base64-encoded 32-byte AES-256 GCM encryption key. 216The blob is written to 217.Ar blob_path . 218A PIN or equivalent user-verification gesture is required. 219.It Fl G Fl b Fl n Ar rp_id Oo Fl i Ar cred_id Oc Ar blob_path Ar device 220Gets a CTAP 2.1 221.Dq largeBlob 222associated with 223.Ar rp_id 224from 225.Ar device . 226If 227.Ar rp_id 228has multiple credentials enrolled on 229.Ar device , 230the credential ID must be specified using 231.Fl i Ar cred_id , 232where 233.Ar cred_id 234is a base64-encoded blob. 235The blob is written to 236.Ar blob_path . 237A PIN or equivalent user-verification gesture is required. 238.It Fl I Ar device 239Retrieves information on 240.Ar device . 241.It Fl I Fl c Ar device 242Retrieves resident credential metadata from 243.Ar device . 244The user will be prompted for the PIN. 245.It Fl I Fl k Ar rp_id Fl i Ar cred_id Ar device 246Prints the credential id (base64-encoded) and public key 247(PEM encoded) of the resident credential specified by 248.Ar rp_id 249and 250.Ar cred_id , 251where 252.Ar rp_id 253is a UTF-8 relying party id, and 254.Ar cred_id 255is a base64-encoded credential id. 256The user will be prompted for the PIN. 257.It Fl L 258Produces a list of authenticators found by the operating system. 259.It Fl L Fl b Ar device 260Produces a list of CTAP 2.1 261.Dq largeBlobs 262on 263.Ar device . 264A PIN or equivalent user-verification gesture is required. 265.It Fl L Fl e Ar device 266Produces a list of biometric enrollments on 267.Ar device . 268The user will be prompted for the PIN. 269.It Fl L Fl r Ar device 270Produces a list of relying parties with resident credentials on 271.Ar device . 272The user will be prompted for the PIN. 273.It Fl L Fl k Ar rp_id Ar device 274Produces a list of resident credentials corresponding to 275relying party 276.Ar rp_id 277on 278.Ar device . 279The user will be prompted for the PIN. 280.It Fl R 281Performs a reset on 282.Ar device . 283.Nm 284will NOT prompt for confirmation. 285.It Fl S 286Sets the PIN of 287.Ar device . 288The user will be prompted for the PIN. 289.It Fl S Fl a Ar device 290Enables CTAP 2.1 Enterprise Attestation on 291.Ar device . 292.It Fl S Fl b Fl k Ar key_path Ar blob_path Ar device 293Sets a CTAP 2.1 294.Dq largeBlob 295encrypted with 296.Ar key_path 297on 298.Ar device , 299where 300.Ar key_path 301holds the blob's base64-encoded 32-byte AES-256 GCM encryption key. 302The blob is read from 303.Fa blob_path . 304A PIN or equivalent user-verification gesture is required. 305.It Fl S Fl b Fl n Ar rp_id Oo Fl i Ar cred_id Oc Ar blob_path Ar device 306Sets a CTAP 2.1 307.Dq largeBlob 308associated with 309.Ar rp_id 310on 311.Ar device . 312The blob is read from 313.Fa blob_path . 314If 315.Ar rp_id 316has multiple credentials enrolled on 317.Ar device , 318the credential ID must be specified using 319.Fl i Ar cred_id , 320where 321.Ar cred_id 322is a base64-encoded blob. 323A PIN or equivalent user-verification gesture is required. 324.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 325Sets the 326.Ar name 327and 328.Ar display_name 329attributes of the resident credential identified by 330.Ar cred_id 331and 332.Ar user_id , 333where 334.Ar name 335and 336.Ar display_name 337are UTF-8 strings and 338.Ar cred_id 339and 340.Ar user_id 341are base64-encoded blobs. 342A PIN or equivalent user-verification gesture is required. 343.It Fl S Fl e Ar device 344Performs a new biometric enrollment on 345.Ar device . 346The user will be prompted for the PIN. 347.It Fl S Fl e Fl i Ar template_id Fl n Ar template_name Ar device 348Sets the friendly name of the biometric enrollment specified by 349.Ar template_id 350to 351.Ar template_name 352on 353.Ar device , 354where 355.Ar template_id 356is base64-encoded and 357.Ar template_name 358is a UTF-8 string. 359The user will be prompted for the PIN. 360.It Fl S Fl f Ar device 361Forces a PIN change on 362.Ar device . 363The user will be prompted for the PIN. 364.It Fl S Fl l Ar pin_length Ar device 365Sets the minimum PIN length of 366.Ar device 367to 368.Ar pin_length . 369The user will be prompted for the PIN. 370.It Fl S Fl m Ar rp_id Ar device 371Sets the list of relying party IDs that are allowed to retrieve 372the minimum PIN length of 373.Ar device . 374Multiple IDs may be specified, separated by commas. 375The user will be prompted for the PIN. 376.It Fl S Fl u Ar device 377Enables the CTAP 2.1 378.Dq user verification always 379feature on 380.Ar device . 381.It Fl V 382Prints version information. 383.It Fl d 384Causes 385.Nm 386to emit debugging output on 387.Em stderr . 388.El 389.Pp 390If a 391.Em tty 392is available, 393.Nm 394will use it to prompt for PINs. 395Otherwise, 396.Em stdin 397is used. 398.Pp 399.Nm 400exits 0 on success and 1 on error. 401.Sh SEE ALSO 402.Xr fido2-assert 1 , 403.Xr fido2-cred 1 404.Sh CAVEATS 405The actual user-flow to perform a reset is outside the scope of the 406FIDO2 specification, and may therefore vary depending on the 407authenticator. 408Yubico authenticators do not allow resets after 5 seconds from 409power-up, and expect a reset to be confirmed by the user through 410touch within 30 seconds. 411.Pp 412An authenticator's path may contain spaces. 413.Pp 414Resident credentials are called 415.Dq discoverable credentials 416in CTAP 2.1. 417.Pp 418Whether the CTAP 2.1 419.Dq user verification always 420feature is activated or deactivated after an authenticator reset 421is vendor-specific. 422