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