Debian Codegraph @

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

raw
1 .\" Copyright (c) 2018-2021 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: May 25 2018 $
29 .Dt FIDO_DEV_SET_IO_FUNCTIONS 3
30 .Os
31 .Sh NAME
32 .Nm fido_dev_set_io_functions ,
33 .Nm fido_dev_set_sigmask ,
34 .Nm fido_dev_set_timeout ,
35 .Nm fido_dev_set_transport_functions ,
36 .Nm fido_dev_io_handle
37 .Nd FIDO2 device I/O interface
38 .Sh SYNOPSIS
39 .In fido.h
40 .Bd -literal
41 typedef void *fido_dev_io_open_t(const char *);
42 typedef void fido_dev_io_close_t(void *);
43 typedef int fido_dev_io_read_t(void *, unsigned char *, size_t, int);
44 typedef int fido_dev_io_write_t(void *, const unsigned char *, size_t);
45
46 typedef struct fido_dev_io {
47 fido_dev_io_open_t *open;
48 fido_dev_io_close_t *close;
49 fido_dev_io_read_t *read;
50 fido_dev_io_write_t *write;
51 } fido_dev_io_t;
52
53 #ifdef _WIN32
54 typedef int fido_sigset_t;
55 #else
56 typedef sigset_t fido_sigset_t;
57 #endif
58
59 typedef int fido_dev_rx_t(struct fido_dev *,
60 uint8_t, unsigned char *, size_t, int);
61 typedef int fido_dev_tx_t(struct fido_dev *,
62 uint8_t, const unsigned char *, size_t);
63
64 typedef struct fido_dev_transport {
65 fido_dev_rx_t *rx;
66 fido_dev_tx_t *tx;
67 } fido_dev_transport_t;
68 .Ed
69 .Pp
70 .Ft int
71 .Fn fido_dev_set_io_functions "fido_dev_t *dev" "const fido_dev_io_t *io"
72 .Ft int
73 .Fn fido_dev_set_sigmask "fido_dev_t *dev" "const fido_sigset_t *sigmask"
74 .Ft int
75 .Fn fido_dev_set_timeout "fido_dev_t *dev" "int ms"
76 .Ft int
77 .Fn fido_dev_set_transport_functions "fido_dev_t *dev" "const fido_dev_transport_t *t"
78 .Ft void *
79 .Fn fido_dev_io_handle "const fido_dev_t *dev"
80 .Sh DESCRIPTION
81 The
82 .Fn fido_dev_set_io_functions
83 function sets the I/O handlers used by
84 .Em libfido2
85 to talk to
86 .Fa dev .
87 By default, these handlers are set to the operating system's native HID or NFC
88 interfaces.
89 They are defined as follows:
90 .Bl -tag -width Ds
91 .It Vt fido_dev_open_t
92 Receives a
93 .Vt const char *
94 holding a path and opens the corresponding device, returning a
95 non-NULL opaque pointer on success and NULL on error.
96 .It Vt fido_dev_close_t
97 Receives the opaque pointer returned by
98 .Vt fido_dev_open_t
99 and closes the device.
100 .It Vt fido_dev_read_t
101 Reads a single transmission unit (HID report, APDU) from a device.
102 The first parameter is the opaque pointer returned by
103 .Vt fido_dev_open_t .
104 The second parameter is the read buffer, and the third parameter
105 is the read buffer size.
106 The fourth parameter is the number of milliseconds the caller is
107 willing to sleep, should the call need to block.
108 If this value holds -1,
109 .Vt fido_dev_read_t
110 may block indefinitely.
111 On success, the number of bytes read is returned.
112 On error, -1 is returned.
113 .It Vt fido_dev_write_t
114 Writes a single transmission unit (HID report, APDU) to
115 .Fa dev .
116 The first parameter is the opaque pointer returned by
117 .Vt fido_dev_open_t .
118 The second parameter is the write buffer, and the third parameter
119 is the number of bytes to be written.
120 A
121 .Vt fido_dev_write_t
122 may block.
123 On success, the number of bytes written is returned.
124 On error, -1 is returned.
125 .El
126 .Pp
127 When calling
128 .Fn fido_dev_set_io_functions ,
129 the
130 .Fa open ,
131 .Fa close ,
132 .Fa read ,
133 and
134 .Fa write
135 fields of
136 .Fa io
137 may not be NULL.
138 .Pp
139 No references to
140 .Fa io
141 are held by
142 .Fn fido_dev_set_io_functions .
143 .Pp
144 The
145 .Fn fido_dev_set_sigmask
146 function may be used to specify a non-NULL signal mask
147 .Fa sigmask
148 to be used while
149 .Em libfido2's
150 default I/O handlers wait on
151 .Fa dev .
152 On UNIX-like operating systems,
153 .Vt fido_sigset_t
154 is defined as
155 .Vt sigset_t .
156 On Windows,
157 .Vt fido_sigset_t
158 is defined as
159 .Vt int
160 and
161 .Fn fido_dev_set_sigmask
162 is a no-op.
163 .Pp
164 No references to
165 .Fa sigmask
166 are held by
167 .Fn fido_dev_set_sigmask .
168 .Pp
169 The
170 .Fn fido_dev_set_timeout
171 function informs
172 .Em libfido2
173 not to block for more than
174 .Fa ms
175 milliseconds while communicating with
176 .Fa dev .
177 If a timeout occurs, the corresponding
178 .Em fido_dev_*
179 function will fail with
180 .Dv FIDO_ERR_RX .
181 If
182 .Fa ms
183 is -1,
184 then
185 .Em libfido2
186 may block indefinitely.
187 This is the default behaviour.
188 When using the Windows Hello backend,
189 .Fa ms
190 is used as a guidance and may be overwritten by the platform.
191 .Pp
192 The
193 .Fn fido_dev_set_transport_functions
194 function sets the transport functions used by
195 .Em libfido2
196 to talk to
197 .Fa dev .
198 While the I/O handlers are responsible for sending and receiving
199 transmission units of initialization and continuation packets already
200 formatted by
201 .Em libfido2 ,
202 the transport handlers are responsible for sending and receiving
203 the CTAPHID commands and data directly, as defined in the FIDO Client
204 to Authenticator Protocol (CTAP) standard.
205 They are defined as follows:
206 .Bl -tag -width Ds
207 .It Vt fido_dev_tx_t
208 Receives a device, a CTAPHID command to transmit, a data buffer to
209 transmit, and the length of the data buffer.
210 On success, 0 is returned.
211 On error, -1 is returned.
212 .It Vt fido_dev_rx_t
213 Receives a device, a CTAPHID command whose response the caller expects
214 to receive, a data buffer to receive into, the size of the data buffer
215 determining the maximum length of a response, and the maximum number of
216 milliseconds to wait for a response.
217 On success, the number of bytes read into the data buffer is returned.
218 On error, -1 is returned.
219 .El
220 .Pp
221 When transport functions are specified,
222 .Em libfido2
223 will use them instead of the
224 .Dv read
225 and
226 .Dv write
227 functions of the I/O handlers.
228 However, the I/O handlers must still be specified to open and close the
229 device.
230 .Pp
231 The
232 .Fn fido_dev_io_handle
233 function returns the opaque pointer returned by the
234 .Dv open
235 function of the I/O handlers.
236 This is useful mainly for the transport functions, which unlike the I/O
237 handlers are passed the
238 .Vt fido_dev_t
239 pointer instead of the opaque I/O handle.
240 .Sh RETURN VALUES
241 On success,
242 .Fn fido_dev_set_io_functions ,
243 .Fn fido_dev_set_transport_functions ,
244 .Fn fido_dev_set_sigmask ,
245 and
246 .Fn fido_dev_set_timeout
247 return
248 .Dv FIDO_OK .
249 On error, a different error code defined in
250 .In fido/err.h
251 is returned.
252 .Sh SEE ALSO
253 .Xr fido_dev_info_manifest 3 ,
254 .Xr fido_dev_open 3
255 .Rs
256 .%D 2021-06-15
257 .%O Proposed Standard, Version 2.1
258 .%Q FIDO Alliance
259 .%R Client to Authenticator Protocol (CTAP)
260 .%U https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html
261 .Re