1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
.\" Copyright (c) 2018 Yubico AB. All rights reserved.
.\" Use of this source code is governed by a BSD-style
.\" license that can be found in the LICENSE file.
.\"
.Dd $Mdocdate: November 5 2019 $
.Dt FIDO2-ASSERT 1
.Os
.Sh NAME
.Nm fido2-assert
.Nd get/verify a FIDO 2 assertion
.Sh SYNOPSIS
.Nm
.Fl G
.Op Fl dhpruv
.Op Fl i Ar input_file
.Op Fl o Ar output_file
.Ar device
.Nm
.Fl V
.Op Fl dhpv
.Op Fl i Ar input_file
.Ar key_file
.Op Ar type
.Sh DESCRIPTION
.Nm
gets or verifies a FIDO 2 assertion.
.Pp
The input of
.Nm
is defined by the parameters of the assertion to be obtained/verified.
See the
.Sx INPUT FORMAT
section for details.
.Pp
The output of
.Nm
is defined by the result of the selected operation.
See the
.Sx OUTPUT FORMAT
section for details.
.Pp
If an assertion is successfully obtained or verified,
.Nm
exits 0.
Otherwise,
.Nm
exits 1.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl G
Tells
.Nm
to obtain a new assertion from
.Ar device .
.It Fl V
Tells
.Nm
to verify an assertion using the PEM-encoded public key in
.Ar key_file
of type
.Ar type ,
where
.Ar type
may be
.Em es256
(denoting ECDSA over NIST P-256 with SHA-256),
.Em rs256
(denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or
.Em eddsa
(denoting EDDSA over Curve25519 with SHA-512).
If
.Ar type
is not specified,
.Em es256
is assumed.
.It Fl h
If obtaining an assertion, enable the FIDO2 hmac-secret
extension.
If verifying an assertion, check whether the extension data bit was
signed by the authenticator.
.It Fl d
Causes
.Nm
to emit debugging output on
.Em stderr .
.It Fl i Ar input_file
Tells
.Nm
to read the parameters of the assertion from
.Ar input_file
instead of
.Em stdin .
.It Fl o Ar output_file
Tells
.Nm
to write output on
.Ar output_file
instead of
.Em stdout .
.It Fl p
If obtaining an assertion, request user presence.
If verifying an assertion, check whether the user presence bit was
signed by the authenticator.
.It Fl r
Obtain an assertion using a resident credential.
If
.Fl r
is specified,
.Nm
will not expect a credential id in its input, and may output
multiple assertions.
.It Fl u
Obtain an assertion using U2F.
By default,
.Nm
will use FIDO2 if supported by the authenticator, and fallback to
U2F otherwise.
.It Fl v
If obtaining an assertion, prompt the user for a PIN and request
user verification from the authenticator.
If a
.Em tty
is available,
.Nm
will use it to obtain the PIN.
Otherwise,
.Em stdin
is used.
If verifying an assertion, check whether the user verification bit
was signed by the authenticator.
.El
.Sh INPUT FORMAT
The input of
.Nm
consists of base64 blobs and UTF-8 strings separated
by newline characters ('\\n').
.Pp
When obtaining an assertion,
.Nm
expects its input to consist of:
.Pp
.Bl -enum -offset indent -compact
.It
client data hash (base64 blob);
.It
relying party id (UTF-8 string);
.It
credential id, if credential not resident (base64 blob);
.It
hmac salt, if the FIDO2 hmac-secret extension is enabled
(base64 blob);
.El
.Pp
When verifying an assertion,
.Nm
expects its input to consist of:
.Pp
.Bl -enum -offset indent -compact
.It
client data hash (base64 blob);
.It
relying party id (UTF-8 string);
.It
authenticator data (base64 blob);
.It
assertion signature (base64 blob);
.El
.Pp
UTF-8 strings passed to
.Nm
must not contain embedded newline or NUL characters.
.Sh OUTPUT FORMAT
The output of
.Nm
consists of base64 blobs and UTF-8 strings separated
by newline characters ('\\n').
.Pp
For each generated assertion,
.Nm
outputs:
.Pp
.Bl -enum -offset indent -compact
.It
client data hash (base64 blob);
.It
relying party id (UTF-8 string);
.It
authenticator data (base64 blob);
.It
assertion signature (base64 blob);
.It
user id, if credential resident (base64 blob);
.It
hmac secret, if the FIDO2 hmac-secret extension is enabled
(base64 blob);
.El
.Pp
When verifying an assertion,
.Nm
produces no output.
.Sh EXAMPLES
Assuming
.Pa cred
contains a
.Em es256
credential created according to the steps outlined in
.Xr fido2-cred 1 ,
obtain an assertion from an authenticator at
.Pa /dev/hidraw5
and verify it:
.Pp
.Dl $ echo assertion challenge | openssl sha256 -binary | base64 > assert_param
.Dl $ echo relying party >> assert_param
.Dl $ head -1 cred >> assert_param
.Dl $ tail -n +2 cred > pubkey
.Dl $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V pubkey es256
.Sh SEE ALSO
.Xr fido2-cred 1 ,
.Xr fido2-token 1
|
