diff options
Diffstat (limited to 'man/fido2-cred.1')
-rw-r--r-- | man/fido2-cred.1 | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/man/fido2-cred.1 b/man/fido2-cred.1 new file mode 100644 index 0000000..d9bf7d2 --- /dev/null +++ b/man/fido2-cred.1 | |||
@@ -0,0 +1,238 @@ | |||
1 | .\" Copyright (c) 2018 Yubico AB. All rights reserved. | ||
2 | .\" Use of this source code is governed by a BSD-style | ||
3 | .\" license that can be found in the LICENSE file. | ||
4 | .\" | ||
5 | .Dd $Mdocdate: November 5 2019 $ | ||
6 | .Dt FIDO2-CRED 1 | ||
7 | .Os | ||
8 | .Sh NAME | ||
9 | .Nm fido2-cred | ||
10 | .Nd make/verify a FIDO 2 credential | ||
11 | .Sh SYNOPSIS | ||
12 | .Nm | ||
13 | .Fl M | ||
14 | .Op Fl dhqruv | ||
15 | .Op Fl i Ar input_file | ||
16 | .Op Fl o Ar output_file | ||
17 | .Ar device | ||
18 | .Op Ar type | ||
19 | .Nm | ||
20 | .Fl V | ||
21 | .Op Fl dhv | ||
22 | .Op Fl i Ar input_file | ||
23 | .Op Fl o Ar output_file | ||
24 | .Op Ar type | ||
25 | .Sh DESCRIPTION | ||
26 | .Nm | ||
27 | makes or verifies a FIDO 2 credential. | ||
28 | .Pp | ||
29 | A credential | ||
30 | .Ar type | ||
31 | may be | ||
32 | .Em es256 | ||
33 | (denoting ECDSA over NIST P-256 with SHA-256), | ||
34 | .Em rs256 | ||
35 | (denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or | ||
36 | .Em eddsa | ||
37 | (denoting EDDSA over Curve25519 with SHA-512). | ||
38 | If | ||
39 | .Ar type | ||
40 | is not specified, | ||
41 | .Em es256 | ||
42 | is assumed. | ||
43 | .Pp | ||
44 | When making a credential, the authenticator may require the user | ||
45 | to authenticate with a PIN. | ||
46 | If the | ||
47 | .Fl q | ||
48 | option is not specified, | ||
49 | .Nm | ||
50 | will prompt the user for the PIN. | ||
51 | If a | ||
52 | .Em tty | ||
53 | is available, | ||
54 | .Nm | ||
55 | will use it to obtain the PIN. | ||
56 | Otherwise, | ||
57 | .Em stdin | ||
58 | is used. | ||
59 | .Pp | ||
60 | The input of | ||
61 | .Nm | ||
62 | is defined by the parameters of the credential to be made/verified. | ||
63 | See the | ||
64 | .Sx INPUT FORMAT | ||
65 | section for details. | ||
66 | .Pp | ||
67 | The output of | ||
68 | .Nm | ||
69 | is defined by the result of the selected operation. | ||
70 | See the | ||
71 | .Sx OUTPUT FORMAT | ||
72 | section for details. | ||
73 | .Pp | ||
74 | If a credential is successfully created or verified, | ||
75 | .Nm | ||
76 | exits 0. | ||
77 | Otherwise, | ||
78 | .Nm | ||
79 | exits 1. | ||
80 | .Pp | ||
81 | The options are as follows: | ||
82 | .Bl -tag -width Ds | ||
83 | .It Fl M | ||
84 | Tells | ||
85 | .Nm | ||
86 | to make a new credential on | ||
87 | .Ar device . | ||
88 | .It Fl V | ||
89 | Tells | ||
90 | .Nm | ||
91 | to verify a credential. | ||
92 | .It Fl d | ||
93 | Causes | ||
94 | .Nm | ||
95 | to emit debugging output on | ||
96 | .Em stderr . | ||
97 | .It Fl h | ||
98 | If making a credential, enable the FIDO2 hmac-secret extension. | ||
99 | If verifying a credential, check whether the extension data bit was | ||
100 | signed by the authenticator. | ||
101 | .It Fl i Ar input_file | ||
102 | Tells | ||
103 | .Nm | ||
104 | to read the parameters of the credential from | ||
105 | .Ar input_file | ||
106 | instead of | ||
107 | .Em stdin . | ||
108 | .It Fl o Ar output_file | ||
109 | Tells | ||
110 | .Nm | ||
111 | to write output on | ||
112 | .Ar output_file | ||
113 | instead of | ||
114 | .Em stdout . | ||
115 | .It Fl q | ||
116 | Tells | ||
117 | .Nm | ||
118 | to be quiet. | ||
119 | If a PIN is required and | ||
120 | .Fl q | ||
121 | is specified, | ||
122 | .Nm | ||
123 | will fail. | ||
124 | .It Fl r | ||
125 | Create a resident credential. | ||
126 | .It Fl u | ||
127 | Create a U2F credential. | ||
128 | By default, | ||
129 | .Nm | ||
130 | will use FIDO2 if supported by the authenticator, and fallback to | ||
131 | U2F otherwise. | ||
132 | .It Fl v | ||
133 | If making a credential, request user verification. | ||
134 | If verifying a credential, check whether the user verification bit | ||
135 | was signed by the authenticator. | ||
136 | .El | ||
137 | .Sh INPUT FORMAT | ||
138 | The input of | ||
139 | .Nm | ||
140 | consists of base64 blobs and UTF-8 strings separated | ||
141 | by newline characters ('\\n'). | ||
142 | .Pp | ||
143 | When making a credential, | ||
144 | .Nm | ||
145 | expects its input to consist of: | ||
146 | .Pp | ||
147 | .Bl -enum -offset indent -compact | ||
148 | .It | ||
149 | client data hash (base64 blob); | ||
150 | .It | ||
151 | relying party id (UTF-8 string); | ||
152 | .It | ||
153 | user name (UTF-8 string); | ||
154 | .It | ||
155 | user id (base64 blob). | ||
156 | .El | ||
157 | .Pp | ||
158 | When verifying a credential, | ||
159 | .Nm | ||
160 | expects its input to consist of: | ||
161 | .Pp | ||
162 | .Bl -enum -offset indent -compact | ||
163 | .It | ||
164 | client data hash (base64 blob); | ||
165 | .It | ||
166 | relying party id (UTF-8 string); | ||
167 | .It | ||
168 | credential format (UTF-8 string); | ||
169 | .It | ||
170 | authenticator data (base64 blob); | ||
171 | .It | ||
172 | credential id (base64 blob); | ||
173 | .It | ||
174 | attestation signature (base64 blob); | ||
175 | .It | ||
176 | attestation certificate (optional, base64 blob). | ||
177 | .El | ||
178 | .Pp | ||
179 | UTF-8 strings passed to | ||
180 | .Nm | ||
181 | must not contain embedded newline or NUL characters. | ||
182 | .Sh OUTPUT FORMAT | ||
183 | The output of | ||
184 | .Nm | ||
185 | consists of base64 blobs, UTF-8 strings, and PEM-encoded public | ||
186 | keys separated by newline characters ('\\n'). | ||
187 | .Pp | ||
188 | Upon the successful generation of a credential, | ||
189 | .Nm | ||
190 | outputs: | ||
191 | .Pp | ||
192 | .Bl -enum -offset indent -compact | ||
193 | .It | ||
194 | client data hash (base64 blob); | ||
195 | .It | ||
196 | relying party id (UTF-8 string); | ||
197 | .It | ||
198 | credential format (UTF-8 string); | ||
199 | .It | ||
200 | authenticator data (base64 blob); | ||
201 | .It | ||
202 | credential id (base64 blob); | ||
203 | .It | ||
204 | attestation signature (base64 blob); | ||
205 | .It | ||
206 | attestation certificate, if present (base64 blob). | ||
207 | .El | ||
208 | .Pp | ||
209 | Upon the successful verification of a credential, | ||
210 | .Nm | ||
211 | outputs: | ||
212 | .Pp | ||
213 | .Bl -enum -offset indent -compact | ||
214 | .It | ||
215 | credential id (base64 blob); | ||
216 | .It | ||
217 | PEM-encoded credential key. | ||
218 | .El | ||
219 | .Sh EXAMPLES | ||
220 | Create a new | ||
221 | .Em es256 | ||
222 | credential on | ||
223 | .Pa /dev/hidraw5 , | ||
224 | verify it, and save the id and the public key of the credential in | ||
225 | .Em cred : | ||
226 | .Pp | ||
227 | .Dl $ echo credential challenge | openssl sha256 -binary | base64 > cred_param | ||
228 | .Dl $ echo relying party >> cred_param | ||
229 | .Dl $ echo user name >> cred_param | ||
230 | .Dl $ dd if=/dev/urandom bs=1 count=32 | base64 >> cred_param | ||
231 | .Dl $ fido2-cred -M -i cred_param /dev/hidraw5 | fido2-cred -V -o cred | ||
232 | .Sh SEE ALSO | ||
233 | .Xr fido2-assert 1 , | ||
234 | .Xr fido2-token 1 | ||
235 | .Sh CAVEATS | ||
236 | Please note that | ||
237 | .Nm | ||
238 | handles Basic Attestation and Self Attestation transparently. | ||