Debian Codegraph @

extra/libfido2/libfido2-1.15.0/man/fido_cbor_info_new.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 22 2022 $
29 .Dt FIDO_CBOR_INFO_NEW 3
30 .Os
31 .Sh NAME
32 .Nm fido_cbor_info_new ,
33 .Nm fido_cbor_info_free ,
34 .Nm fido_dev_get_cbor_info ,
35 .Nm fido_cbor_info_aaguid_ptr ,
36 .Nm fido_cbor_info_extensions_ptr ,
37 .Nm fido_cbor_info_protocols_ptr ,
38 .Nm fido_cbor_info_transports_ptr ,
39 .Nm fido_cbor_info_versions_ptr ,
40 .Nm fido_cbor_info_options_name_ptr ,
41 .Nm fido_cbor_info_options_value_ptr ,
42 .Nm fido_cbor_info_algorithm_type ,
43 .Nm fido_cbor_info_algorithm_cose ,
44 .Nm fido_cbor_info_algorithm_count ,
45 .Nm fido_cbor_info_certs_name_ptr ,
46 .Nm fido_cbor_info_certs_value_ptr ,
47 .Nm fido_cbor_info_certs_len ,
48 .Nm fido_cbor_info_aaguid_len ,
49 .Nm fido_cbor_info_extensions_len ,
50 .Nm fido_cbor_info_protocols_len ,
51 .Nm fido_cbor_info_transports_len ,
52 .Nm fido_cbor_info_versions_len ,
53 .Nm fido_cbor_info_options_len ,
54 .Nm fido_cbor_info_maxmsgsiz ,
55 .Nm fido_cbor_info_maxcredbloblen ,
56 .Nm fido_cbor_info_maxcredcntlst ,
57 .Nm fido_cbor_info_maxcredidlen ,
58 .Nm fido_cbor_info_maxlargeblob ,
59 .Nm fido_cbor_info_maxrpid_minpinlen ,
60 .Nm fido_cbor_info_minpinlen ,
61 .Nm fido_cbor_info_fwversion ,
62 .Nm fido_cbor_info_uv_attempts ,
63 .Nm fido_cbor_info_uv_modality ,
64 .Nm fido_cbor_info_rk_remaining ,
65 .Nm fido_cbor_info_new_pin_required
66 .Nd FIDO2 CBOR Info API
67 .Sh SYNOPSIS
68 .In fido.h
69 .Ft fido_cbor_info_t *
70 .Fn fido_cbor_info_new "void"
71 .Ft void
72 .Fn fido_cbor_info_free "fido_cbor_info_t **ci_p"
73 .Ft int
74 .Fn fido_dev_get_cbor_info "fido_dev_t *dev" "fido_cbor_info_t *ci"
75 .Ft const unsigned char *
76 .Fn fido_cbor_info_aaguid_ptr "const fido_cbor_info_t *ci"
77 .Ft char **
78 .Fn fido_cbor_info_extensions_ptr "const fido_cbor_info_t *ci"
79 .Ft const uint8_t *
80 .Fn fido_cbor_info_protocols_ptr "const fido_cbor_info_t *ci"
81 .Ft char **
82 .Fn fido_cbor_info_transports_ptr "const fido_cbor_info_t *ci"
83 .Ft char **
84 .Fn fido_cbor_info_versions_ptr "const fido_cbor_info_t *ci"
85 .Ft char **
86 .Fn fido_cbor_info_options_name_ptr "const fido_cbor_info_t *ci"
87 .Ft const bool *
88 .Fn fido_cbor_info_options_value_ptr "const fido_cbor_info_t *ci"
89 .Ft const char *
90 .Fn fido_cbor_info_algorithm_type "const fido_cbor_info_t *ci" "size_t idx"
91 .Ft int
92 .Fn fido_cbor_info_algorithm_cose "const fido_cbor_info_t *ci" "size_t idx"
93 .Ft size_t
94 .Fn fido_cbor_info_algorithm_count "const fido_cbor_info_t *ci"
95 .Ft char **
96 .Fn fido_cbor_info_certs_name_ptr "const fido_cbor_info_t *ci"
97 .Ft const uint64_t *
98 .Fn fido_cbor_info_certs_value_ptr "const fido_cbor_info_t *ci"
99 .Ft size_t
100 .Fn fido_cbor_info_certs_len "const fido_cbor_info_t *ci"
101 .Ft size_t
102 .Fn fido_cbor_info_aaguid_len "const fido_cbor_info_t *ci"
103 .Ft size_t
104 .Fn fido_cbor_info_extensions_len "const fido_cbor_info_t *ci"
105 .Ft size_t
106 .Fn fido_cbor_info_protocols_len "const fido_cbor_info_t *ci"
107 .Ft size_t
108 .Fn fido_cbor_info_transports_len "const fido_cbor_info_t *ci"
109 .Ft size_t
110 .Fn fido_cbor_info_versions_len "const fido_cbor_info_t *ci"
111 .Ft size_t
112 .Fn fido_cbor_info_options_len "const fido_cbor_info_t *ci"
113 .Ft uint64_t
114 .Fn fido_cbor_info_maxmsgsiz "const fido_cbor_info_t *ci"
115 .Ft uint64_t
116 .Fn fido_cbor_info_maxcredbloblen "const fido_cbor_info_t *ci"
117 .Ft uint64_t
118 .Fn fido_cbor_info_maxcredcntlst "const fido_cbor_info_t *ci"
119 .Ft uint64_t
120 .Fn fido_cbor_info_maxcredidlen "const fido_cbor_info_t *ci"
121 .Ft uint64_t
122 .Fn fido_cbor_info_maxlargeblob "const fido_cbor_info_t *ci"
123 .Ft uint64_t
124 .Fn fido_cbor_info_maxrpid_minpinlen "const fido_cbor_info_t *ci"
125 .Ft uint64_t
126 .Fn fido_cbor_info_minpinlen "const fido_cbor_info_t *ci"
127 .Ft uint64_t
128 .Fn fido_cbor_info_fwversion "const fido_cbor_info_t *ci"
129 .Ft uint64_t
130 .Fn fido_cbor_info_uv_attempts "const fido_cbor_info_t *ci"
131 .Ft uint64_t
132 .Fn fido_cbor_info_uv_modality "const fido_cbor_info_t *ci"
133 .Ft int64_t
134 .Fn fido_cbor_info_rk_remaining "const fido_cbor_info_t *ci"
135 .Ft bool
136 .Fn fido_cbor_info_new_pin_required "const fido_cbor_info_t *ci"
137 .Sh DESCRIPTION
138 The
139 .Fn fido_cbor_info_new
140 function returns a pointer to a newly allocated, empty
141 .Vt fido_cbor_info_t
142 type.
143 If memory cannot be allocated, NULL is returned.
144 .Pp
145 The
146 .Fn fido_cbor_info_free
147 function releases the memory backing
148 .Fa *ci_p ,
149 where
150 .Fa *ci_p
151 must have been previously allocated by
152 .Fn fido_cbor_info_new .
153 On return,
154 .Fa *ci_p
155 is set to NULL.
156 Either
157 .Fa ci_p
158 or
159 .Fa *ci_p
160 may be NULL, in which case
161 .Fn fido_cbor_info_free
162 is a NOP.
163 .Pp
164 The
165 .Fn fido_dev_get_cbor_info
166 function transmits a
167 .Dv CTAP_CBOR_GETINFO
168 command to
169 .Fa dev
170 and fills
171 .Fa ci
172 with attributes retrieved from the command's response.
173 The
174 .Fn fido_dev_get_cbor_info
175 function may block.
176 .Pp
177 The
178 .Fn fido_cbor_info_aaguid_ptr ,
179 .Fn fido_cbor_info_extensions_ptr ,
180 .Fn fido_cbor_info_protocols_ptr ,
181 .Fn fido_cbor_info_transports_ptr ,
182 and
183 .Fn fido_cbor_info_versions_ptr
184 functions return pointers to the authenticator attestation GUID,
185 supported extensions, PIN protocol, transports, and CTAP version
186 strings of
187 .Fa ci .
188 The corresponding length of a given attribute can be
189 obtained by
190 .Fn fido_cbor_info_aaguid_len ,
191 .Fn fido_cbor_info_extensions_len ,
192 .Fn fido_cbor_info_protocols_len ,
193 .Fn fido_cbor_info_transports_len ,
194 or
195 .Fn fido_cbor_info_versions_len .
196 .Pp
197 The
198 .Fn fido_cbor_info_options_name_ptr
199 and
200 .Fn fido_cbor_info_options_value_ptr
201 functions return pointers to the array of option names and their
202 respective values
203 in
204 .Fa ci .
205 The length of the options array is returned by
206 .Fn fido_cbor_info_options_len .
207 .Pp
208 The
209 .Fn fido_cbor_info_algorithm_count
210 function returns the number of supported algorithms in
211 .Fa ci .
212 The
213 .Fn fido_cbor_info_algorithm_cose
214 function returns the COSE identifier of algorithm
215 .Fa idx
216 in
217 .Fa ci ,
218 or 0 if the COSE identifier is unknown or unset.
219 The
220 .Fn fido_cbor_info_algorithm_type
221 function returns the type of algorithm
222 .Fa idx
223 in
224 .Fa ci ,
225 or NULL if the type is unset.
226 Please note that the first algorithm in
227 .Fa ci
228 has an
229 .Fa idx
230 (index) value of 0.
231 .Pp
232 The
233 .Fn fido_cbor_info_certs_name_ptr
234 and
235 .Fn fido_cbor_info_certs_value_ptr
236 functions return pointers to the array of certification names and their
237 respective values
238 in
239 .Fa ci .
240 The length of the certifications array is returned by
241 .Fn fido_cbor_info_certs_len .
242 .Pp
243 The
244 .Fn fido_cbor_info_maxmsgsiz
245 function returns the maximum message size attribute of
246 .Fa ci .
247 .Pp
248 The
249 .Fn fido_cbor_info_maxcredbloblen
250 function returns the maximum
251 .Dq credBlob
252 length in bytes supported by the authenticator as reported in
253 .Fa ci .
254 .Pp
255 The
256 .Fn fido_cbor_info_maxcredcntlst
257 function returns the maximum supported number of credentials in
258 a single credential ID list as reported in
259 .Fa ci .
260 .Pp
261 The
262 .Fn fido_cbor_info_maxcredidlen
263 function returns the maximum supported length of a credential ID
264 as reported in
265 .Fa ci .
266 .Pp
267 The
268 .Fn fido_cbor_info_maxrpid_minpinlen
269 function returns the maximum number of RP IDs that may be passed to
270 .Xr fido_dev_set_pin_minlen_rpid 3 ,
271 as reported in
272 .Fa ci .
273 The minimum PIN length attribute is a CTAP 2.1 addition.
274 If the attribute is not advertised by the authenticator, the
275 .Fn fido_cbor_info_maxrpid_minpinlen
276 function returns zero.
277 .Pp
278 The
279 .Fn fido_cbor_info_maxlargeblob
280 function returns the maximum length in bytes of an authenticator's
281 serialized largeBlob array as reported in
282 .Fa ci .
283 .Pp
284 The
285 .Fn fido_cbor_info_minpinlen
286 function returns the minimum PIN length enforced by the
287 authenticator as reported in
288 .Fa ci .
289 The minimum PIN length attribute is a CTAP 2.1 addition.
290 If the attribute is not advertised by the authenticator, the
291 .Fn fido_cbor_info_minpinlen
292 function returns zero.
293 .Pp
294 The
295 .Fn fido_cbor_info_fwversion
296 function returns the firmware version attribute of
297 .Fa ci .
298 .Pp
299 The
300 .Fn fido_cbor_info_uv_attempts
301 function returns the number of UV attempts that the platform may
302 attempt before falling back to PIN authentication.
303 If 1, then all
304 .Xr fido_dev_get_uv_retry_count 3
305 retries are handled internally by the authenticator and the
306 platform may only attempt non-PIN UV once.
307 The UV attempts attribute is a CTAP 2.1 addition.
308 If the attribute is not advertised by the authenticator,
309 the
310 .Fn fido_cbor_info_uv_attempts
311 function returns zero.
312 .Pp
313 The
314 .Fn fido_cbor_info_uv_modality
315 function returns a bitmask representing different UV modes
316 supported by the authenticator, as defined in the FIDO Registry of
317 Predefined Values and reported in
318 .Fa ci .
319 See the
320 .Em FIDO_UV_MODE_*
321 definitions in
322 .In fido/param.h
323 for the set of values defined by libfido2 and a brief description
324 of each.
325 The UV modality attribute is a CTAP 2.1 addition.
326 If the attribute is not advertised by the authenticator, the
327 .Fn fido_cbor_info_uv_modality
328 function returns zero.
329 .Pp
330 The
331 .Fn fido_cbor_info_rk_remaining
332 function returns the estimated number of additional
333 resident/discoverable credentials that can be stored on the
334 authenticator as reported in
335 .Fa ci .
336 The estimated number of remaining resident credentials is a
337 CTAP 2.1 addition.
338 If the attribute is not advertised by the authenticator, the
339 .Fn fido_cbor_info_rk_remaining
340 function returns -1.
341 .Pp
342 The
343 .Fn fido_cbor_info_new_pin_required
344 function returns whether a new PIN is required by the authenticator
345 as reported in
346 .Fa ci .
347 If
348 .Fn fido_cbor_info_new_pin_required
349 returns true, operations requiring PIN authentication will fail
350 until a new PIN is set on the authenticator.
351 The
352 .Xr fido_dev_set_pin 3
353 function can be used to set a new PIN.
354 .Pp
355 A complete example of how to use these functions can be found in the
356 .Pa example/info.c
357 file shipped with
358 .Em libfido2 .
359 .Sh RETURN VALUES
360 The
361 .Fn fido_cbor_info_aaguid_ptr ,
362 .Fn fido_cbor_info_extensions_ptr ,
363 .Fn fido_cbor_info_protocols_ptr ,
364 .Fn fido_cbor_info_transports_ptr ,
365 .Fn fido_cbor_info_versions_ptr ,
366 .Fn fido_cbor_info_options_name_ptr ,
367 and
368 .Fn fido_cbor_info_options_value_ptr
369 functions return NULL if the respective field in
370 .Fa ci
371 is absent.
372 If not NULL, returned pointers are guaranteed to exist until any
373 API function that takes
374 .Fa ci
375 without the
376 .Em const
377 qualifier is invoked.
378 .Sh SEE ALSO
379 .Xr fido_dev_get_uv_retry_count 3 ,
380 .Xr fido_dev_open 3 ,
381 .Xr fido_dev_set_pin 3 ,
382 .Xr fido_dev_set_pin_minlen_rpid 3
383 .Rs
384 .%D 2021-05-25
385 .%O Review Draft, Version 2.2
386 .%Q FIDO Alliance
387 .%R FIDO Registry of Predefined Values
388 .%U https://fidoalliance.org/specs/common-specs/fido-registry-v2.2-rd-20210525.html
389 .Re