1FIDO2-ASSERT(1) BSD General Commands Manual FIDO2-ASSERT(1)
2
4 fido2-assert — get/verify a FIDO 2 assertion
5
7 fido2-assert -G [-bdhpruv] [-t option] [-i input_file] [-o output_file]
8 device
9 fido2-assert -V [-dhpv] [-i input_file] key_file [type]
10
12 fido2-assert gets or verifies a FIDO 2 assertion.
13 The input of fido2-assert is defined by the parameters of the assertion
15 to be obtained/verified. See the INPUT FORMAT section for details.
16 The output of fido2-assert is defined by the result of the selected oper‐
18 ation. See the OUTPUT FORMAT section for details.
19 If an assertion is successfully obtained or verified, fido2-assert exits
21 0. Otherwise, fido2-assert exits 1.
22 The options are as follows:
24 -G Tells fido2-assert to obtain a new assertion from device.
26 -V Tells fido2-assert to verify an assertion using the PEM-encoded
28 public key in key_file of type type, where type may be es256 (de‐
29 noting ECDSA over NIST P-256 with SHA-256), rs256 (denoting
30 2048-bit RSA with PKCS#1.5 padding and SHA-256), or eddsa (denot‐
31 ing EDDSA over Curve25519 with SHA-512). If type is not speci‐
32 fied, es256 is assumed.
33 -b Request the credential's “largeBlobKey”, a 32-byte symmetric key
35 associated with the asserted credential.
36 -h If obtaining an assertion, enable the FIDO2 hmac-secret exten‐
38 sion. If verifying an assertion, check whether the extension
39 data bit was signed by the authenticator.
40 -d Causes fido2-assert to emit debugging output on stderr.
42 -i input_file
44 Tells fido2-assert to read the parameters of the assertion from
45 input_file instead of stdin.
46 -o output_file
48 Tells fido2-assert to write output on output_file instead of
49 stdout.
50 -p If obtaining an assertion, request user presence. If verifying
52 an assertion, check whether the user presence bit was signed by
53 the authenticator.
54 -r Obtain an assertion using a resident credential. If -r is speci‐
56 fied, fido2-assert will not expect a credential id in its input,
57 and may output multiple assertions. Resident credentials are
58 called “discoverable credentials” in FIDO 2.1.
59 -t option
61 Toggles a key/value option, where option is a string of the form
62 “key=value”. The options supported at present are:
63 up=true|false
65 Asks the authenticator for user presence to be enabled or
66 disabled.
67 uv=true|false
69 Asks the authenticator for user verification to be en‐
70 abled or disabled.
71 pin=true|false
73 Tells fido2-assert whether to prompt for a PIN and re‐
74 quest user verification.
75 The -t option may be specified multiple times.
77 -u Obtain an assertion using U2F. By default, fido2-assert will use
79 FIDO2 if supported by the authenticator, and fallback to U2F oth‐
80 erwise.
81 -v If obtaining an assertion, prompt the user for a PIN and request
83 user verification from the authenticator. If verifying an asser‐
84 tion, check whether the user verification bit was signed by the
85 authenticator.
86 If a tty is available, fido2-assert will use it to obtain the PIN. Oth‐
88 erwise, stdin is used.
89
91 The input of fido2-assert consists of base64 blobs and UTF-8 strings sep‐
92 arated by newline characters ('\n').
93 When obtaining an assertion, fido2-assert expects its input to consist
95 of:
96 1. client data hash (base64 blob);
98 2. relying party id (UTF-8 string);
99 3. credential id, if credential not resident (base64 blob);
100 4. hmac salt, if the FIDO2 hmac-secret extension is enabled
101 (base64 blob);
102 When verifying an assertion, fido2-assert expects its input to consist
104 of:
105 1. client data hash (base64 blob);
107 2. relying party id (UTF-8 string);
108 3. authenticator data (base64 blob);
109 4. assertion signature (base64 blob);
110 UTF-8 strings passed to fido2-assert must not contain embedded newline or
112 NUL characters.
113
115 The output of fido2-assert consists of base64 blobs and UTF-8 strings
116 separated by newline characters ('\n').
117 For each generated assertion, fido2-assert outputs:
119 1. client data hash (base64 blob);
121 2. relying party id (UTF-8 string);
122 3. authenticator data (base64 blob);
123 4. assertion signature (base64 blob);
124 5. user id, if credential resident (base64 blob);
125 6. hmac secret, if the FIDO2 hmac-secret extension is enabled
126 (base64 blob);
127 7. the credential's associated 32-byte symmetric key
128 (“largeBlobKey”), if requested (base64 blob).
129 When verifying an assertion, fido2-assert produces no output.
131
133 Assuming cred contains a es256 credential created according to the steps
134 outlined in fido2-cred(1), obtain an assertion from an authenticator at
135 /dev/hidraw5 and verify it:
136 $ echo assertion challenge | openssl sha256 -binary | base64 >
138 assert_param
139 $ echo relying party >> assert_param
140 $ head -1 cred >> assert_param
141 $ tail -n +2 cred > pubkey
142 $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V
143 pubkey es256
144
146 fido2-cred(1), fido2-token(1)
147BSD November 5, 2019 BSD