Debian Codegraph @

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

raw
1 .\" Copyright (c) 2019-2021 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: June 28 2019 $
29 .Dt FIDO_CREDMAN_METADATA_NEW 3
30 .Os
31 .Sh NAME
32 .Nm fido_credman_metadata_new ,
33 .Nm fido_credman_rk_new ,
34 .Nm fido_credman_rp_new ,
35 .Nm fido_credman_metadata_free ,
36 .Nm fido_credman_rk_free ,
37 .Nm fido_credman_rp_free ,
38 .Nm fido_credman_rk_existing ,
39 .Nm fido_credman_rk_remaining ,
40 .Nm fido_credman_rk ,
41 .Nm fido_credman_rk_count ,
42 .Nm fido_credman_rp_id ,
43 .Nm fido_credman_rp_name ,
44 .Nm fido_credman_rp_count ,
45 .Nm fido_credman_rp_id_hash_ptr ,
46 .Nm fido_credman_rp_id_hash_len ,
47 .Nm fido_credman_get_dev_metadata ,
48 .Nm fido_credman_get_dev_rk ,
49 .Nm fido_credman_set_dev_rk ,
50 .Nm fido_credman_del_dev_rk ,
51 .Nm fido_credman_get_dev_rp
52 .Nd FIDO2 credential management API
53 .Sh SYNOPSIS
54 .In fido.h
55 .In fido/credman.h
56 .Ft fido_credman_metadata_t *
57 .Fn fido_credman_metadata_new "void"
58 .Ft fido_credman_rk_t *
59 .Fn fido_credman_rk_new "void"
60 .Ft fido_credman_rp_t *
61 .Fn fido_credman_rp_new "void"
62 .Ft void
63 .Fn fido_credman_metadata_free "fido_credman_metadata_t **metadata_p"
64 .Ft void
65 .Fn fido_credman_rk_free "fido_credman_rk_t **rk_p"
66 .Ft void
67 .Fn fido_credman_rp_free "fido_credman_rp_t **rp_p"
68 .Ft uint64_t
69 .Fn fido_credman_rk_existing "const fido_credman_metadata_t *metadata"
70 .Ft uint64_t
71 .Fn fido_credman_rk_remaining "const fido_credman_metadata_t *metadata"
72 .Ft const fido_cred_t *
73 .Fn fido_credman_rk "const fido_credman_rk_t *rk" "size_t idx"
74 .Ft size_t
75 .Fn fido_credman_rk_count "const fido_credman_rk_t *rk"
76 .Ft const char *
77 .Fn fido_credman_rp_id "const fido_credman_rp_t *rp" "size_t idx"
78 .Ft const char *
79 .Fn fido_credman_rp_name "const fido_credman_rp_t *rp" "size_t idx"
80 .Ft size_t
81 .Fn fido_credman_rp_count "const fido_credman_rp_t *rp"
82 .Ft const unsigned char *
83 .Fn fido_credman_rp_id_hash_ptr "const fido_credman_rp_t *rp" "size_t idx"
84 .Ft size_t
85 .Fn fido_credman_rp_id_hash_len "const fido_credman_rp_t *" "size_t idx"
86 .Ft int
87 .Fn fido_credman_get_dev_metadata "fido_dev_t *dev" "fido_credman_metadata_t *metadata" "const char *pin"
88 .Ft int
89 .Fn fido_credman_get_dev_rk "fido_dev_t *dev" "const char *rp_id" "fido_credman_rk_t *rk" "const char *pin"
90 .Ft int
91 .Fn fido_credman_set_dev_rk "fido_dev_t *dev" "fido_cred_t *cred" "const char *pin"
92 .Ft int
93 .Fn fido_credman_del_dev_rk "fido_dev_t *dev" "const unsigned char *cred_id" "size_t cred_id_len" "const char *pin"
94 .Ft int
95 .Fn fido_credman_get_dev_rp "fido_dev_t *dev" "fido_credman_rp_t *rp" "const char *pin"
96 .Sh DESCRIPTION
97 The credential management API of
98 .Em libfido2
99 allows resident credentials on a FIDO2 authenticator to be listed,
100 inspected, modified, and removed.
101 Please note that not all FIDO2 authenticators support credential
102 management.
103 To obtain information on what an authenticator supports, please
104 refer to
105 .Xr fido_cbor_info_new 3 .
106 .Pp
107 The
108 .Vt fido_credman_metadata_t
109 type abstracts credential management metadata.
110 .Pp
111 The
112 .Fn fido_credman_metadata_new
113 function returns a pointer to a newly allocated, empty
114 .Vt fido_credman_metadata_t
115 type.
116 If memory cannot be allocated, NULL is returned.
117 .Pp
118 The
119 .Fn fido_credman_metadata_free
120 function releases the memory backing
121 .Fa *metadata_p ,
122 where
123 .Fa *metadata_p
124 must have been previously allocated by
125 .Fn fido_credman_metadata_new .
126 On return,
127 .Fa *metadata_p
128 is set to NULL.
129 Either
130 .Fa metadata_p
131 or
132 .Fa *metadata_p
133 may be NULL, in which case
134 .Fn fido_credman_metadata_free
135 is a NOP.
136 .Pp
137 The
138 .Fn fido_credman_get_dev_metadata
139 function populates
140 .Fa metadata
141 with information retrieved from
142 .Fa dev .
143 A valid
144 .Fa pin
145 must be provided.
146 .Pp
147 The
148 .Fn fido_credman_rk_existing
149 function inspects
150 .Fa metadata
151 and returns the number of resident credentials on the
152 authenticator.
153 The
154 .Fn fido_credman_rk_remaining
155 function inspects
156 .Fa metadata
157 and returns the estimated number of resident credentials that can
158 be created on the authenticator.
159 .Pp
160 The
161 .Vt fido_credman_rk_t
162 type abstracts the set of resident credentials belonging to a
163 given relying party.
164 .Pp
165 The
166 .Fn fido_credman_rk_new
167 function returns a pointer to a newly allocated, empty
168 .Vt fido_credman_rk_t
169 type.
170 If memory cannot be allocated, NULL is returned.
171 .Pp
172 The
173 .Fn fido_credman_rk_free
174 function releases the memory backing
175 .Fa *rk_p ,
176 where
177 .Fa *rk_p
178 must have been previously allocated by
179 .Fn fido_credman_rk_new .
180 On return,
181 .Fa *rk_p
182 is set to NULL.
183 Either
184 .Fa rk_p
185 or
186 .Fa *rk_p
187 may be NULL, in which case
188 .Fn fido_credman_rk_free
189 is a NOP.
190 .Pp
191 The
192 .Fn fido_credman_get_dev_rk
193 function populates
194 .Fa rk
195 with the set of resident credentials belonging to
196 .Fa rp_id
197 in
198 .Fa dev .
199 A valid
200 .Fa pin
201 must be provided.
202 .Pp
203 The
204 .Fn fido_credman_rk_count
205 function returns the number of resident credentials in
206 .Fa rk .
207 The
208 .Fn fido_credman_rk
209 function returns a pointer to the credential at index
210 .Fa idx
211 in
212 .Fa rk .
213 Please note that the first credential in
214 .Fa rk
215 has an
216 .Fa idx
217 (index) value of 0.
218 .Pp
219 The
220 .Fn fido_credman_set_dev_rk
221 function updates the credential pointed to by
222 .Fa cred
223 in
224 .Fa dev .
225 The credential id and user id attributes of
226 .Fa cred
227 must be set.
228 See
229 .Xr fido_cred_set_id 3
230 and
231 .Xr fido_cred_set_user 3
232 for details.
233 Only a credential's user attributes (name, display name)
234 may be updated at this time.
235 .Pp
236 The
237 .Fn fido_credman_del_dev_rk
238 function deletes the resident credential identified by
239 .Fa cred_id
240 from
241 .Fa dev ,
242 where
243 .Fa cred_id
244 points to
245 .Fa cred_id_len
246 bytes.
247 A valid
248 .Fa pin
249 must be provided.
250 .Pp
251 The
252 .Vt fido_credman_rp_t
253 type abstracts information about a relying party.
254 .Pp
255 The
256 .Fn fido_credman_rp_new
257 function returns a pointer to a newly allocated, empty
258 .Vt fido_credman_rp_t
259 type.
260 If memory cannot be allocated, NULL is returned.
261 .Pp
262 The
263 .Fn fido_credman_rp_free
264 function releases the memory backing
265 .Fa *rp_p ,
266 where
267 .Fa *rp_p
268 must have been previously allocated by
269 .Fn fido_credman_rp_new .
270 On return,
271 .Fa *rp_p
272 is set to NULL.
273 Either
274 .Fa rp_p
275 or
276 .Fa *rp_p
277 may be NULL, in which case
278 .Fn fido_credman_rp_free
279 is a NOP.
280 .Pp
281 The
282 .Fn fido_credman_get_dev_rp
283 function populates
284 .Fa rp
285 with information about relying parties with resident credentials
286 in
287 .Fa dev .
288 A valid
289 .Fa pin
290 must be provided.
291 .Pp
292 The
293 .Fn fido_credman_rp_count
294 function returns the number of relying parties in
295 .Fa rp .
296 .Pp
297 The
298 .Fn fido_credman_rp_id
299 and
300 .Fn fido_credman_rp_name
301 functions return pointers to the id and name of relying party
302 .Fa idx
303 in
304 .Fa rp .
305 If not NULL, the values returned by these functions point to
306 NUL-terminated UTF-8 strings.
307 Please note that the first relying party in
308 .Fa rp
309 has an
310 .Fa idx
311 (index) value of 0.
312 .Pp
313 The
314 .Fn fido_credman_rp_id_hash_ptr
315 function returns a pointer to the hashed id of relying party
316 .Fa idx
317 in
318 .Fa rp .
319 The corresponding length can be obtained by
320 .Fn fido_credman_rp_id_hash_len .
321 Please note that the first relying party in
322 .Fa rp
323 has an
324 .Fa idx
325 (index) value of 0.
326 .Sh RETURN VALUES
327 The
328 .Fn fido_credman_get_dev_metadata ,
329 .Fn fido_credman_get_dev_rk ,
330 .Fn fido_credman_set_dev_rk ,
331 .Fn fido_credman_del_dev_rk ,
332 and
333 .Fn fido_credman_get_dev_rp
334 functions return
335 .Dv FIDO_OK
336 on success.
337 On error, a different error code defined in
338 .In fido/err.h
339 is returned.
340 Functions returning pointers are not guaranteed to succeed, and
341 should have their return values checked for NULL.
342 .Sh SEE ALSO
343 .Xr fido_cbor_info_new 3 ,
344 .Xr fido_cred_new 3 ,
345 .Xr fido_dev_supports_credman 3
346 .Sh CAVEATS
347 Resident credentials are called
348 .Dq discoverable credentials
349 in CTAP 2.1.