1.\" Copyright (c) 2018 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: August 11 2020 $ 6.Dt FIDO_DEV_SET_IO_FUNCTIONS 3 7.Os 8.Sh NAME 9.Nm fido_dev_set_io_functions 10.Nd FIDO 2 device I/O interface 11.Sh SYNOPSIS 12.In fido.h 13.Bd -literal 14typedef void *fido_dev_io_open_t(const char *); 15typedef void fido_dev_io_close_t(void *); 16typedef int fido_dev_io_read_t(void *, unsigned char *, size_t, int); 17typedef int fido_dev_io_write_t(void *, const unsigned char *, size_t); 18typedef int fido_dev_io_rx_t(struct fido_dev *, uint8_t, unsigned char *, size_t, int); 19typedef int fido_dev_io_tx_t(struct fido_dev *, uint8_t, const unsigned char *, size_t); 20 21typedef struct fido_dev_io { 22 fido_dev_io_open_t *open; 23 fido_dev_io_close_t *close; 24 fido_dev_io_read_t *read; 25 fido_dev_io_write_t *write; 26 fido_dev_io_rx_t *rx; 27 fido_dev_io_tx_t *tx; 28} fido_dev_io_t; 29.Ed 30.Ft int 31.Fn fido_dev_set_io_functions "fido_dev_t *dev" "const fido_dev_io_t *io" 32.Sh DESCRIPTION 33The 34.Nm 35interface defines the I/O and transmission handlers used to talk to 36.Fa dev . 37Its usage is optional. 38By default, 39.Em libfido2 40will use the operating system's native HID interface to talk CTAP2 to 41a FIDO device. 42.Pp 43A 44.Vt fido_dev_io_open_t 45function is expected to return a non-NULL opaque pointer on success, 46and NULL on error. 47The returned opaque pointer is never dereferenced by 48.Em libfido2 . 49.Pp 50A 51.Vt fido_dev_io_close_t 52function receives the opaque handle obtained from 53.Vt fido_dev_io_open_t . 54It is not expected to be idempotent. 55.Pp 56A 57.Vt fido_dev_io_read_t 58function reads a single HID report from 59.Fa dev . 60The first parameter taken is the opaque handle obtained from 61.Vt fido_dev_io_open_t . 62The read buffer is pointed to by the second parameter, and the 63third parameter holds its size. 64The last argument passed to 65.Vt fido_dev_io_read_t 66is the number of milliseconds the caller is willing to sleep, 67should the call need to block. 68If this value holds -1, 69.Vt fido_dev_io_read_t 70may block indefinitely. 71The number of bytes read is returned. 72On error, -1 is returned. 73.Pp 74A 75.Vt fido_dev_io_write_t 76function writes a single HID report to 77.Fa dev . 78The first parameter taken is the opaque handle returned by 79.Vt fido_dev_io_open_t . 80The write buffer is pointed to by the second parameter, and the 81third parameter holds its size. 82A 83.Vt fido_dev_io_write_t 84function may block. 85The number of bytes written is returned. 86On error, -1 is returned. 87.Pp 88A 89.Vt fido_dev_io_rx_t 90function receives a complete CTAP2 message from 91.Fa dev . 92The first parameter taken is a pointer to 93.Fa dev . 94The second parameter holds the expected CTAP2 command byte. 95The read buffer is pointed to by the third parameter, and the 96fourth parameter holds its size. 97The last argument passed to 98.Vt fido_dev_io_rx_t 99is the number of milliseconds the caller is willing to sleep, 100should the call need to block. 101If this value holds -1, 102.Vt fido_dev_io_rx_t 103may block indefinitely. 104The number of bytes read is returned. 105On error, -1 is returned. 106.Pp 107A 108.Vt fido_dev_io_tx_t 109function transmits a complete CTAP2 message to 110.Fa dev . 111The first parameter taken is a pointer to 112.Fa dev . 113The second parameter holds the CTAP2 command byte. 114The write buffer is pointed to by the third parameter, and the 115fourth parameter holds its size. 116A 117.Vt fido_dev_io_tx_t 118function may block. 119On success, 0 is returned. 120On error, -1 is returned. 121.Pp 122When calling 123.Fn fido_dev_set_io_functions , 124the 125.Fa open , 126.Fa close , 127.Fa read 128and 129.Fa write 130fields of 131.Fa io 132may not be NULL. 133Either 134.Fa rx 135or 136.Fa tx 137may be NULL, in which case 138.Em libfido2 139uses its corresponding CTAP2 HID transport method. 140.Pp 141No references to 142.Fa io 143are held by 144.Fn fido_dev_set_io_functions . 145.Sh RETURN VALUES 146On success, 147.Fn fido_dev_set_io_functions 148returns 149.Dv FIDO_OK . 150On error, a different error code defined in 151.In fido/err.h 152is returned. 153