Debian Codegraph @

extra/libfido2/libfido2-1.15.0/man/fido_assert_set_authdata.3

raw
1 .\" Copyright (c) 2018-2022 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: April 8 2023 $
29 .Dt FIDO_ASSERT_SET_AUTHDATA 3
30 .Os
31 .Sh NAME
32 .Nm fido_assert_set_authdata ,
33 .Nm fido_assert_set_authdata_raw ,
34 .Nm fido_assert_set_clientdata ,
35 .Nm fido_assert_set_clientdata_hash ,
36 .Nm fido_assert_set_count ,
37 .Nm fido_assert_set_extensions ,
38 .Nm fido_assert_set_hmac_salt ,
39 .Nm fido_assert_set_hmac_secret ,
40 .Nm fido_assert_set_up ,
41 .Nm fido_assert_set_uv ,
42 .Nm fido_assert_set_rp ,
43 .Nm fido_assert_set_sig ,
44 .Nm fido_assert_set_winhello_appid
45 .Nd set parameters of a FIDO2 assertion
46 .Sh SYNOPSIS
47 .In fido.h
48 .Bd -literal
49 typedef enum {
50 FIDO_OPT_OMIT = 0, /* use authenticator's default */
51 FIDO_OPT_FALSE, /* explicitly set option to false */
52 FIDO_OPT_TRUE, /* explicitly set option to true */
53 } fido_opt_t;
54 .Ed
55 .Ft int
56 .Fn fido_assert_set_authdata "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len"
57 .Ft int
58 .Fn fido_assert_set_authdata_raw "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len"
59 .Ft int
60 .Fn fido_assert_set_clientdata "fido_assert_t *assert" "const unsigned char *ptr" "size_t len"
61 .Ft int
62 .Fn fido_assert_set_clientdata_hash "fido_assert_t *assert" "const unsigned char *ptr" "size_t len"
63 .Ft int
64 .Fn fido_assert_set_count "fido_assert_t *assert" "size_t n"
65 .Ft int
66 .Fn fido_assert_set_extensions "fido_assert_t *assert" "int flags"
67 .Ft int
68 .Fn fido_assert_set_hmac_salt "fido_assert_t *assert" "const unsigned char *ptr" "size_t len"
69 .Ft int
70 .Fn fido_assert_set_hmac_secret "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len"
71 .Ft int
72 .Fn fido_assert_set_up "fido_assert_t *assert" "fido_opt_t up"
73 .Ft int
74 .Fn fido_assert_set_uv "fido_assert_t *assert" "fido_opt_t uv"
75 .Ft int
76 .Fn fido_assert_set_rp "fido_assert_t *assert" "const char *id"
77 .Ft int
78 .Fn fido_assert_set_sig "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len"
79 .Ft int
80 .Fn fido_assert_set_winhello_appid "fido_assert_t *assert" "const char *id"
81 .Sh DESCRIPTION
82 The
83 .Nm
84 set of functions define the various parameters of a FIDO2
85 assertion, allowing a
86 .Fa fido_assert_t
87 type to be prepared for a subsequent call to
88 .Xr fido_dev_get_assert 3
89 or
90 .Xr fido_assert_verify 3 .
91 For the complete specification of a FIDO2 assertion and the format
92 of its constituent parts, please refer to the Web Authentication
93 (webauthn) standard.
94 .Pp
95 The
96 .Fn fido_assert_set_count
97 function sets the number of assertion statements in
98 .Fa assert
99 to
100 .Fa n .
101 .Pp
102 The
103 .Fn fido_assert_set_authdata
104 and
105 .Fn fido_assert_set_sig
106 functions set the authenticator data and signature parts of the
107 statement with index
108 .Fa idx
109 of
110 .Fa assert
111 to
112 .Fa ptr ,
113 where
114 .Fa ptr
115 points to
116 .Fa len
117 bytes.
118 A copy of
119 .Fa ptr
120 is made, and no references to the passed pointer are kept.
121 Please note that the first assertion statement of
122 .Fa assert
123 has an
124 .Fa idx
125 of
126 .Em 0 .
127 The authenticator data passed to
128 .Fn fido_assert_set_authdata
129 must be a CBOR-encoded byte string, as obtained from
130 .Fn fido_assert_authdata_ptr .
131 Alternatively, a raw binary blob may be passed to
132 .Fn fido_assert_set_authdata_raw .
133 .Pp
134 The
135 .Fn fido_assert_set_clientdata_hash
136 function sets the client data hash of
137 .Fa assert
138 to
139 .Fa ptr ,
140 where
141 .Fa ptr
142 points to
143 .Fa len
144 bytes.
145 A copy of
146 .Fa ptr
147 is made, and no references to the passed pointer are kept.
148 .Pp
149 The
150 .Fn fido_assert_set_clientdata
151 function allows an application to set the client data hash of
152 .Fa assert
153 by specifying the assertion's unhashed client data.
154 This is required by Windows Hello, which calculates the client data
155 hash internally.
156 For compatibility with Windows Hello, applications should use
157 .Fn fido_assert_set_clientdata
158 instead of
159 .Fn fido_assert_set_clientdata_hash .
160 .Pp
161 The
162 .Fn fido_assert_set_rp
163 function sets the relying party
164 .Fa id
165 of
166 .Fa assert ,
167 where
168 .Fa id
169 is a NUL-terminated UTF-8 string.
170 The content of
171 .Fa id
172 is copied, and no references to the passed pointer are kept.
173 .Pp
174 The
175 .Fn fido_assert_set_extensions
176 function sets the extensions of
177 .Fa assert
178 to the bitmask
179 .Fa flags .
180 At the moment, only the
181 .Dv FIDO_EXT_CRED_BLOB ,
182 .Dv FIDO_EXT_HMAC_SECRET ,
183 and
184 .Dv FIDO_EXT_LARGEBLOB_KEY
185 extensions are supported.
186 If
187 .Fa flags
188 is zero, the extensions of
189 .Fa assert
190 are cleared.
191 .Pp
192 The
193 .Fn fido_assert_set_hmac_salt
194 and
195 .Fn fido_assert_set_hmac_secret
196 functions set the hmac-salt and hmac-secret parts of
197 .Fa assert
198 to
199 .Fa ptr ,
200 where
201 .Fa ptr
202 points to
203 .Fa len
204 bytes.
205 A copy of
206 .Fa ptr
207 is made, and no references to the passed pointer are kept.
208 The HMAC Secret
209 .Pq hmac-secret
210 Extension is a CTAP 2.0 extension.
211 Note that the resulting hmac-secret varies according to whether
212 user verification was performed by the authenticator.
213 The
214 .Fn fido_assert_set_hmac_secret
215 function is normally only useful when writing tests.
216 .Pp
217 The
218 .Fn fido_assert_set_up
219 and
220 .Fn fido_assert_set_uv
221 functions set the
222 .Fa up
223 (user presence) and
224 .Fa uv
225 (user verification)
226 attributes of
227 .Fa assert .
228 Both are
229 .Dv FIDO_OPT_OMIT
230 by default, allowing the authenticator to use its default settings.
231 .Pp
232 The
233 .Fn fido_assert_set_winhello_appid
234 function sets the U2F application
235 .Fa id
236 .Pq Dq U2F AppID
237 of
238 .Fa assert ,
239 where
240 .Fa id
241 is a NUL-terminated UTF-8 string.
242 The content of
243 .Fa id
244 is copied, and no references to the passed pointer are kept.
245 The
246 .Fn fido_assert_set_winhello_appid
247 function is a no-op unless
248 .Fa assert
249 is passed to
250 .Xr fido_dev_get_assert 3
251 with a device
252 .Fa dev
253 on which
254 .Xr fido_dev_is_winhello 3
255 holds true.
256 In this case,
257 .Em libfido2
258 will instruct Windows Hello to try the assertion twice,
259 first with the
260 .Fa id
261 passed to
262 .Fn fido_assert_set_rp ,
263 and a second time with the
264 .Fa id
265 passed to
266 .Fn fido_assert_set_winhello_appid .
267 If the second assertion succeeds,
268 .Xr fido_assert_rp_id 3
269 will point to the U2F AppID once
270 .Xr fido_dev_get_assert 3
271 completes.
272 This mechanism exists in Windows Hello to ensure U2F backwards
273 compatibility without the application inadvertently prompting the
274 user twice.
275 Note that
276 .Fn fido_assert_set_winhello_appid
277 is not needed on platforms offering CTAP primitives, since the
278 authenticator can be silently probed for the existence of U2F
279 credentials.
280 .Pp
281 Use of the
282 .Nm
283 set of functions may happen in two distinct situations:
284 when asking a FIDO2 device to produce a series of assertion
285 statements, prior to
286 .Xr fido_dev_get_assert 3
287 (i.e, in the context of a FIDO2 client), or when verifying assertion
288 statements using
289 .Xr fido_assert_verify 3
290 (i.e, in the context of a FIDO2 server).
291 .Pp
292 For a complete description of the generation of a FIDO2 assertion
293 and its verification, please refer to the FIDO2 specification.
294 An example of how to use the
295 .Nm
296 set of functions can be found in the
297 .Pa examples/assert.c
298 file shipped with
299 .Em libfido2 .
300 .Sh RETURN VALUES
301 The
302 .Nm
303 functions return
304 .Dv FIDO_OK
305 on success.
306 The error codes returned by the
307 .Nm
308 set of functions are defined in
309 .In fido/err.h .
310 .Sh SEE ALSO
311 .Xr fido_assert_allow_cred 3 ,
312 .Xr fido_assert_verify 3 ,
313 .Xr fido_dev_get_assert 3 ,
314 .Xr fido_dev_is_winhello 3