Debian Codegraph @

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

raw
1 .\" Copyright (c) 2018-2023 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 19 2023 $
29 .Dt FIDO_ASSERT_NEW 3
30 .Os
31 .Sh NAME
32 .Nm fido_assert_new ,
33 .Nm fido_assert_free ,
34 .Nm fido_assert_count ,
35 .Nm fido_assert_rp_id ,
36 .Nm fido_assert_user_display_name ,
37 .Nm fido_assert_user_icon ,
38 .Nm fido_assert_user_name ,
39 .Nm fido_assert_authdata_ptr ,
40 .Nm fido_assert_authdata_raw_ptr ,
41 .Nm fido_assert_blob_ptr ,
42 .Nm fido_assert_clientdata_hash_ptr ,
43 .Nm fido_assert_hmac_secret_ptr ,
44 .Nm fido_assert_largeblob_key_ptr ,
45 .Nm fido_assert_user_id_ptr ,
46 .Nm fido_assert_sig_ptr ,
47 .Nm fido_assert_id_ptr ,
48 .Nm fido_assert_authdata_len ,
49 .Nm fido_assert_authdata_raw_len ,
50 .Nm fido_assert_blob_len ,
51 .Nm fido_assert_clientdata_hash_len ,
52 .Nm fido_assert_hmac_secret_len ,
53 .Nm fido_assert_largeblob_key_len ,
54 .Nm fido_assert_user_id_len ,
55 .Nm fido_assert_sig_len ,
56 .Nm fido_assert_id_len ,
57 .Nm fido_assert_sigcount ,
58 .Nm fido_assert_flags
59 .Nd FIDO2 assertion API
60 .Sh SYNOPSIS
61 .In fido.h
62 .Ft fido_assert_t *
63 .Fn fido_assert_new "void"
64 .Ft void
65 .Fn fido_assert_free "fido_assert_t **assert_p"
66 .Ft size_t
67 .Fn fido_assert_count "const fido_assert_t *assert"
68 .Ft const char *
69 .Fn fido_assert_rp_id "const fido_assert_t *assert"
70 .Ft const char *
71 .Fn fido_assert_user_display_name "const fido_assert_t *assert" "size_t idx"
72 .Ft const char *
73 .Fn fido_assert_user_icon "const fido_assert_t *assert" "size_t idx"
74 .Ft const char *
75 .Fn fido_assert_user_name "const fido_assert_t *assert" "size_t idx"
76 .Ft const unsigned char *
77 .Fn fido_assert_authdata_ptr "const fido_assert_t *assert" "size_t idx"
78 .Ft const unsigned char *
79 .Fn fido_assert_authdata_raw_ptr "const fido_assert_t *assert" "size_t idx"
80 .Ft const unsigned char *
81 .Fn fido_assert_clientdata_hash_ptr "const fido_assert_t *assert"
82 .Ft const unsigned char *
83 .Fn fido_assert_blob_ptr "const fido_assert_t *assert" "size_t idx"
84 .Ft const unsigned char *
85 .Fn fido_assert_hmac_secret_ptr "const fido_assert_t *assert" "size_t idx"
86 .Ft const unsigned char *
87 .Fn fido_assert_largeblob_key_ptr "const fido_assert_t *assert" "size_t idx"
88 .Ft const unsigned char *
89 .Fn fido_assert_user_id_ptr "const fido_assert_t *assert" "size_t idx"
90 .Ft const unsigned char *
91 .Fn fido_assert_sig_ptr "const fido_assert_t *assert" "size_t idx"
92 .Ft const unsigned char *
93 .Fn fido_assert_id_ptr "const fido_assert_t *assert" "size_t idx"
94 .Ft size_t
95 .Fn fido_assert_authdata_len "const fido_assert_t *assert" "size_t idx"
96 .Ft size_t
97 .Fn fido_assert_authdata_raw_len "const fido_assert_t *assert" "size_t idx"
98 .Ft size_t
99 .Fn fido_assert_clientdata_hash_len "const fido_assert_t *assert"
100 .Ft size_t
101 .Fn fido_assert_blob_len "const fido_assert_t *assert" "size_t idx"
102 .Ft size_t
103 .Fn fido_assert_hmac_secret_len "const fido_assert_t *assert" "size_t idx"
104 .Ft size_t
105 .Fn fido_assert_largeblob_key_len "const fido_assert_t *assert" "size_t idx"
106 .Ft size_t
107 .Fn fido_assert_user_id_len "const fido_assert_t *assert" "size_t idx"
108 .Ft size_t
109 .Fn fido_assert_sig_len "const fido_assert_t *assert" "size_t idx"
110 .Ft size_t
111 .Fn fido_assert_id_len "const fido_assert_t *assert" "size_t idx"
112 .Ft uint32_t
113 .Fn fido_assert_sigcount "const fido_assert_t *assert" "size_t idx"
114 .Ft uint8_t
115 .Fn fido_assert_flags "const fido_assert_t *assert" "size_t idx"
116 .Sh DESCRIPTION
117 A FIDO2 assertion is a collection of statements, each statement a
118 map between a challenge, a credential, a signature, and ancillary
119 attributes.
120 In
121 .Em libfido2 ,
122 a FIDO2 assertion is abstracted by the
123 .Vt fido_assert_t
124 type.
125 The functions described in this page allow a
126 .Vt fido_assert_t
127 type to be allocated, deallocated, and inspected.
128 For other operations on
129 .Vt fido_assert_t ,
130 please refer to
131 .Xr fido_assert_set_authdata 3 ,
132 .Xr fido_assert_allow_cred 3 ,
133 .Xr fido_assert_verify 3 ,
134 and
135 .Xr fido_dev_get_assert 3 .
136 .Pp
137 The
138 .Fn fido_assert_new
139 function returns a pointer to a newly allocated, empty
140 .Vt fido_assert_t
141 type.
142 If memory cannot be allocated, NULL is returned.
143 .Pp
144 The
145 .Fn fido_assert_free
146 function releases the memory backing
147 .Fa *assert_p ,
148 where
149 .Fa *assert_p
150 must have been previously allocated by
151 .Fn fido_assert_new .
152 On return,
153 .Fa *assert_p
154 is set to NULL.
155 Either
156 .Fa assert_p
157 or
158 .Fa *assert_p
159 may be NULL, in which case
160 .Fn fido_assert_free
161 is a NOP.
162 .Pp
163 The
164 .Fn fido_assert_count
165 function returns the number of statements in
166 .Fa assert .
167 .Pp
168 The
169 .Fn fido_assert_rp_id
170 function returns a pointer to a NUL-terminated string holding the
171 relying party ID of
172 .Fa assert .
173 .Pp
174 The
175 .Fn fido_assert_user_display_name ,
176 .Fn fido_assert_user_icon ,
177 and
178 .Fn fido_assert_user_name ,
179 functions return pointers to the user display name, icon, and
180 name attributes of statement
181 .Fa idx
182 in
183 .Fa assert .
184 If not NULL, the values returned by these functions point to
185 NUL-terminated UTF-8 strings.
186 The user display name, icon, and name attributes will typically
187 only be returned by the authenticator if user verification was
188 performed by the authenticator and multiple resident/discoverable
189 credentials were involved in the assertion.
190 .Pp
191 The
192 .Fn fido_assert_authdata_ptr ,
193 .Fn fido_assert_authdata_raw_ptr ,
194 .Fn fido_assert_clientdata_hash_ptr ,
195 .Fn fido_assert_id_ptr ,
196 .Fn fido_assert_user_id_ptr ,
197 .Fn fido_assert_sig_ptr ,
198 .Fn fido_assert_sigcount ,
199 and
200 .Fn fido_assert_flags
201 functions return pointers to the CBOR-encoded and raw authenticator data,
202 client data hash, credential ID, user ID, signature, signature
203 count, and authenticator data flags of statement
204 .Fa idx
205 in
206 .Fa assert .
207 .Pp
208 The
209 .Fn fido_assert_hmac_secret_ptr
210 function returns a pointer to the hmac-secret attribute of statement
211 .Fa idx
212 in
213 .Fa assert .
214 The HMAC Secret Extension
215 .Pq hmac-secret
216 is a CTAP 2.0 extension.
217 Note that the resulting hmac-secret varies according to whether
218 user verification was performed by the authenticator.
219 .Pp
220 The
221 .Fn fido_assert_blob_ptr
222 and
223 .Fn fido_assert_largeblob_key_ptr
224 functions return pointers to the
225 .Dq credBlob
226 and
227 .Dq largeBlobKey
228 attributes of statement
229 .Fa idx
230 in
231 .Fa assert .
232 Credential Blob
233 .Pq credBlob
234 and
235 Large Blob Key
236 .Pq largeBlobKey
237 are CTAP 2.1 extensions.
238 .Pp
239 The
240 .Fn fido_assert_authdata_len ,
241 .Fn fido_assert_authdata_raw_len ,
242 .Fn fido_assert_clientdata_hash_len ,
243 .Fn fido_assert_id_len ,
244 .Fn fido_assert_user_id_len ,
245 .Fn fido_assert_sig_len ,
246 .Fn fido_assert_hmac_secret_len ,
247 .Fn fido_assert_blob_len ,
248 and
249 .Fn fido_assert_largeblob_key_len
250 functions return the length of a given attribute.
251 .Pp
252 Please note that the first statement in
253 .Fa assert
254 has an
255 .Fa idx
256 (index) value of 0.
257 .Pp
258 The authenticator data and signature parts of an assertion
259 statement are typically passed to a FIDO2 server for verification.
260 .Sh RETURN VALUES
261 The authenticator data returned by
262 .Fn fido_assert_authdata_ptr
263 is a CBOR-encoded byte string, as obtained from the authenticator.
264 .Pp
265 The
266 .Fn fido_assert_rp_id ,
267 .Fn fido_assert_user_display_name ,
268 .Fn fido_assert_user_icon ,
269 .Fn fido_assert_user_name ,
270 .Fn fido_assert_authdata_ptr ,
271 .Fn fido_assert_clientdata_hash_ptr ,
272 .Fn fido_assert_id_ptr ,
273 .Fn fido_assert_user_id_ptr ,
274 .Fn fido_assert_sig_ptr ,
275 .Fn fido_assert_hmac_secret_ptr ,
276 .Fn fido_assert_blob_ptr ,
277 and
278 .Fn fido_assert_largeblob_key_ptr
279 functions may return NULL if the respective field in
280 .Fa assert
281 is not set.
282 If not NULL, returned pointers are guaranteed to exist until any API
283 function that takes
284 .Fa assert
285 without the
286 .Em const
287 qualifier is invoked.
288 .Sh SEE ALSO
289 .Xr fido_assert_allow_cred 3 ,
290 .Xr fido_assert_set_authdata 3 ,
291 .Xr fido_assert_verify 3 ,
292 .Xr fido_dev_get_assert 3 ,
293 .Xr fido_dev_largeblob_get 3