Debian Codegraph @

extra/libfido2/libfido2-1.15.0/man/fido2-cred.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-CRED 1
30 .Os
31 .Sh NAME
32 .Nm fido2-cred
33 .Nd make/verify a FIDO2 credential
34 .Sh SYNOPSIS
35 .Nm
36 .Fl M
37 .Op Fl bdhqruvw
38 .Op Fl c Ar cred_protect
39 .Op Fl i Ar input_file
40 .Op Fl o Ar output_file
41 .Ar device
42 .Op Ar type
43 .Nm
44 .Fl V
45 .Op Fl dhv
46 .Op Fl c Ar cred_protect
47 .Op Fl i Ar input_file
48 .Op Fl o Ar output_file
49 .Op Ar type
50 .Sh DESCRIPTION
51 .Nm
52 makes or verifies a FIDO2 credential.
53 .Pp
54 A credential
55 .Ar type
56 may be
57 .Em es256
58 (denoting ECDSA over NIST P-256 with SHA-256),
59 .Em rs256
60 (denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or
61 .Em eddsa
62 (denoting EDDSA over Curve25519 with SHA-512).
63 If
64 .Ar type
65 is not specified,
66 .Em es256
67 is assumed.
68 .Pp
69 When making a credential, the authenticator may require the user
70 to authenticate with a PIN.
71 If the
72 .Fl q
73 option is not specified,
74 .Nm
75 will prompt the user for the PIN.
76 If a
77 .Em tty
78 is available,
79 .Nm
80 will use it to obtain the PIN.
81 Otherwise,
82 .Em stdin
83 is used.
84 .Pp
85 The input of
86 .Nm
87 is defined by the parameters of the credential to be made/verified.
88 See the
89 .Sx INPUT FORMAT
90 section for details.
91 .Pp
92 The output of
93 .Nm
94 is defined by the result of the selected operation.
95 See the
96 .Sx OUTPUT FORMAT
97 section for details.
98 .Pp
99 If a credential is successfully created or verified,
100 .Nm
101 exits 0.
102 Otherwise,
103 .Nm
104 exits 1.
105 .Pp
106 The options are as follows:
107 .Bl -tag -width Ds
108 .It Fl M
109 Tells
110 .Nm
111 to make a new credential on
112 .Ar device .
113 .It Fl V
114 Tells
115 .Nm
116 to verify a credential.
117 .It Fl b
118 Request the credential's
119 .Dq largeBlobKey ,
120 a 32-byte symmetric key associated with the generated credential.
121 .It Fl c Ar cred_protect
122 If making a credential, set the credential's protection level to
123 .Ar cred_protect ,
124 where
125 .Ar cred_protect
126 is the credential's protection level in decimal notation.
127 Please refer to
128 .In fido/param.h
129 for the set of possible values.
130 If verifying a credential, check whether the credential's protection
131 level was signed by the authenticator as
132 .Ar cred_protect .
133 .It Fl d
134 Causes
135 .Nm
136 to emit debugging output on
137 .Em stderr .
138 .It Fl h
139 If making a credential, enable the FIDO2 hmac-secret extension.
140 If verifying a credential, check whether the extension data bit was
141 signed by the authenticator.
142 .It Fl i Ar input_file
143 Tells
144 .Nm
145 to read the parameters of the credential from
146 .Ar input_file
147 instead of
148 .Em stdin .
149 .It Fl o Ar output_file
150 Tells
151 .Nm
152 to write output on
153 .Ar output_file
154 instead of
155 .Em stdout .
156 .It Fl q
157 Tells
158 .Nm
159 to be quiet.
160 If a PIN is required and
161 .Fl q
162 is specified,
163 .Nm
164 will fail.
165 .It Fl r
166 Create a resident credential.
167 Resident credentials are called
168 .Dq discoverable credentials
169 in CTAP 2.1.
170 .It Fl u
171 Create a U2F credential.
172 By default,
173 .Nm
174 will use FIDO2 if supported by the authenticator, and fallback to
175 U2F otherwise.
176 .It Fl v
177 If making a credential, request user verification.
178 If verifying a credential, check whether the user verification bit
179 was signed by the authenticator.
180 .It Fl w
181 Tells
182 .Nm
183 that the first line of input when making a credential shall be
184 interpreted as unhashed client data.
185 This is required by Windows Hello, which calculates the client data hash
186 internally.
187 .El
188 .Sh INPUT FORMAT
189 The input of
190 .Nm
191 consists of base64 blobs and UTF-8 strings separated
192 by newline characters ('\\n').
193 .Pp
194 When making a credential,
195 .Nm
196 expects its input to consist of:
197 .Pp
198 .Bl -enum -offset indent -compact
199 .It
200 client data hash (base64 blob);
201 .It
202 relying party id (UTF-8 string);
203 .It
204 user name (UTF-8 string);
205 .It
206 user id (base64 blob).
207 .El
208 .Pp
209 When verifying a credential,
210 .Nm
211 expects its input to consist of:
212 .Pp
213 .Bl -enum -offset indent -compact
214 .It
215 client data hash (base64 blob);
216 .It
217 relying party id (UTF-8 string);
218 .It
219 credential format (UTF-8 string);
220 .It
221 authenticator data (base64 blob);
222 .It
223 credential id (base64 blob);
224 .It
225 attestation signature (base64 blob);
226 .It
227 attestation certificate (optional, base64 blob).
228 .El
229 .Pp
230 UTF-8 strings passed to
231 .Nm
232 must not contain embedded newline or NUL characters.
233 .Sh OUTPUT FORMAT
234 The output of
235 .Nm
236 consists of base64 blobs, UTF-8 strings, and PEM-encoded public
237 keys separated by newline characters ('\\n').
238 .Pp
239 Upon the successful generation of a credential,
240 .Nm
241 outputs:
242 .Pp
243 .Bl -enum -offset indent -compact
244 .It
245 client data hash (base64 blob);
246 .It
247 relying party id (UTF-8 string);
248 .It
249 credential format (UTF-8 string);
250 .It
251 authenticator data (base64 blob);
252 .It
253 credential id (base64 blob);
254 .It
255 attestation signature (base64 blob);
256 .It
257 attestation certificate, if present (base64 blob).
258 .It
259 the credential's associated 32-byte symmetric key
260 .Pq Dq largeBlobKey ,
261 if present (base64 blob).
262 .El
263 .Pp
264 Upon the successful verification of a credential,
265 .Nm
266 outputs:
267 .Pp
268 .Bl -enum -offset indent -compact
269 .It
270 credential id (base64 blob);
271 .It
272 PEM-encoded credential key.
273 .El
274 .Sh EXAMPLES
275 Create a new
276 .Em es256
277 credential on
278 .Pa /dev/hidraw5 ,
279 verify it, and save the id and the public key of the credential in
280 .Em cred :
281 .Pp
282 .Dl $ echo credential challenge | openssl sha256 -binary | base64 > cred_param
283 .Dl $ echo relying party >> cred_param
284 .Dl $ echo user name >> cred_param
285 .Dl $ dd if=/dev/urandom bs=1 count=32 | base64 >> cred_param
286 .Dl $ fido2-cred -M -i cred_param /dev/hidraw5 | fido2-cred -V -o cred
287 .Sh SEE ALSO
288 .Xr fido2-assert 1 ,
289 .Xr fido2-token 1
290 .Sh CAVEATS
291 Please note that
292 .Nm
293 handles Basic Attestation and Self Attestation transparently.
294 In the case of Basic Attestation, the validity of the authenticator's
295 attestation certificate is
296 .Em not
297 verified.