1.\" Copyright (c) 2018 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: May 25 2018 $
6.Dt FIDO_DEV_INFO_MANIFEST 3
7.Os
8.Sh NAME
9.Nm fido_dev_info_manifest ,
10.Nm fido_dev_info_new ,
11.Nm fido_dev_info_free ,
12.Nm fido_dev_info_ptr ,
13.Nm fido_dev_info_path ,
14.Nm fido_dev_info_product ,
15.Nm fido_dev_info_vendor ,
16.Nm fido_dev_info_manufacturer_string ,
17.Nm fido_dev_info_product_string ,
18.Nm fido_dev_info_set
19.Nd FIDO2 device discovery functions
20.Sh SYNOPSIS
21.In fido.h
22.Ft int
23.Fn fido_dev_info_manifest "fido_dev_info_t *devlist" "size_t ilen" "size_t *olen"
24.Ft fido_dev_info_t *
25.Fn fido_dev_info_new "size_t n"
26.Ft void
27.Fn fido_dev_info_free "fido_dev_info_t **devlist_p" "size_t n"
28.Ft const fido_dev_info_t *
29.Fn fido_dev_info_ptr "const fido_dev_info_t *devlist" "size_t i"
30.Ft const char *
31.Fn fido_dev_info_path "const fido_dev_info_t *di"
32.Ft int16_t
33.Fn fido_dev_info_product "const fido_dev_info_t *di"
34.Ft int16_t
35.Fn fido_dev_info_vendor "const fido_dev_info_t *di"
36.Ft const char *
37.Fn fido_dev_info_manufacturer_string "const fido_dev_info_t *di"
38.Ft const char *
39.Fn fido_dev_info_product_string "const fido_dev_info_t *di"
40.Ft int
41.Fn fido_dev_info_set "fido_dev_info_t *devlist" "size_t i" "const char *path" "const char *manufacturer" "const char *product" "const fido_dev_io_t *io" "const fido_dev_transport_t *transport"
42.Sh DESCRIPTION
43The
44.Fn fido_dev_info_manifest
45function fills
46.Fa devlist
47with up to
48.Fa ilen
49FIDO2 devices found by the underlying operating system.
50Currently only USB HID devices are supported.
51The number of discovered devices is returned in
52.Fa olen ,
53where
54.Fa olen
55is an addressable pointer.
56.Pp
57The
58.Fn fido_dev_info_new
59function returns a pointer to a newly allocated, empty device list
60with
61.Fa n
62available slots.
63If memory is not available, NULL is returned.
64.Pp
65The
66.Fn fido_dev_info_free
67function releases the memory backing
68.Fa *devlist_p ,
69where
70.Fa *devlist_p
71must have been previously allocated by
72.Fn fido_dev_info_new .
73The number
74.Fa n
75of allocated slots must also be provided.
76On return,
77.Fa *devlist_p
78is set to NULL.
79Either
80.Fa devlist_p
81or
82.Fa *devlist_p
83may be NULL, in which case
84.Fn fido_dev_info_free
85is a NOP.
86.Pp
87The
88.Fn fido_dev_info_ptr
89function returns a pointer to slot number
90.Fa i
91of
92.Fa devlist .
93It is the caller's responsibility to ensure that
94.Fa i
95is bounded.
96Please note that the first slot has index 0.
97.Pp
98The
99.Fn fido_dev_info_path
100returns the filesystem path or subsystem-specific identification
101string of
102.Fa di .
103.Pp
104The
105.Fn fido_dev_info_product
106function returns the product ID of
107.Fa di .
108.Pp
109The
110.Fn fido_dev_info_vendor
111function returns the vendor ID of
112.Fa di .
113.Pp
114The
115.Fn fido_dev_info_manufacturer_string
116function returns the manufacturer string of
117.Fa di .
118If
119.Fa di
120does not have an associated manufacturer string,
121.Fn fido_dev_info_manufacturer_string
122returns an empty string.
123.Pp
124The
125.Fn fido_dev_info_product_string
126function returns the product string of
127.Fa di .
128If
129.Fa di
130does not have an associated product string,
131.Fn fido_dev_info_product_string
132returns an empty string.
133.Pp
134An example of how to use the functions described in this document
135can be found in the
136.Pa examples/manifest.c
137file shipped with
138.Em libfido2 .
139.Pp
140The
141.Fn fido_dev_info_set
142function initializes an entry in a device list allocated by
143.Fn fido_dev_info_new
144with the specified path, manufacturer, and product strings, and with
145the specified I/O handlers and, optionally, transport functions, as
146described in
147.Xr fido_dev_set_io_functions 3 .
148The
149.Fa io
150argument must be specified; the
151.Fa transport
152argument may be
153.Dv NULL .
154The path, I/O handlers, and transport functions will be used
155automatically by
156.Xr fido_dev_new_with_info 3
157and
158.Xr fido_dev_open_with_info 3 .
159An application can use this, for example, to substitute mock FIDO2
160devices in testing for the real ones that
161.Fn fido_dev_info_manifest
162would discover.
163.Sh RETURN VALUES
164The
165.Fn fido_dev_info_manifest
166function always returns
167.Dv FIDO_OK .
168If a discovery error occurs, the
169.Fa olen
170pointer is set to 0.
171.Pp
172On success, the
173.Fn fido_dev_info_set
174function returns
175.Dv FIDO_OK .
176On error, a different error code defined in
177.In fido/err.h
178is returned.
179.Pp
180The pointers returned by
181.Fn fido_dev_info_ptr ,
182.Fn fido_dev_info_path ,
183.Fn fido_dev_info_manufacturer_string ,
184and
185.Fn fido_dev_info_product_string
186are guaranteed to exist until
187.Fn fido_dev_info_free
188is called on the corresponding device list.
189