Debian Codegraph @

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

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