Debian Codegraph @

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

raw
1 .\" Copyright (c) 2018-2024 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: May 23 2018 $
29 .Dt FIDO_CRED_NEW 3
30 .Os
31 .Sh NAME
32 .Nm fido_cred_new ,
33 .Nm fido_cred_free ,
34 .Nm fido_cred_pin_minlen ,
35 .Nm fido_cred_prot ,
36 .Nm fido_cred_fmt ,
37 .Nm fido_cred_rp_id ,
38 .Nm fido_cred_rp_name ,
39 .Nm fido_cred_user_name ,
40 .Nm fido_cred_display_name ,
41 .Nm fido_cred_authdata_ptr ,
42 .Nm fido_cred_authdata_raw_ptr ,
43 .Nm fido_cred_clientdata_hash_ptr ,
44 .Nm fido_cred_id_ptr ,
45 .Nm fido_cred_aaguid_ptr ,
46 .Nm fido_cred_largeblob_key_ptr ,
47 .Nm fido_cred_pubkey_ptr ,
48 .Nm fido_cred_sig_ptr ,
49 .Nm fido_cred_user_id_ptr ,
50 .Nm fido_cred_x5c_list_count ,
51 .Nm fido_cred_x5c_list_ptr ,
52 .Nm fido_cred_x5c_ptr ,
53 .Nm fido_cred_attstmt_ptr ,
54 .Nm fido_cred_authdata_len ,
55 .Nm fido_cred_authdata_raw_len ,
56 .Nm fido_cred_clientdata_hash_len ,
57 .Nm fido_cred_id_len ,
58 .Nm fido_cred_aaguid_len ,
59 .Nm fido_cred_largeblob_key_len ,
60 .Nm fido_cred_pubkey_len ,
61 .Nm fido_cred_sig_len ,
62 .Nm fido_cred_user_id_len ,
63 .Nm fido_cred_x5c_list_len ,
64 .Nm fido_cred_x5c_len ,
65 .Nm fido_cred_attstmt_len ,
66 .Nm fido_cred_type ,
67 .Nm fido_cred_flags ,
68 .Nm fido_cred_sigcount
69 .Nd FIDO2 credential API
70 .Sh SYNOPSIS
71 .In fido.h
72 .Ft fido_cred_t *
73 .Fn fido_cred_new "void"
74 .Ft void
75 .Fn fido_cred_free "fido_cred_t **cred_p"
76 .Ft size_t
77 .Fn fido_cred_pin_minlen "const fido_cred_t *cred"
78 .Ft int
79 .Fn fido_cred_prot "const fido_cred_t *cred"
80 .Ft const char *
81 .Fn fido_cred_fmt "const fido_cred_t *cred"
82 .Ft const char *
83 .Fn fido_cred_rp_id "const fido_cred_t *cred"
84 .Ft const char *
85 .Fn fido_cred_rp_name "const fido_cred_t *cred"
86 .Ft const char *
87 .Fn fido_cred_user_name "const fido_cred_t *cred"
88 .Ft const char *
89 .Fn fido_cred_display_name "const fido_cred_t *cred"
90 .Ft const unsigned char *
91 .Fn fido_cred_authdata_ptr "const fido_cred_t *cred"
92 .Ft const unsigned char *
93 .Fn fido_cred_authdata_raw_ptr "const fido_cred_t *cred"
94 .Ft const unsigned char *
95 .Fn fido_cred_clientdata_hash_ptr "const fido_cred_t *cred"
96 .Ft const unsigned char *
97 .Fn fido_cred_id_ptr "const fido_cred_t *cred"
98 .Ft const unsigned char *
99 .Fn fido_cred_aaguid_ptr "const fido_cred_t *cred"
100 .Ft const unsigned char *
101 .Fn fido_cred_largeblob_key_ptr "const fido_cred_t *cred"
102 .Ft const unsigned char *
103 .Fn fido_cred_pubkey_ptr "const fido_cred_t *cred"
104 .Ft const unsigned char *
105 .Fn fido_cred_sig_ptr "const fido_cred_t *cred"
106 .Ft const unsigned char *
107 .Fn fido_cred_user_id_ptr "const fido_cred_t *cred"
108 .Ft size_t
109 .Fn fido_cred_x5c_list_count "const fido_cred_t *cred"
110 .Ft const unsigned char *
111 .Fn fido_cred_x5c_list_ptr "const fido_cred_t *cred" "size_t idx"
112 .Ft const unsigned char *
113 .Fn fido_cred_x5c_ptr "const fido_cred_t *cred"
114 .Ft const unsigned char *
115 .Fn fido_cred_attstmt_ptr "const fido_cred_t *cred"
116 .Ft size_t
117 .Fn fido_cred_authdata_len "const fido_cred_t *cred"
118 .Ft size_t
119 .Fn fido_cred_authdata_raw_len "const fido_cred_t *cred"
120 .Ft size_t
121 .Fn fido_cred_clientdata_hash_len "const fido_cred_t *cred"
122 .Ft size_t
123 .Fn fido_cred_id_len "const fido_cred_t *cred"
124 .Ft size_t
125 .Fn fido_cred_aaguid_len "const fido_cred_t *cred"
126 .Ft size_t
127 .Fn fido_cred_largeblob_key_len "const fido_cred_t *cred"
128 .Ft size_t
129 .Fn fido_cred_pubkey_len "const fido_cred_t *cred"
130 .Ft size_t
131 .Fn fido_cred_sig_len "const fido_cred_t *cred"
132 .Ft size_t
133 .Fn fido_cred_user_id_len "const fido_cred_t *cred"
134 .Ft size_t
135 .Fn fido_cred_x5c_list_len "const fido_cred_t *cred" "size_t idx"
136 .Ft size_t
137 .Fn fido_cred_x5c_len "const fido_cred_t *cred"
138 .Ft size_t
139 .Fn fido_cred_attstmt_len "const fido_cred_t *cred"
140 .Ft int
141 .Fn fido_cred_type "const fido_cred_t *cred"
142 .Ft uint8_t
143 .Fn fido_cred_flags "const fido_cred_t *cred"
144 .Ft uint32_t
145 .Fn fido_cred_sigcount "const fido_cred_t *cred"
146 .Sh DESCRIPTION
147 FIDO2 credentials are abstracted in
148 .Em libfido2
149 by the
150 .Vt fido_cred_t
151 type.
152 The functions described in this page allow a
153 .Vt fido_cred_t
154 type to be allocated, deallocated, and inspected.
155 For other operations on
156 .Vt fido_cred_t ,
157 please refer to
158 .Xr fido_cred_set_authdata 3 ,
159 .Xr fido_cred_exclude 3 ,
160 .Xr fido_cred_verify 3 ,
161 and
162 .Xr fido_dev_make_cred 3 .
163 .Pp
164 The
165 .Fn fido_cred_new
166 function returns a pointer to a newly allocated, empty
167 .Vt fido_cred_t
168 type.
169 If memory cannot be allocated, NULL is returned.
170 .Pp
171 The
172 .Fn fido_cred_free
173 function releases the memory backing
174 .Fa *cred_p ,
175 where
176 .Fa *cred_p
177 must have been previously allocated by
178 .Fn fido_cred_new .
179 On return,
180 .Fa *cred_p
181 is set to NULL.
182 Either
183 .Fa cred_p
184 or
185 .Fa *cred_p
186 may be NULL, in which case
187 .Fn fido_cred_free
188 is a NOP.
189 .Pp
190 If the CTAP 2.1
191 .Dv FIDO_EXT_MINPINLEN
192 extension is enabled on
193 .Fa cred ,
194 then the
195 .Fn fido_cred_pin_minlen
196 function returns the minimum PIN length of
197 .Fa cred .
198 Otherwise,
199 .Fn fido_cred_pin_minlen
200 returns zero.
201 See
202 .Xr fido_cred_set_pin_minlen 3
203 on how to enable this extension.
204 .Pp
205 If the CTAP 2.1
206 .Dv FIDO_EXT_CRED_PROTECT
207 extension is enabled on
208 .Fa cred ,
209 then the
210 .Fn fido_cred_prot
211 function returns the protection of
212 .Fa cred .
213 Otherwise,
214 .Fn fido_cred_prot
215 returns zero.
216 See
217 .Xr fido_cred_set_prot 3
218 for the protection policies understood by
219 .Em libfido2 .
220 .Pp
221 The
222 .Fn fido_cred_fmt
223 function returns a pointer to a NUL-terminated string containing
224 the attestation statement format identifier of
225 .Fa cred ,
226 or NULL if
227 .Fa cred
228 does not have a format set.
229 .Pp
230 The
231 .Fn fido_cred_rp_id ,
232 .Fn fido_cred_rp_name ,
233 .Fn fido_cred_user_name ,
234 and
235 .Fn fido_cred_display_name
236 functions return pointers to NUL-terminated strings holding the
237 relying party ID, relying party name, user name, and user display
238 name attributes of
239 .Fa cred ,
240 or NULL if the respective entry is not set.
241 .Pp
242 The
243 .Fn fido_cred_authdata_ptr ,
244 .Fn fido_cred_authdata_raw_ptr ,
245 .Fn fido_cred_clientdata_hash_ptr ,
246 .Fn fido_cred_id_ptr ,
247 .Fn fido_cred_aaguid_ptr ,
248 .Fn fido_cred_largeblob_key_ptr ,
249 .Fn fido_cred_pubkey_ptr ,
250 .Fn fido_cred_sig_ptr ,
251 .Fn fido_cred_user_id_ptr ,
252 .Fn fido_cred_x5c_ptr ,
253 and
254 .Fn fido_cred_attstmt_ptr
255 functions return pointers to the CBOR-encoded and raw authenticator
256 data, client data hash, ID, authenticator attestation GUID,
257 .Dq largeBlobKey ,
258 public key, signature, user ID, x509 leaf certificate, and attestation
259 statement parts of
260 .Fa cred ,
261 or NULL if the respective entry is not set.
262 .Pp
263 The corresponding length can be obtained by
264 .Fn fido_cred_authdata_len ,
265 .Fn fido_cred_authdata_raw_len ,
266 .Fn fido_cred_clientdata_hash_len ,
267 .Fn fido_cred_id_len ,
268 .Fn fido_cred_aaguid_len ,
269 .Fn fido_cred_largeblob_key_len ,
270 .Fn fido_cred_pubkey_len ,
271 .Fn fido_cred_sig_len ,
272 .Fn fido_cred_user_id_len ,
273 .Fn fido_cred_x5c_len ,
274 and
275 .Fn fido_cred_attstmt_len .
276 .Pp
277 The
278 .Fn fido_cred_x5c_list_count
279 function returns the length of the x509 certificate chain in
280 .Fa cred
281 and the
282 .Fn fido_cred_x5c_list_ptr
283 and
284 .Fn fido_cred_x5c_list_len
285 functions return a pointer to and length of the x509 certificate at index
286 .Fa idx
287 respectively.
288 Please note that the leaf certificate has an
289 .Fa idx
290 (index) value of 0 and calling
291 .Fn fido_cred_x5c_list_ptr cred 0
292 and
293 .Fn fido_cred_x5c_list_len cred 0
294 is equivalent to
295 .Fn fido_cred_x5c_ptr cred
296 and
297 .Fn fido_cred_x5c_len cred
298 respectively.
299 If
300 .Fa idx
301 exceeds the return value of
302 .Fn fido_cred_x5c_list_count ,
303 .Fn fido_cred_x5c_list_ptr
304 returns NULL and
305 .Fn fido_cred_x5c_list_len
306 returns 0.
307 .Pp
308 The authenticator data, x509 certificate, and signature parts of a
309 credential are typically passed to a FIDO2 server for verification.
310 .Pp
311 The
312 .Fn fido_cred_type
313 function returns the COSE algorithm of
314 .Fa cred .
315 .Pp
316 The
317 .Fn fido_cred_flags
318 function returns the authenticator data flags of
319 .Fa cred .
320 .Pp
321 The
322 .Fn fido_cred_sigcount
323 function returns the authenticator data signature counter of
324 .Fa cred .
325 .Sh RETURN VALUES
326 The authenticator data returned by
327 .Fn fido_cred_authdata_ptr
328 is a CBOR-encoded byte string, as obtained from the authenticator.
329 To obtain the decoded byte string, use
330 .Fn fido_cred_authdata_raw_ptr .
331 .Pp
332 If not NULL, pointers returned by
333 .Fn fido_cred_fmt ,
334 .Fn fido_cred_authdata_ptr ,
335 .Fn fido_cred_clientdata_hash_ptr ,
336 .Fn fido_cred_id_ptr ,
337 .Fn fido_cred_aaguid_ptr ,
338 .Fn fido_cred_largeblob_key_ptr ,
339 .Fn fido_cred_pubkey_ptr ,
340 .Fn fido_cred_sig_ptr ,
341 and
342 .Fn fido_cred_x5c_ptr
343 are guaranteed to exist until any API function that takes
344 .Fa cred
345 without the
346 .Em const
347 qualifier is invoked.
348 .Sh SEE ALSO
349 .Xr fido_cred_exclude 3 ,
350 .Xr fido_cred_set_authdata 3 ,
351 .Xr fido_cred_set_pin_minlen 3 ,
352 .Xr fido_cred_set_prot 3 ,
353 .Xr fido_cred_verify 3 ,
354 .Xr fido_credman_metadata_new 3 ,
355 .Xr fido_dev_largeblob_get 3 ,
356 .Xr fido_dev_make_cred 3