Debian Codegraph @

extra/libfido2/libfido2-1.15.0/man/fido2-token.1

raw
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
147 manages a FIDO2 authenticator.
148 .Pp
149 The options are as follows:
150 .Bl -tag -width Ds
151 .It Fl C Ar device
152 Changes the PIN of
153 .Ar device .
154 The user will be prompted for the current and new PINs.
155 .It Fl D Fl i Ar id Ar device
156 Deletes the resident credential specified by
157 .Ar id
158 from
159 .Ar device ,
160 where
161 .Ar id
162 is the credential's base64-encoded id.
163 The user will be prompted for the PIN.
164 .It Fl D Fl b Fl k Ar key_path Ar device
165 Deletes a
166 .Dq largeBlob
167 encrypted with
168 .Ar key_path
169 from
170 .Ar device ,
171 where
172 .Ar key_path
173 holds the blob's base64-encoded 32-byte AES-256 GCM encryption key.
174 A 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
176 Deletes a
177 .Dq largeBlob
178 corresponding to
179 .Ar rp_id
180 from
181 .Ar device .
182 If
183 .Ar rp_id
184 has multiple credentials enrolled on
185 .Ar device ,
186 the credential ID must be specified using
187 .Fl i Ar cred_id ,
188 where
189 .Ar cred_id
190 is a base64-encoded blob.
191 A PIN or equivalent user-verification gesture is required.
192 .It Fl D Fl e Fl i Ar id Ar device
193 Deletes the biometric enrollment specified by
194 .Ar id
195 from
196 .Ar device ,
197 where
198 .Ar id
199 is the enrollment's template base64-encoded id.
200 The user will be prompted for the PIN.
201 .It Fl D Fl u Ar device
202 Disables the CTAP 2.1
203 .Dq user verification always
204 feature on
205 .Ar device .
206 .It Fl G Fl b Fl k Ar key_path Ar blob_path Ar device
207 Gets a CTAP 2.1
208 .Dq largeBlob
209 encrypted with
210 .Ar key_path
211 from
212 .Ar device ,
213 where
214 .Ar key_path
215 holds the blob's base64-encoded 32-byte AES-256 GCM encryption key.
216 The blob is written to
217 .Ar blob_path .
218 A 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
220 Gets a CTAP 2.1
221 .Dq largeBlob
222 associated with
223 .Ar rp_id
224 from
225 .Ar device .
226 If
227 .Ar rp_id
228 has multiple credentials enrolled on
229 .Ar device ,
230 the credential ID must be specified using
231 .Fl i Ar cred_id ,
232 where
233 .Ar cred_id
234 is a base64-encoded blob.
235 The blob is written to
236 .Ar blob_path .
237 A PIN or equivalent user-verification gesture is required.
238 .It Fl I Ar device
239 Retrieves information on
240 .Ar device .
241 .It Fl I Fl c Ar device
242 Retrieves resident credential metadata from
243 .Ar device .
244 The user will be prompted for the PIN.
245 .It Fl I Fl k Ar rp_id Fl i Ar cred_id Ar device
246 Prints the credential id (base64-encoded) and public key
247 (PEM encoded) of the resident credential specified by
248 .Ar rp_id
249 and
250 .Ar cred_id ,
251 where
252 .Ar rp_id
253 is a UTF-8 relying party id, and
254 .Ar cred_id
255 is a base64-encoded credential id.
256 The user will be prompted for the PIN.
257 .It Fl L
258 Produces a list of authenticators found by the operating system.
259 .It Fl L Fl b Ar device
260 Produces a list of CTAP 2.1
261 .Dq largeBlobs
262 on
263 .Ar device .
264 A PIN or equivalent user-verification gesture is required.
265 .It Fl L Fl e Ar device
266 Produces a list of biometric enrollments on
267 .Ar device .
268 The user will be prompted for the PIN.
269 .It Fl L Fl r Ar device
270 Produces a list of relying parties with resident credentials on
271 .Ar device .
272 The user will be prompted for the PIN.
273 .It Fl L Fl k Ar rp_id Ar device
274 Produces a list of resident credentials corresponding to
275 relying party
276 .Ar rp_id
277 on
278 .Ar device .
279 The user will be prompted for the PIN.
280 .It Fl R
281 Performs a reset on
282 .Ar device .
283 .Nm
284 will NOT prompt for confirmation.
285 .It Fl S
286 Sets the PIN of
287 .Ar device .
288 The user will be prompted for the PIN.
289 .It Fl S Fl a Ar device
290 Enables 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
293 Sets a CTAP 2.1
294 .Dq largeBlob
295 encrypted with
296 .Ar key_path
297 on
298 .Ar device ,
299 where
300 .Ar key_path
301 holds the blob's base64-encoded 32-byte AES-256 GCM encryption key.
302 The blob is read from
303 .Fa blob_path .
304 A 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
306 Sets a CTAP 2.1
307 .Dq largeBlob
308 associated with
309 .Ar rp_id
310 on
311 .Ar device .
312 The blob is read from
313 .Fa blob_path .
314 If
315 .Ar rp_id
316 has multiple credentials enrolled on
317 .Ar device ,
318 the credential ID must be specified using
319 .Fl i Ar cred_id ,
320 where
321 .Ar cred_id
322 is a base64-encoded blob.
323 A 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
325 Sets the
326 .Ar name
327 and
328 .Ar display_name
329 attributes of the resident credential identified by
330 .Ar cred_id
331 and
332 .Ar user_id ,
333 where
334 .Ar name
335 and
336 .Ar display_name
337 are UTF-8 strings and
338 .Ar cred_id
339 and
340 .Ar user_id
341 are base64-encoded blobs.
342 A PIN or equivalent user-verification gesture is required.
343 .It Fl S Fl e Ar device
344 Performs a new biometric enrollment on
345 .Ar device .
346 The 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
348 Sets the friendly name of the biometric enrollment specified by
349 .Ar template_id
350 to
351 .Ar template_name
352 on
353 .Ar device ,
354 where
355 .Ar template_id
356 is base64-encoded and
357 .Ar template_name
358 is a UTF-8 string.
359 The user will be prompted for the PIN.
360 .It Fl S Fl f Ar device
361 Forces a PIN change on
362 .Ar device .
363 The user will be prompted for the PIN.
364 .It Fl S Fl l Ar pin_length Ar device
365 Sets the minimum PIN length of
366 .Ar device
367 to
368 .Ar pin_length .
369 The user will be prompted for the PIN.
370 .It Fl S Fl m Ar rp_id Ar device
371 Sets the list of relying party IDs that are allowed to retrieve
372 the minimum PIN length of
373 .Ar device .
374 Multiple IDs may be specified, separated by commas.
375 The user will be prompted for the PIN.
376 .It Fl S Fl u Ar device
377 Enables the CTAP 2.1
378 .Dq user verification always
379 feature on
380 .Ar device .
381 .It Fl V
382 Prints version information.
383 .It Fl d
384 Causes
385 .Nm
386 to emit debugging output on
387 .Em stderr .
388 .El
389 .Pp
390 If a
391 .Em tty
392 is available,
393 .Nm
394 will use it to prompt for PINs.
395 Otherwise,
396 .Em stdin
397 is used.
398 .Pp
399 .Nm
400 exits 0 on success and 1 on error.
401 .Sh SEE ALSO
402 .Xr fido2-assert 1 ,
403 .Xr fido2-cred 1
404 .Sh CAVEATS
405 The actual user-flow to perform a reset is outside the scope of the
406 FIDO2 specification, and may therefore vary depending on the
407 authenticator.
408 Yubico authenticators do not allow resets after 5 seconds from
409 power-up, and expect a reset to be confirmed by the user through
410 touch within 30 seconds.
411 .Pp
412 An authenticator's path may contain spaces.
413 .Pp
414 Resident credentials are called
415 .Dq discoverable credentials
416 in CTAP 2.1.
417 .Pp
418 Whether the CTAP 2.1
419 .Dq user verification always
420 feature is activated or deactivated after an authenticator reset
421 is vendor-specific.