Debian Codegraph @

examples/README.adoc

raw
1 = Examples
2
3 === Definitions
4
5 The following definitions are used in the description below:
6
7 - <device>
8
9 The file system path or subsystem-specific identification string of a
10 FIDO device.
11
12 - <pin>, [oldpin]
13
14 Strings passed directly in the executed command's argument vector.
15
16 - <cred_id>
17
18 The file system path of a file containing a FIDO credential ID in
19 binary representation.
20
21 - <pubkey>
22
23 The file system path of a file containing a public key in PEM format.
24
25 - <blobkey>
26
27 A credential's associated CTAP 2.1 "largeBlob" symmetric key.
28
29 === Description
30
31 The following examples are provided:
32
33 - manifest
34
35 Prints a list of configured FIDO devices.
36
37 - info <device>
38
39 Prints information about <device>.
40
41 - reset <device>
42
43 Performs a factory reset on <device>.
44
45 - setpin <pin> [oldpin] <device>
46
47 Configures <pin> as the new PIN of <device>. If [oldpin] is provided,
48 the device's PIN is changed from [oldpin] to <pin>.
49
50 - cred [-t es256|es384|rs256|eddsa] [-k pubkey] [-ei cred_id] [-P pin]
51 [-T seconds] [-b blobkey] [-hruv] [-c cred_protect] <device>
52
53 Creates a new credential on <device> and verify that the credential
54 was signed by the authenticator. The device's attestation certificate
55 is not verified. If option -k is specified, the credential's public
56 key is stored in <pubkey>. If option -i is specified, the credential
57 ID is stored in <cred_id>. The -e option may be used to add <cred_id>
58 to the list of excluded credentials. If option -h is specified,
59 the hmac-secret FIDO2 extension is enabled on the generated
60 credential. If option -r is specified, the generated credential
61 will involve a resident key. User verification may be requested
62 through the -v option. If option -u is specified, the credential
63 is generated using U2F (CTAP1) instead of FIDO2 (CTAP2) commands.
64 The -T option may be used to enforce a timeout of <seconds>. If the
65 option -b is specified, the credential's "largeBlob" key is stored in
66 <blobkey>. If the option -c is specified the the generated credential
67 will be bound by the specified protection policy. If the option -a is
68 specified, enterprise attestation will be requested.
69
70 - assert [-t es256|es384|rs256|eddsa] [-a cred_id] [-h hmac_secret] [-P pin]
71 [-s hmac_salt] [-T seconds] [-b blobkey] [-puv] <pubkey> <device>
72
73 Asks <device> for a FIDO2 assertion corresponding to [cred_id],
74 which may be omitted for resident keys. The obtained assertion
75 is verified using <pubkey>. The -p option requests that the user
76 be present and checks whether the user presence bit was signed by the
77 authenticator. The -v option requests user verification and checks
78 whether the user verification bit was signed by the authenticator.
79 If option -u is specified, the assertion is generated using
80 U2F (CTAP1) instead of FIDO2 (CTAP2) commands. If option -s is
81 specified, a FIDO2 hmac-secret is requested from the authenticator,
82 and the contents of <hmac_salt> are used as the salt. If option -h
83 is specified, the resulting hmac-secret is stored in <hmac_secret>.
84 The -T option may be used to enforce a timeout of <seconds>. If the
85 option -b specified, the credential's "largeBlob" key is stored in
86 <blobkey>.
87
88 - retries <device>
89 Get the number of PIN attempts left on <device> before lockout.
90
91 - select
92
93 Enumerates available FIDO devices and, if more than one is present,
94 simultaneously requests touch on all of them, printing information
95 about the device touched.
96
97 - bio [-P pin] <device>
98
99 Shows a sequence of BIO operations (enrollment, template rename, template
100 enumeration, and removal) and how a PUAT can be instantiated to
101 minimize PIN use during these steps.
102
103 - largeblob [-P pin] <device>
104
105 Creates a new credential on <device>, and adds an associated large blob.
106 Then obtains an assertion and erases the large blob associated
107 to the credential on the previous step.
108
109 This example also demonstrates how to use a PUAT to provide user
110 verification during each phase.
111
112 Debugging is possible through the use of the FIDO_DEBUG environment variable.
113 If set, libfido2 will produce a log of its transactions with the authenticator.
114
115 Additionally, an example of a WebAuthn client using libfido2 is available at
116 https://github.com/martelletto/fido2-webauthn-client.