.\" Copyright (c) 2018-2021 Yubico AB. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\"    1. Redistributions of source code must retain the above copyright
.\"       notice, this list of conditions and the following disclaimer.
.\"    2. Redistributions in binary form must reproduce the above copyright
.\"       notice, this list of conditions and the following disclaimer in
.\"       the documentation and/or other materials provided with the
.\"       distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.Dd $Mdocdate: May 25 2018 $
.Dt FIDO_DEV_SET_IO_FUNCTIONS 3
.Os
.Sh NAME
.Nm fido_dev_set_io_functions ,
.Nm fido_dev_set_sigmask ,
.Nm fido_dev_set_timeout ,
.Nm fido_dev_set_transport_functions ,
.Nm fido_dev_io_handle
.Nd FIDO2 device I/O interface
.Sh SYNOPSIS
.In fido.h
.Bd -literal
typedef void *fido_dev_io_open_t(const char *);
typedef void  fido_dev_io_close_t(void *);
typedef int   fido_dev_io_read_t(void *, unsigned char *, size_t, int);
typedef int   fido_dev_io_write_t(void *, const unsigned char *, size_t);

typedef struct fido_dev_io {
	fido_dev_io_open_t  *open;
	fido_dev_io_close_t *close;
	fido_dev_io_read_t  *read;
	fido_dev_io_write_t *write;
} fido_dev_io_t;

#ifdef _WIN32
typedef int fido_sigset_t;
#else
typedef sigset_t fido_sigset_t;
#endif

typedef int   fido_dev_rx_t(struct fido_dev *,
                  uint8_t, unsigned char *, size_t, int);
typedef int   fido_dev_tx_t(struct fido_dev *,
                  uint8_t, const unsigned char *, size_t);

typedef struct fido_dev_transport {
	fido_dev_rx_t *rx;
	fido_dev_tx_t *tx;
} fido_dev_transport_t;
.Ed
.Pp
.Ft int
.Fn fido_dev_set_io_functions "fido_dev_t *dev" "const fido_dev_io_t *io"
.Ft int
.Fn fido_dev_set_sigmask "fido_dev_t *dev" "const fido_sigset_t *sigmask"
.Ft int
.Fn fido_dev_set_timeout "fido_dev_t *dev" "int ms"
.Ft int
.Fn fido_dev_set_transport_functions "fido_dev_t *dev" "const fido_dev_transport_t *t"
.Ft void *
.Fn fido_dev_io_handle "const fido_dev_t *dev"
.Sh DESCRIPTION
The
.Fn fido_dev_set_io_functions
function sets the I/O handlers used by
.Em libfido2
to talk to
.Fa dev .
By default, these handlers are set to the operating system's native HID or NFC
interfaces.
They are defined as follows:
.Bl -tag -width Ds
.It Vt fido_dev_open_t
Receives a
.Vt const char *
holding a path and opens the corresponding device, returning a
non-NULL opaque pointer on success and NULL on error.
.It Vt fido_dev_close_t
Receives the opaque pointer returned by
.Vt fido_dev_open_t
and closes the device.
.It Vt fido_dev_read_t
Reads a single transmission unit (HID report, APDU) from a device.
The first parameter is the opaque pointer returned by
.Vt fido_dev_open_t .
The second parameter is the read buffer, and the third parameter
is the read buffer size.
The fourth parameter is the number of milliseconds the caller is
willing to sleep, should the call need to block.
If this value holds -1,
.Vt fido_dev_read_t
may block indefinitely.
On success, the number of bytes read is returned.
On error, -1 is returned.
.It Vt fido_dev_write_t
Writes a single transmission unit (HID report, APDU) to
.Fa dev .
The first parameter is the opaque pointer returned by
.Vt fido_dev_open_t .
The second parameter is the write buffer, and the third parameter
is the number of bytes to be written.
A
.Vt fido_dev_write_t
may block.
On success, the number of bytes written is returned.
On error, -1 is returned.
.El
.Pp
When calling
.Fn fido_dev_set_io_functions ,
the
.Fa open ,
.Fa close ,
.Fa read ,
and
.Fa write
fields of
.Fa io
may not be NULL.
.Pp
No references to
.Fa io
are held by
.Fn fido_dev_set_io_functions .
.Pp
The
.Fn fido_dev_set_sigmask
function may be used to specify a non-NULL signal mask
.Fa sigmask
to be used while
.Em libfido2's
default I/O handlers wait on
.Fa dev .
On UNIX-like operating systems,
.Vt fido_sigset_t
is defined as
.Vt sigset_t .
On Windows,
.Vt fido_sigset_t
is defined as
.Vt int
and
.Fn fido_dev_set_sigmask
is a no-op.
.Pp
No references to
.Fa sigmask
are held by
.Fn fido_dev_set_sigmask .
.Pp
The
.Fn fido_dev_set_timeout
function informs
.Em libfido2
not to block for more than
.Fa ms
milliseconds while communicating with
.Fa dev .
If a timeout occurs, the corresponding
.Em fido_dev_*
function will fail with
.Dv FIDO_ERR_RX .
If
.Fa ms
is -1,
then
.Em libfido2
may block indefinitely.
This is the default behaviour.
When using the Windows Hello backend,
.Fa ms
is used as a guidance and may be overwritten by the platform.
.Pp
The
.Fn fido_dev_set_transport_functions
function sets the transport functions used by
.Em libfido2
to talk to
.Fa dev .
While the I/O handlers are responsible for sending and receiving
transmission units of initialization and continuation packets already
formatted by
.Em libfido2 ,
the transport handlers are responsible for sending and receiving
the CTAPHID commands and data directly, as defined in the FIDO Client
to Authenticator Protocol (CTAP) standard.
They are defined as follows:
.Bl -tag -width Ds
.It Vt fido_dev_tx_t
Receives a device, a CTAPHID command to transmit, a data buffer to
transmit, and the length of the data buffer.
On success, 0 is returned.
On error, -1 is returned.
.It Vt fido_dev_rx_t
Receives a device, a CTAPHID command whose response the caller expects
to receive, a data buffer to receive into, the size of the data buffer
determining the maximum length of a response, and the maximum number of
milliseconds to wait for a response.
On success, the number of bytes read into the data buffer is returned.
On error, -1 is returned.
.El
.Pp
When transport functions are specified,
.Em libfido2
will use them instead of the
.Dv read
and
.Dv write
functions of the I/O handlers.
However, the I/O handlers must still be specified to open and close the
device.
.Pp
The
.Fn fido_dev_io_handle
function returns the opaque pointer returned by the
.Dv open
function of the I/O handlers.
This is useful mainly for the transport functions, which unlike the I/O
handlers are passed the
.Vt fido_dev_t
pointer instead of the opaque I/O handle.
.Sh RETURN VALUES
On success,
.Fn fido_dev_set_io_functions ,
.Fn fido_dev_set_transport_functions ,
.Fn fido_dev_set_sigmask ,
and
.Fn fido_dev_set_timeout
return
.Dv FIDO_OK .
On error, a different error code defined in
.In fido/err.h
is returned.
.Sh SEE ALSO
.Xr fido_dev_info_manifest 3 ,
.Xr fido_dev_open 3
.Rs
.%D 2021-06-15
.%O Proposed Standard, Version 2.1
.%Q FIDO Alliance
.%R Client to Authenticator Protocol (CTAP)
.%U https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html
.Re