Debian Codegraph @

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

raw
1 .\" Copyright (c) 2018-2023 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: July 3 2023 $
29 .Dt FIDO2-ASSERT 1
30 .Os
31 .Sh NAME
32 .Nm fido2-assert
33 .Nd get/verify a FIDO2 assertion
34 .Sh SYNOPSIS
35 .Nm
36 .Fl G
37 .Op Fl bdhpruvw
38 .Op Fl t Ar option
39 .Op Fl i Ar input_file
40 .Op Fl o Ar output_file
41 .Ar device
42 .Nm
43 .Fl V
44 .Op Fl dhpv
45 .Op Fl i Ar input_file
46 .Ar key_file
47 .Op Ar type
48 .Sh DESCRIPTION
49 .Nm
50 gets or verifies a FIDO2 assertion.
51 .Pp
52 The input of
53 .Nm
54 is defined by the parameters of the assertion to be obtained/verified.
55 See the
56 .Sx INPUT FORMAT
57 section for details.
58 .Pp
59 The output of
60 .Nm
61 is defined by the result of the selected operation.
62 See the
63 .Sx OUTPUT FORMAT
64 section for details.
65 .Pp
66 If an assertion is successfully obtained or verified,
67 .Nm
68 exits 0.
69 Otherwise,
70 .Nm
71 exits 1.
72 .Pp
73 The options are as follows:
74 .Bl -tag -width Ds
75 .It Fl G
76 Tells
77 .Nm
78 to obtain a new assertion from
79 .Ar device .
80 .It Fl V
81 Tells
82 .Nm
83 to verify an assertion using the PEM-encoded public key in
84 .Ar key_file
85 of type
86 .Ar type ,
87 where
88 .Ar type
89 may be
90 .Em es256
91 (denoting ECDSA over NIST P-256 with SHA-256),
92 .Em rs256
93 (denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or
94 .Em eddsa
95 (denoting EDDSA over Curve25519 with SHA-512).
96 If
97 .Ar type
98 is not specified,
99 .Em es256
100 is assumed.
101 .It Fl b
102 Request the credential's
103 .Dq largeBlobKey ,
104 a 32-byte symmetric key associated with the asserted credential.
105 .It Fl h
106 If obtaining an assertion, enable the FIDO2 hmac-secret
107 extension.
108 If verifying an assertion, check whether the extension data bit was
109 signed by the authenticator.
110 .It Fl d
111 Causes
112 .Nm
113 to emit debugging output on
114 .Em stderr .
115 .It Fl i Ar input_file
116 Tells
117 .Nm
118 to read the parameters of the assertion from
119 .Ar input_file
120 instead of
121 .Em stdin .
122 .It Fl o Ar output_file
123 Tells
124 .Nm
125 to write output on
126 .Ar output_file
127 instead of
128 .Em stdout .
129 .It Fl p
130 If obtaining an assertion, request user presence.
131 If verifying an assertion, check whether the user presence bit was
132 signed by the authenticator.
133 .It Fl r
134 Obtain an assertion using a resident credential.
135 If
136 .Fl r
137 is specified,
138 .Nm
139 will not expect a credential id in its input, and may output
140 multiple assertions.
141 Resident credentials are called
142 .Dq discoverable credentials
143 in CTAP 2.1.
144 .It Fl t Ar option
145 Toggles a key/value
146 .Ar option ,
147 where
148 .Ar option
149 is a string of the form
150 .Dq key=value .
151 The options supported at present are:
152 .Bl -tag -width Ds
153 .It Cm up Ns = Ns Ar true|false
154 Asks the authenticator for user presence to be enabled or disabled.
155 .It Cm uv Ns = Ns Ar true|false
156 Asks the authenticator for user verification to be enabled or
157 disabled.
158 .It Cm pin Ns = Ns Ar true|false
159 Tells
160 .Nm
161 whether to prompt for a PIN and request user verification.
162 .El
163 .Pp
164 The
165 .Fl t
166 option may be specified multiple times.
167 .It Fl u
168 Obtain an assertion using U2F.
169 By default,
170 .Nm
171 will use FIDO2 if supported by the authenticator, and fallback to
172 U2F otherwise.
173 .It Fl v
174 If obtaining an assertion, prompt the user for a PIN and request
175 user verification from the authenticator.
176 If verifying an assertion, check whether the user verification bit
177 was signed by the authenticator.
178 .It Fl w
179 Tells
180 .Nm
181 that the first line of input when obtaining an assertion shall be
182 interpreted as unhashed client data.
183 This is required by Windows Hello, which calculates the client data hash
184 internally.
185 .El
186 .Pp
187 If a
188 .Em tty
189 is available,
190 .Nm
191 will use it to obtain the PIN.
192 Otherwise,
193 .Em stdin
194 is used.
195 .Sh INPUT FORMAT
196 The input of
197 .Nm
198 consists of base64 blobs and UTF-8 strings separated
199 by newline characters ('\\n').
200 .Pp
201 When obtaining an assertion,
202 .Nm
203 expects its input to consist of:
204 .Pp
205 .Bl -enum -offset indent -compact
206 .It
207 client data hash (base64 blob);
208 .It
209 relying party id (UTF-8 string);
210 .It
211 credential id, if credential not resident (base64 blob);
212 .It
213 hmac salt, if the FIDO2 hmac-secret extension is enabled
214 (base64 blob);
215 .El
216 .Pp
217 When verifying an assertion,
218 .Nm
219 expects its input to consist of:
220 .Pp
221 .Bl -enum -offset indent -compact
222 .It
223 client data hash (base64 blob);
224 .It
225 relying party id (UTF-8 string);
226 .It
227 authenticator data (base64 blob);
228 .It
229 assertion signature (base64 blob);
230 .El
231 .Pp
232 UTF-8 strings passed to
233 .Nm
234 must not contain embedded newline or NUL characters.
235 .Sh OUTPUT FORMAT
236 The output of
237 .Nm
238 consists of base64 blobs and UTF-8 strings separated
239 by newline characters ('\\n').
240 .Pp
241 For each generated assertion,
242 .Nm
243 outputs:
244 .Pp
245 .Bl -enum -offset indent -compact
246 .It
247 client data hash (base64 blob);
248 .It
249 relying party id (UTF-8 string);
250 .It
251 authenticator data (base64 blob);
252 .It
253 assertion signature (base64 blob);
254 .It
255 user id, if credential resident (base64 blob);
256 .It
257 hmac secret, if the FIDO2 hmac-secret extension is enabled
258 (base64 blob);
259 .It
260 the credential's associated 32-byte symmetric key
261 .Pq Dq largeBlobKey ,
262 if requested (base64 blob).
263 .El
264 .Pp
265 When verifying an assertion,
266 .Nm
267 produces no output.
268 .Sh EXAMPLES
269 Assuming
270 .Pa cred
271 contains a
272 .Em es256
273 credential created according to the steps outlined in
274 .Xr fido2-cred 1 ,
275 obtain an assertion from an authenticator at
276 .Pa /dev/hidraw5
277 and verify it:
278 .Pp
279 .Dl $ echo assertion challenge | openssl sha256 -binary | base64 > assert_param
280 .Dl $ echo relying party >> assert_param
281 .Dl $ head -1 cred >> assert_param
282 .Dl $ tail -n +2 cred > pubkey
283 .Dl $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V pubkey es256
284 .Sh SEE ALSO
285 .Xr fido2-cred 1 ,
286 .Xr fido2-token 1