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 41typedef void *fido_dev_io_open_t(const char *); 42typedef void fido_dev_io_close_t(void *); 43typedef int fido_dev_io_read_t(void *, unsigned char *, size_t, int); 44typedef int fido_dev_io_write_t(void *, const unsigned char *, size_t); 45 46typedef 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 54typedef int fido_sigset_t; 55#else 56typedef sigset_t fido_sigset_t; 57#endif 58 59typedef int fido_dev_rx_t(struct fido_dev *, 60 uint8_t, unsigned char *, size_t, int); 61typedef int fido_dev_tx_t(struct fido_dev *, 62 uint8_t, const unsigned char *, size_t); 63 64typedef 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 81The 82.Fn fido_dev_set_io_functions 83function sets the I/O handlers used by 84.Em libfido2 85to talk to 86.Fa dev . 87By default, these handlers are set to the operating system's native HID or NFC 88interfaces. 89They are defined as follows: 90.Bl -tag -width Ds 91.It Vt fido_dev_open_t 92Receives a 93.Vt const char * 94holding a path and opens the corresponding device, returning a 95non-NULL opaque pointer on success and NULL on error. 96.It Vt fido_dev_close_t 97Receives the opaque pointer returned by 98.Vt fido_dev_open_t 99and closes the device. 100.It Vt fido_dev_read_t 101Reads a single transmission unit (HID report, APDU) from a device. 102The first parameter is the opaque pointer returned by 103.Vt fido_dev_open_t . 104The second parameter is the read buffer, and the third parameter 105is the read buffer size. 106The fourth parameter is the number of milliseconds the caller is 107willing to sleep, should the call need to block. 108If this value holds -1, 109.Vt fido_dev_read_t 110may block indefinitely. 111On success, the number of bytes read is returned. 112On error, -1 is returned. 113.It Vt fido_dev_write_t 114Writes a single transmission unit (HID report, APDU) to 115.Fa dev . 116The first parameter is the opaque pointer returned by 117.Vt fido_dev_open_t . 118The second parameter is the write buffer, and the third parameter 119is the number of bytes to be written. 120A 121.Vt fido_dev_write_t 122may block. 123On success, the number of bytes written is returned. 124On error, -1 is returned. 125.El 126.Pp 127When calling 128.Fn fido_dev_set_io_functions , 129the 130.Fa open , 131.Fa close , 132.Fa read , 133and 134.Fa write 135fields of 136.Fa io 137may not be NULL. 138.Pp 139No references to 140.Fa io 141are held by 142.Fn fido_dev_set_io_functions . 143.Pp 144The 145.Fn fido_dev_set_sigmask 146function may be used to specify a non-NULL signal mask 147.Fa sigmask 148to be used while 149.Em libfido2's 150default I/O handlers wait on 151.Fa dev . 152On UNIX-like operating systems, 153.Vt fido_sigset_t 154is defined as 155.Vt sigset_t . 156On Windows, 157.Vt fido_sigset_t 158is defined as 159.Vt int 160and 161.Fn fido_dev_set_sigmask 162is a no-op. 163.Pp 164No references to 165.Fa sigmask 166are held by 167.Fn fido_dev_set_sigmask . 168.Pp 169The 170.Fn fido_dev_set_timeout 171function informs 172.Em libfido2 173not to block for more than 174.Fa ms 175milliseconds while communicating with 176.Fa dev . 177If a timeout occurs, the corresponding 178.Em fido_dev_* 179function will fail with 180.Dv FIDO_ERR_RX . 181If 182.Fa ms 183is -1, 184then 185.Em libfido2 186may block indefinitely. 187This is the default behaviour. 188When using the Windows Hello backend, 189.Fa ms 190is used as a guidance and may be overwritten by the platform. 191.Pp 192The 193.Fn fido_dev_set_transport_functions 194function sets the transport functions used by 195.Em libfido2 196to talk to 197.Fa dev . 198While the I/O handlers are responsible for sending and receiving 199transmission units of initialization and continuation packets already 200formatted by 201.Em libfido2 , 202the transport handlers are responsible for sending and receiving 203the CTAPHID commands and data directly, as defined in the FIDO Client 204to Authenticator Protocol (CTAP) standard. 205They are defined as follows: 206.Bl -tag -width Ds 207.It Vt fido_dev_tx_t 208Receives a device, a CTAPHID command to transmit, a data buffer to 209transmit, and the length of the data buffer. 210On success, 0 is returned. 211On error, -1 is returned. 212.It Vt fido_dev_rx_t 213Receives a device, a CTAPHID command whose response the caller expects 214to receive, a data buffer to receive into, the size of the data buffer 215determining the maximum length of a response, and the maximum number of 216milliseconds to wait for a response. 217On success, the number of bytes read into the data buffer is returned. 218On error, -1 is returned. 219.El 220.Pp 221When transport functions are specified, 222.Em libfido2 223will use them instead of the 224.Dv read 225and 226.Dv write 227functions of the I/O handlers. 228However, the I/O handlers must still be specified to open and close the 229device. 230.Pp 231The 232.Fn fido_dev_io_handle 233function returns the opaque pointer returned by the 234.Dv open 235function of the I/O handlers. 236This is useful mainly for the transport functions, which unlike the I/O 237handlers are passed the 238.Vt fido_dev_t 239pointer instead of the opaque I/O handle. 240.Sh RETURN VALUES 241On success, 242.Fn fido_dev_set_io_functions , 243.Fn fido_dev_set_transport_functions , 244.Fn fido_dev_set_sigmask , 245and 246.Fn fido_dev_set_timeout 247return 248.Dv FIDO_OK . 249On error, a different error code defined in 250.In fido/err.h 251is 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 262