Debian Codegraph @

extra/libfido2/libfido2-1.15.0/man/fido_cred_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: July 15 2022 $
29 .Dt FIDO_CRED_SET_AUTHDATA 3
30 .Os
31 .Sh NAME
32 .Nm fido_cred_set_authdata ,
33 .Nm fido_cred_set_authdata_raw ,
34 .Nm fido_cred_set_attstmt ,
35 .Nm fido_cred_set_attobj ,
36 .Nm fido_cred_set_x509 ,
37 .Nm fido_cred_set_sig ,
38 .Nm fido_cred_set_id ,
39 .Nm fido_cred_set_clientdata ,
40 .Nm fido_cred_set_clientdata_hash ,
41 .Nm fido_cred_set_rp ,
42 .Nm fido_cred_set_user ,
43 .Nm fido_cred_set_extensions ,
44 .Nm fido_cred_set_blob ,
45 .Nm fido_cred_set_pin_minlen ,
46 .Nm fido_cred_set_prot ,
47 .Nm fido_cred_set_rk ,
48 .Nm fido_cred_set_uv ,
49 .Nm fido_cred_set_fmt ,
50 .Nm fido_cred_set_type
51 .Nd set parameters of a FIDO2 credential
52 .Sh SYNOPSIS
53 .In fido.h
54 .Bd -literal
55 typedef enum {
56 FIDO_OPT_OMIT = 0, /* use authenticator's default */
57 FIDO_OPT_FALSE, /* explicitly set option to false */
58 FIDO_OPT_TRUE, /* explicitly set option to true */
59 } fido_opt_t;
60 .Ed
61 .Ft int
62 .Fn fido_cred_set_authdata "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
63 .Ft int
64 .Fn fido_cred_set_authdata_raw "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
65 .Ft int
66 .Fn fido_cred_set_attstmt "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
67 .Ft int
68 .Fn fido_cred_set_attobj "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
69 .Ft int
70 .Fn fido_cred_set_x509 "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
71 .Ft int
72 .Fn fido_cred_set_sig "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
73 .Ft int
74 .Fn fido_cred_set_id "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
75 .Ft int
76 .Fn fido_cred_set_clientdata "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
77 .Ft int
78 .Fn fido_cred_set_clientdata_hash "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
79 .Ft int
80 .Fn fido_cred_set_rp "fido_cred_t *cred" "const char *id" "const char *name"
81 .Ft int
82 .Fn fido_cred_set_user "fido_cred_t *cred" "const unsigned char *user_id" "size_t user_id_len" "const char *name" "const char *display_name" "const char *icon"
83 .Ft int
84 .Fn fido_cred_set_extensions "fido_cred_t *cred" "int flags"
85 .Ft int
86 .Fn fido_cred_set_blob "fido_cred_t *cred" "const unsigned char *ptr" "size_t len"
87 .Ft int
88 .Fn fido_cred_set_pin_minlen "fido_cred_t *cred" "size_t len"
89 .Ft int
90 .Fn fido_cred_set_prot "fido_cred_t *cred" "int prot"
91 .Ft int
92 .Fn fido_cred_set_rk "fido_cred_t *cred" "fido_opt_t rk"
93 .Ft int
94 .Fn fido_cred_set_uv "fido_cred_t *cred" "fido_opt_t uv"
95 .Ft int
96 .Fn fido_cred_set_fmt "fido_cred_t *cred" "const char *ptr"
97 .Ft int
98 .Fn fido_cred_set_type "fido_cred_t *cred" "int cose_alg"
99 .Sh DESCRIPTION
100 The
101 .Nm
102 set of functions define the various parameters of a FIDO2
103 credential, allowing a
104 .Fa fido_cred_t
105 type to be prepared for a subsequent call to
106 .Xr fido_dev_make_cred 3
107 or
108 .Xr fido_cred_verify 3 .
109 For the complete specification of a FIDO2 credential and the format
110 of its constituent parts, please refer to the Web Authentication
111 (webauthn) standard.
112 .Pp
113 The
114 .Fn fido_cred_set_authdata ,
115 .Fn fido_cred_set_attstmt ,
116 .Fn fido_cred_set_attobj ,
117 .Fn fido_cred_set_x509 ,
118 .Fn fido_cred_set_sig ,
119 .Fn fido_cred_set_id ,
120 and
121 .Fn fido_cred_set_clientdata_hash
122 functions set the authenticator data, attestation statement,
123 attestation object, attestation certificate, attestation signature,
124 id, and client data hash parts of
125 .Fa cred
126 to
127 .Fa ptr ,
128 where
129 .Fa ptr
130 points to
131 .Fa len
132 bytes.
133 A copy of
134 .Fa ptr
135 is made, and no references to the passed pointer are kept.
136 .Pp
137 The authenticator data passed to
138 .Fn fido_cred_set_authdata
139 must be a CBOR-encoded byte string, as obtained from
140 .Fn fido_cred_authdata_ptr .
141 Alternatively, a raw binary blob may be passed to
142 .Fn fido_cred_set_authdata_raw .
143 An application calling
144 .Fn fido_cred_set_authdata
145 does not need to call
146 .Fn fido_cred_set_id .
147 The latter is meant to be used in contexts where the
148 credential's authenticator data is not available.
149 .Pp
150 The attestation statement passed to
151 .Fn fido_cred_set_attstmt
152 must be a CBOR-encoded map, as obtained from
153 .Fn fido_cred_attstmt_ptr .
154 An application calling
155 .Fn fido_cred_set_attstmt
156 does not need to call
157 .Fn fido_cred_set_x509
158 or
159 .Fn fido_cred_set_sig .
160 The latter two are meant to be used in contexts where the
161 credential's complete attestation statement is not available or
162 required.
163 .Pp
164 The attestation object passed to
165 .Fn fido_cred_set_attobj
166 must be a CBOR-encoded map containing
167 .Dq authData ,
168 .Dq fmt ,
169 and
170 .Dq attStmt .
171 An application calling
172 .Fn fido_cred_set_attobj
173 does not need to call
174 .Fn fido_cred_set_fmt ,
175 .Fn fido_cred_set_attstmt ,
176 .Fn fido_cred_set_authdata ,
177 or
178 .Fn fido_cred_set_authdata_raw .
179 .Fn fido_cred_set_attobj
180 may be useful in applications interfacing with the WebAuthn API,
181 removing the need to first parse the attestation object to verify the
182 credential.
183 .Pp
184 The
185 .Fn fido_cred_set_clientdata
186 function allows an application to set the client data hash of
187 .Fa cred
188 by specifying the credential's unhashed client data.
189 This is required by Windows Hello, which calculates the client data
190 hash internally.
191 For compatibility with Windows Hello, applications should use
192 .Fn fido_cred_set_clientdata
193 instead of
194 .Fn fido_cred_set_clientdata_hash .
195 .Pp
196 The
197 .Fn fido_cred_set_rp
198 function sets the relying party
199 .Fa id
200 and
201 .Fa name
202 parameters of
203 .Fa cred ,
204 where
205 .Fa id
206 and
207 .Fa name
208 are NUL-terminated UTF-8 strings.
209 The contents of
210 .Fa id
211 and
212 .Fa name
213 are copied, and no references to the passed pointers are kept.
214 .Pp
215 The
216 .Fn fido_cred_set_user
217 function sets the user attributes of
218 .Fa cred ,
219 where
220 .Fa user_id
221 points to
222 .Fa user_id_len
223 bytes and
224 .Fa name ,
225 .Fa display_name ,
226 and
227 .Fa icon
228 are NUL-terminated UTF-8 strings.
229 The contents of
230 .Fa user_id ,
231 .Fa name ,
232 .Fa display_name ,
233 and
234 .Fa icon
235 are copied, and no references to the passed pointers are kept.
236 Previously set user attributes are flushed.
237 The
238 .Fa user_id ,
239 .Fa name ,
240 .Fa display_name ,
241 and
242 .Fa icon
243 parameters may be NULL.
244 .Pp
245 The
246 .Fn fido_cred_set_extensions
247 function sets the extensions of
248 .Fa cred
249 to the bitmask
250 .Fa flags .
251 At the moment, only the
252 .Dv FIDO_EXT_CRED_BLOB ,
253 .Dv FIDO_EXT_CRED_PROTECT ,
254 .Dv FIDO_EXT_HMAC_SECRET ,
255 .Dv FIDO_EXT_MINPINLEN ,
256 and
257 .Dv FIDO_EXT_LARGEBLOB_KEY
258 extensions are supported.
259 If
260 .Fa flags
261 is zero, the extensions of
262 .Fa cred
263 are cleared.
264 .Pp
265 The
266 .Fn fido_cred_set_blob
267 function sets the
268 .Dq credBlob
269 to be stored with
270 .Fa cred
271 to the data pointed to by
272 .Fa ptr ,
273 which must be
274 .Fa len
275 bytes long.
276 .Pp
277 The
278 .Fn fido_cred_set_pin_minlen
279 function enables the CTAP 2.1
280 .Dv FIDO_EXT_MINPINLEN
281 extension on
282 .Fa cred
283 and sets the expected minimum PIN length of
284 .Fa cred
285 to
286 .Fa len ,
287 where
288 .Fa len
289 is greater than zero.
290 If
291 .Fa len
292 is zero, the
293 .Dv FIDO_EXT_MINPINLEN
294 extension is disabled on
295 .Fa cred .
296 .Pp
297 The
298 .Fn fido_cred_set_prot
299 function enables the CTAP 2.1
300 .Dv FIDO_EXT_CRED_PROTECT
301 extension on
302 .Fa cred
303 and sets the protection of
304 .Fa cred
305 to the scalar
306 .Fa prot .
307 At the moment, only the
308 .Dv FIDO_CRED_PROT_UV_OPTIONAL ,
309 .Dv FIDO_CRED_PROT_UV_OPTIONAL_WITH_ID ,
310 and
311 .Dv FIDO_CRED_PROT_UV_REQUIRED
312 protections are supported.
313 If
314 .Fa prot
315 is zero, the protection of
316 .Fa cred
317 is cleared.
318 .Pp
319 The
320 .Fn fido_cred_set_rk
321 and
322 .Fn fido_cred_set_uv
323 functions set the
324 .Em rk
325 .Pq resident/discoverable key
326 and
327 .Em uv
328 .Pq user verification
329 attributes of
330 .Fa cred .
331 Both are
332 .Dv FIDO_OPT_OMIT
333 by default, allowing the authenticator to use its default settings.
334 .Pp
335 The
336 .Fn fido_cred_set_fmt
337 function sets the attestation statement format identifier of
338 .Fa cred
339 to
340 .Fa fmt ,
341 where
342 .Fa fmt
343 must be
344 .Vt "packed"
345 .Pq the format used in FIDO2 ,
346 .Vt "fido-u2f"
347 .Pq the format used in U2F ,
348 .Vt "tpm"
349 .Pq the format used by TPM-based authenticators ,
350 or
351 .Vt "none" .
352 A copy of
353 .Fa fmt
354 is made, and no references to the passed pointer are kept.
355 Note that not all authenticators support FIDO2 and therefore may only
356 be able to generate
357 .Vt fido-u2f
358 attestation statements.
359 .Pp
360 The
361 .Fn fido_cred_set_type
362 function sets the type of
363 .Fa cred to
364 .Fa cose_alg ,
365 where
366 .Fa cose_alg
367 is
368 .Dv COSE_ES256 ,
369 .Dv COSE_ES384 ,
370 .Dv COSE_RS256 ,
371 or
372 .Dv COSE_EDDSA .
373 The type of a credential may only be set once.
374 Note that not all authenticators support COSE_RS256, COSE_ES384, or
375 COSE_EDDSA.
376 .Pp
377 Use of the
378 .Nm
379 set of functions may happen in two distinct situations:
380 when generating a new credential on a FIDO2 device, prior to
381 .Xr fido_dev_make_cred 3
382 (i.e, in the context of a FIDO2 client), or when validating
383 a generated credential using
384 .Xr fido_cred_verify 3
385 (i.e, in the context of a FIDO2 server).
386 .Pp
387 For a complete description of the generation of a FIDO2 credential
388 and its verification, please refer to the FIDO2 specification.
389 A concrete utilisation example of the
390 .Nm
391 set of functions can be found in the
392 .Pa cred.c
393 example shipped with
394 .Em libfido2 .
395 .Sh RETURN VALUES
396 The error codes returned by the
397 .Nm
398 set of functions are defined in
399 .In fido/err.h .
400 On success,
401 .Dv FIDO_OK
402 is returned.
403 .Sh SEE ALSO
404 .Xr fido_cred_exclude 3 ,
405 .Xr fido_cred_verify 3 ,
406 .Xr fido_dev_make_cred 3