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