1FIDO_DEV_SET_IO_FUNCT... BSD Library Functions Manual FIDO_DEV_SET_IO_FUNCT...
2

NAME

4     fido_dev_set_io_functions, fido_dev_set_sigmask, fido_dev_set_timeout,
5     fido_dev_set_transport_functions, fido_dev_io_handle — FIDO2 device I/O
6     interface
7

SYNOPSIS

9     #include <fido.h>
10
11     typedef void *fido_dev_io_open_t(const char *);
12     typedef void  fido_dev_io_close_t(void *);
13     typedef int   fido_dev_io_read_t(void *, unsigned char *, size_t, int);
14     typedef int   fido_dev_io_write_t(void *, const unsigned char *, size_t);
15
16     typedef struct fido_dev_io {
17             fido_dev_io_open_t  *open;
18             fido_dev_io_close_t *close;
19             fido_dev_io_read_t  *read;
20             fido_dev_io_write_t *write;
21     } fido_dev_io_t;
22
23     #ifdef _WIN32
24     typedef int fido_sigset_t;
25     #else
26     typedef sigset_t fido_sigset_t;
27     #endif
28
29     typedef int   fido_dev_rx_t(struct fido_dev *,
30                       uint8_t, unsigned char *, size_t, int);
31     typedef int   fido_dev_tx_t(struct fido_dev *,
32                       uint8_t, const unsigned char *, size_t);
33
34     typedef struct fido_dev_transport {
35             fido_dev_rx_t *rx;
36             fido_dev_tx_t *tx;
37     } fido_dev_transport_t;
38
39     int
40     fido_dev_set_io_functions(fido_dev_t *dev, const fido_dev_io_t *io);
41
42     int
43     fido_dev_set_sigmask(fido_dev_t *dev, const fido_sigset_t *sigmask);
44
45     int
46     fido_dev_set_timeout(fido_dev_t *dev, int ms);
47
48     int
49     fido_dev_set_transport_functions(fido_dev_t *dev,
50         const fido_dev_transport_t *t);
51
52     void *
53     fido_dev_io_handle(const fido_dev_t *dev);
54

DESCRIPTION

56     The fido_dev_set_io_functions() function sets the I/O handlers used by
57     libfido2 to talk to dev.  By default, these handlers are set to the oper‐
58     ating system's native HID or NFC interfaces.  They are defined as fol‐
59     lows:
60
61     fido_dev_open_t
62             Receives a const char * holding a path and opens the correspond‐
63             ing device, returning a non-NULL opaque pointer on success and
64             NULL on error.
65
66     fido_dev_close_t
67             Receives the opaque pointer returned by fido_dev_open_t and
68             closes the device.
69
70     fido_dev_read_t
71             Reads a single transmission unit (HID report, APDU) from a de‐
72             vice.  The first parameter is the opaque pointer returned by
73             fido_dev_open_t.  The second parameter is the read buffer, and
74             the third parameter is the read buffer size.  The fourth parame‐
75             ter is the number of milliseconds the caller is willing to sleep,
76             should the call need to block.  If this value holds -1,
77             fido_dev_read_t may block indefinitely.  On success, the number
78             of bytes read is returned.  On error, -1 is returned.
79
80     fido_dev_write_t
81             Writes a single transmission unit (HID report, APDU) to dev.  The
82             first parameter is the opaque pointer returned by
83             fido_dev_open_t.  The second parameter is the write buffer, and
84             the third parameter is the number of bytes to be written.  A
85             fido_dev_write_t may block.  On success, the number of bytes
86             written is returned.  On error, -1 is returned.
87
88     When calling fido_dev_set_io_functions(), the open, close, read, and
89     write fields of io may not be NULL.
90
91     No references to io are held by fido_dev_set_io_functions().
92
93     The fido_dev_set_sigmask() function may be used to specify a non-NULL
94     signal mask sigmask to be used while libfido2's default I/O handlers wait
95     on dev.  On UNIX-like operating systems, fido_sigset_t is defined as
96     sigset_t.  On Windows, fido_sigset_t is defined as int and
97     fido_dev_set_sigmask() is a no-op.
98
99     No references to sigmask are held by fido_dev_set_sigmask().
100
101     The fido_dev_set_timeout() function informs libfido2 not to block for
102     more than ms milliseconds while communicating with dev.  If a timeout oc‐
103     curs, the corresponding fido_dev_* function will fail with FIDO_ERR_RX.
104     If ms is -1, then libfido2 may block indefinitely.  This is the default
105     behaviour.  When using the Windows Hello backend, ms is used as a guid‐
106     ance and may be overwritten by the platform.
107
108     The fido_dev_set_transport_functions() function sets the transport func‐
109     tions used by libfido2 to talk to dev.  While the I/O handlers are re‐
110     sponsible for sending and receiving transmission units of initialization
111     and continuation packets already formatted by libfido2, the transport
112     handlers are responsible for sending and receiving the CTAPHID commands
113     and data directly, as defined in the FIDO Client to Authenticator Proto‐
114     col (CTAP) standard.  They are defined as follows:
115
116     fido_dev_tx_t
117             Receives a device, a CTAPHID command to transmit, a data buffer
118             to transmit, and the length of the data buffer.  On success, 0 is
119             returned.  On error, -1 is returned.
120
121     fido_dev_rx_t
122             Receives a device, a CTAPHID command whose response the caller
123             expects to receive, a data buffer to receive into, the size of
124             the data buffer determining the maximum length of a response, and
125             the maximum number of milliseconds to wait for a response.  On
126             success, the number of bytes read into the data buffer is re‐
127             turned.  On error, -1 is returned.
128
129     When transport functions are specified, libfido2 will use them instead of
130     the read and write functions of the I/O handlers.  However, the I/O han‐
131     dlers must still be specified to open and close the device.
132
133     The fido_dev_io_handle() function returns the opaque pointer returned by
134     the open function of the I/O handlers.  This is useful mainly for the
135     transport functions, which unlike the I/O handlers are passed the
136     fido_dev_t pointer instead of the opaque I/O handle.
137

RETURN VALUES

139     On success, fido_dev_set_io_functions(),
140     fido_dev_set_transport_functions(), fido_dev_set_sigmask(), and
141     fido_dev_set_timeout() return FIDO_OK.  On error, a different error code
142     defined in <fido/err.h> is returned.
143

SEE ALSO

145     fido_dev_info_manifest(3), fido_dev_open(3)
146
147     Client to Authenticator Protocol (CTAP),
148     https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-
149     authenticator-protocol-v2.1-ps-20210615.html, FIDO Alliance, 2021-06-15,
150     Proposed Standard, Version 2.1.
151
152BSD                              May 25, 2018                              BSD
Impressum