diff options
Diffstat (limited to 'man/fido_credman_metadata_new.3')
-rw-r--r-- | man/fido_credman_metadata_new.3 | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/man/fido_credman_metadata_new.3 b/man/fido_credman_metadata_new.3 new file mode 100644 index 0000000..16f0192 --- /dev/null +++ b/man/fido_credman_metadata_new.3 | |||
@@ -0,0 +1,299 @@ | |||
1 | .\" Copyright (c) 2019 Yubico AB. All rights reserved. | ||
2 | .\" Use of this source code is governed by a BSD-style | ||
3 | .\" license that can be found in the LICENSE file. | ||
4 | .\" | ||
5 | .Dd $Mdocdate: June 28 2019 $ | ||
6 | .Dt FIDO_CREDMAN_METADATA_NEW 3 | ||
7 | .Os | ||
8 | .Sh NAME | ||
9 | .Nm fido_credman_metadata_new , | ||
10 | .Nm fido_credman_rk_new , | ||
11 | .Nm fido_credman_rp_new , | ||
12 | .Nm fido_credman_metadata_free , | ||
13 | .Nm fido_credman_rk_free , | ||
14 | .Nm fido_credman_rp_free , | ||
15 | .Nm fido_credman_rk_existing , | ||
16 | .Nm fido_credman_rk_remaining , | ||
17 | .Nm fido_credman_rk , | ||
18 | .Nm fido_credman_rk_count , | ||
19 | .Nm fido_credman_rp_id , | ||
20 | .Nm fido_credman_rp_name , | ||
21 | .Nm fido_credman_rp_count , | ||
22 | .Nm fido_credman_rp_id_hash_ptr , | ||
23 | .Nm fido_credman_rp_id_hash_len , | ||
24 | .Nm fido_credman_get_dev_metadata , | ||
25 | .Nm fido_credman_get_dev_rk , | ||
26 | .Nm fido_credman_del_dev_rk , | ||
27 | .Nm fido_credman_get_dev_rp | ||
28 | .Nd FIDO 2 credential management API | ||
29 | .Sh SYNOPSIS | ||
30 | .In fido.h | ||
31 | .In fido/credman.h | ||
32 | .Ft fido_credman_metadata_t * | ||
33 | .Fn fido_credman_metadata_new "void" | ||
34 | .Ft fido_credman_rk_t * | ||
35 | .Fn fido_credman_rk_new "void" | ||
36 | .Ft fido_credman_rp_t * | ||
37 | .Fn fido_credman_rp_new "void" | ||
38 | .Ft void | ||
39 | .Fn fido_credman_metadata_free "fido_credman_metadata_t **metadata_p" | ||
40 | .Ft void | ||
41 | .Fn fido_credman_rk_free "fido_credman_rk_t **rk_p" | ||
42 | .Ft void | ||
43 | .Fn fido_credman_rp_free "fido_credman_rp_t **rp_p" | ||
44 | .Ft uint64_t | ||
45 | .Fn fido_credman_rk_existing "const fido_credman_metadata_t *metadata" | ||
46 | .Ft uint64_t | ||
47 | .Fn fido_credman_rk_remaining "const fido_credman_metadata_t *metadata" | ||
48 | .Ft const fido_cred_t * | ||
49 | .Fn fido_credman_rk "const fido_credman_rk_t *rk" "size_t idx" | ||
50 | .Ft size_t | ||
51 | .Fn fido_credman_rk_count "const fido_credman_rk_t *rk" | ||
52 | .Ft const char * | ||
53 | .Fn fido_credman_rp_id "const fido_credman_rp_t *rp" "size_t idx" | ||
54 | .Ft const char * | ||
55 | .Fn fido_credman_rp_name "const fido_credman_rp_t *rp" "size_t idx" | ||
56 | .Ft size_t | ||
57 | .Fn fido_credman_rp_count "const fido_credman_rp_t *rp" | ||
58 | .Ft const unsigned char * | ||
59 | .Fn fido_credman_rp_id_hash_ptr "const fido_credman_rp_t *rp" "size_t idx" | ||
60 | .Ft size_t | ||
61 | .Fn fido_credman_rp_id_hash_len "const fido_credman_rp_t *" "size_t idx" | ||
62 | .Ft int | ||
63 | .Fn fido_credman_get_dev_metadata "fido_dev_t *dev" "fido_credman_metadata_t *metadata" "const char *pin" | ||
64 | .Ft int | ||
65 | .Fn fido_credman_get_dev_rk "fido_dev_t *dev" "const char *rp_id" "fido_credman_rk_t *rk" "const char *pin" | ||
66 | .Ft int | ||
67 | .Fn fido_credman_del_dev_rk "fido_dev_t *dev" const unsigned char *cred_id" "size_t cred_id_len" "const char *pin" | ||
68 | .Ft int | ||
69 | .Fn fido_credman_get_dev_rp "fido_dev_t *dev" "fido_credman_rp_t *rp" "const char *pin" | ||
70 | .Sh DESCRIPTION | ||
71 | The credential management API of | ||
72 | .Em libfido2 | ||
73 | allows resident credentials on a FIDO2 authenticator to be listed, | ||
74 | inspected, and removed. | ||
75 | Please note that not all authenticators support credential management. | ||
76 | To obtain information on what an authenticator supports, please | ||
77 | refer to | ||
78 | .Xr fido_cbor_info_new 3 . | ||
79 | .Pp | ||
80 | The | ||
81 | .Vt fido_credman_metadata_t | ||
82 | type abstracts credential management metadata. | ||
83 | .Pp | ||
84 | The | ||
85 | .Fn fido_credman_metadata_new | ||
86 | function returns a pointer to a newly allocated, empty | ||
87 | .Vt fido_credman_metadata_t | ||
88 | type. | ||
89 | If memory cannot be allocated, NULL is returned. | ||
90 | .Pp | ||
91 | The | ||
92 | .Fn fido_credman_metadata_free | ||
93 | function releases the memory backing | ||
94 | .Fa *metadata_p , | ||
95 | where | ||
96 | .Fa *metadata_p | ||
97 | must have been previously allocated by | ||
98 | .Fn fido_credman_metadata_new . | ||
99 | On return, | ||
100 | .Fa *metadata_p | ||
101 | is set to NULL. | ||
102 | Either | ||
103 | .Fa metadata_p | ||
104 | or | ||
105 | .Fa *metadata_p | ||
106 | may be NULL, in which case | ||
107 | .Fn fido_credman_metadata_free | ||
108 | is a NOP. | ||
109 | .Pp | ||
110 | The | ||
111 | .Fn fido_credman_get_dev_metadata | ||
112 | function populates | ||
113 | .Fa metadata | ||
114 | with information retrieved from | ||
115 | .Fa dev . | ||
116 | A valid | ||
117 | .Fa pin | ||
118 | must be provided. | ||
119 | .Pp | ||
120 | The | ||
121 | .Fn fido_credman_rk_existing | ||
122 | function inspects | ||
123 | .Fa metadata | ||
124 | and returns the number of resident credentials on the | ||
125 | authenticator. | ||
126 | The | ||
127 | .Fn fido_credman_rk_remaining | ||
128 | function inspects | ||
129 | .Fa metadata | ||
130 | and returns the estimated number of resident credentials that can | ||
131 | be created on the authenticator. | ||
132 | .Pp | ||
133 | The | ||
134 | .Vt fido_credman_rk_t | ||
135 | type abstracts the set of resident credentials belonging to a | ||
136 | given relying party. | ||
137 | .Pp | ||
138 | The | ||
139 | .Fn fido_credman_rk_new | ||
140 | function returns a pointer to a newly allocated, empty | ||
141 | .Vt fido_credman_rk_t | ||
142 | type. | ||
143 | If memory cannot be allocated, NULL is returned. | ||
144 | .Pp | ||
145 | The | ||
146 | .Fn fido_credman_rk_free | ||
147 | function releases the memory backing | ||
148 | .Fa *rk_p , | ||
149 | where | ||
150 | .Fa *rk_p | ||
151 | must have been previously allocated by | ||
152 | .Fn fido_credman_rk_new . | ||
153 | On return, | ||
154 | .Fa *rk_p | ||
155 | is set to NULL. | ||
156 | Either | ||
157 | .Fa rk_p | ||
158 | or | ||
159 | .Fa *rk_p | ||
160 | may be NULL, in which case | ||
161 | .Fn fido_credman_rk_free | ||
162 | is a NOP. | ||
163 | .Pp | ||
164 | The | ||
165 | .Fn fido_credman_get_dev_rk | ||
166 | function populates | ||
167 | .Fa rk | ||
168 | with the set of resident credentials belonging to | ||
169 | .Fa rp_id | ||
170 | in | ||
171 | .Fa dev . | ||
172 | A valid | ||
173 | .Fa pin | ||
174 | must be provided. | ||
175 | .Pp | ||
176 | The | ||
177 | .Fn fido_credman_rk_count | ||
178 | function returns the number of resident credentials in | ||
179 | .Fa rk . | ||
180 | The | ||
181 | .Fn fido_credman_rk | ||
182 | function returns a pointer to the credential at index | ||
183 | .Fa idx | ||
184 | in | ||
185 | .Fa rk . | ||
186 | Please note that the first credential in | ||
187 | .Fa rk | ||
188 | has an | ||
189 | .Fa idx | ||
190 | (index) value of 0. | ||
191 | .Pp | ||
192 | The | ||
193 | .Fn fido_credman_del_dev_rk | ||
194 | function deletes the resident credential identified by | ||
195 | .Fa cred_id | ||
196 | from | ||
197 | .Fa dev , | ||
198 | where | ||
199 | .Fa cred_id | ||
200 | points to | ||
201 | .Fa cred_id_len | ||
202 | bytes. | ||
203 | A valid | ||
204 | .Fa pin | ||
205 | must be provided. | ||
206 | .Pp | ||
207 | The | ||
208 | .Vt fido_credman_rp_t | ||
209 | type abstracts information about a relying party. | ||
210 | .Pp | ||
211 | The | ||
212 | .Fn fido_credman_rp_new | ||
213 | function returns a pointer to a newly allocated, empty | ||
214 | .Vt fido_credman_rp_t | ||
215 | type. | ||
216 | If memory cannot be allocated, NULL is returned. | ||
217 | .Pp | ||
218 | The | ||
219 | .Fn fido_credman_rp_free | ||
220 | function releases the memory backing | ||
221 | .Fa *rp_p , | ||
222 | where | ||
223 | .Fa *rp_p | ||
224 | must have been previously allocated by | ||
225 | .Fn fido_credman_rp_new . | ||
226 | On return, | ||
227 | .Fa *rp_p | ||
228 | is set to NULL. | ||
229 | Either | ||
230 | .Fa rp_p | ||
231 | or | ||
232 | .Fa *rp_p | ||
233 | may be NULL, in which case | ||
234 | .Fn fido_credman_rp_free | ||
235 | is a NOP. | ||
236 | .Pp | ||
237 | The | ||
238 | .Fn fido_credman_get_dev_rp | ||
239 | function populates | ||
240 | .Fa rp | ||
241 | with information about relying parties with resident credentials | ||
242 | in | ||
243 | .Fa dev . | ||
244 | A valid | ||
245 | .Fa pin | ||
246 | must be provided. | ||
247 | .Pp | ||
248 | The | ||
249 | .Fn fido_credman_rp_count | ||
250 | function returns the number of relying parties in | ||
251 | .Fa rp . | ||
252 | .Pp | ||
253 | The | ||
254 | .Fn fido_credman_rp_id | ||
255 | and | ||
256 | .Fn fido_credman_rp_name | ||
257 | functions return pointers to the id and name of relying party | ||
258 | .Fa idx | ||
259 | in | ||
260 | .Fa rp . | ||
261 | If not NULL, the values returned by these functions point to | ||
262 | NUL-terminated UTF-8 strings. | ||
263 | Please note that the first relying party in | ||
264 | .Fa rp | ||
265 | has an | ||
266 | .Fa idx | ||
267 | (index) value of 0. | ||
268 | .Pp | ||
269 | The | ||
270 | .Fn fido_credman_rp_id_hash_ptr | ||
271 | function returns a pointer to the hashed id of relying party | ||
272 | .Fa idx | ||
273 | in | ||
274 | .Fa rp . | ||
275 | The corresponding length can be obtained by | ||
276 | .Fn fido_credman_rp_id_hash_len . | ||
277 | Please note that the first relying party in | ||
278 | .Fa rp | ||
279 | has an | ||
280 | .Fa idx | ||
281 | (index) value of 0. | ||
282 | .Sh RETURN VALUES | ||
283 | The | ||
284 | .Fn fido_credman_get_dev_metadata , | ||
285 | .Fn fido_credman_get_dev_rk , | ||
286 | .Fn fido_credman_del_dev_rk , | ||
287 | and | ||
288 | .Fn fido_credman_get_dev_rp | ||
289 | functions return | ||
290 | .Dv FIDO_OK | ||
291 | on success. | ||
292 | On error, a different error code defined in | ||
293 | .In fido/err.h | ||
294 | is returned. | ||
295 | Functions returning pointers are not guaranteed to succeed, and | ||
296 | should have their return values checked for NULL. | ||
297 | .Sh SEE ALSO | ||
298 | .Xr fido_cbor_info_new 3 , | ||
299 | .Xr fido_cred_new 3 | ||