3e696dfb70
Some highlights from NEWS:
** bio: fix CTAP2 canonical CBOR encoding in fido_bio_dev_enroll_*();
gh#480.
** New API calls:
- fido_dev_info_set;
- fido_dev_io_handle;
- fido_dev_new_with_info;
- fido_dev_open_with_info.
** Documentation and reliability fixes.
** Support for TPM 2.0 attestation of COSE_ES256 credentials.
Relnotes: Yes
Sponsored by: The FreeBSD Foundation
189 lines
4.4 KiB
Groff
189 lines
4.4 KiB
Groff
.\" Copyright (c) 2018 Yubico AB. All rights reserved.
|
|
.\" Use of this source code is governed by a BSD-style
|
|
.\" license that can be found in the LICENSE file.
|
|
.\"
|
|
.Dd $Mdocdate: May 25 2018 $
|
|
.Dt FIDO_DEV_INFO_MANIFEST 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm fido_dev_info_manifest ,
|
|
.Nm fido_dev_info_new ,
|
|
.Nm fido_dev_info_free ,
|
|
.Nm fido_dev_info_ptr ,
|
|
.Nm fido_dev_info_path ,
|
|
.Nm fido_dev_info_product ,
|
|
.Nm fido_dev_info_vendor ,
|
|
.Nm fido_dev_info_manufacturer_string ,
|
|
.Nm fido_dev_info_product_string ,
|
|
.Nm fido_dev_info_set
|
|
.Nd FIDO2 device discovery functions
|
|
.Sh SYNOPSIS
|
|
.In fido.h
|
|
.Ft int
|
|
.Fn fido_dev_info_manifest "fido_dev_info_t *devlist" "size_t ilen" "size_t *olen"
|
|
.Ft fido_dev_info_t *
|
|
.Fn fido_dev_info_new "size_t n"
|
|
.Ft void
|
|
.Fn fido_dev_info_free "fido_dev_info_t **devlist_p" "size_t n"
|
|
.Ft const fido_dev_info_t *
|
|
.Fn fido_dev_info_ptr "const fido_dev_info_t *devlist" "size_t i"
|
|
.Ft const char *
|
|
.Fn fido_dev_info_path "const fido_dev_info_t *di"
|
|
.Ft int16_t
|
|
.Fn fido_dev_info_product "const fido_dev_info_t *di"
|
|
.Ft int16_t
|
|
.Fn fido_dev_info_vendor "const fido_dev_info_t *di"
|
|
.Ft const char *
|
|
.Fn fido_dev_info_manufacturer_string "const fido_dev_info_t *di"
|
|
.Ft const char *
|
|
.Fn fido_dev_info_product_string "const fido_dev_info_t *di"
|
|
.Ft int
|
|
.Fn fido_dev_info_set "fido_dev_info_t *devlist" "size_t i" "const char *path" "const char *manufacturer" "const char *product" "const fido_dev_io_t *io" "const fido_dev_transport_t *transport"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn fido_dev_info_manifest
|
|
function fills
|
|
.Fa devlist
|
|
with up to
|
|
.Fa ilen
|
|
FIDO2 devices found by the underlying operating system.
|
|
Currently only USB HID devices are supported.
|
|
The number of discovered devices is returned in
|
|
.Fa olen ,
|
|
where
|
|
.Fa olen
|
|
is an addressable pointer.
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_info_new
|
|
function returns a pointer to a newly allocated, empty device list
|
|
with
|
|
.Fa n
|
|
available slots.
|
|
If memory is not available, NULL is returned.
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_info_free
|
|
function releases the memory backing
|
|
.Fa *devlist_p ,
|
|
where
|
|
.Fa *devlist_p
|
|
must have been previously allocated by
|
|
.Fn fido_dev_info_new .
|
|
The number
|
|
.Fa n
|
|
of allocated slots must also be provided.
|
|
On return,
|
|
.Fa *devlist_p
|
|
is set to NULL.
|
|
Either
|
|
.Fa devlist_p
|
|
or
|
|
.Fa *devlist_p
|
|
may be NULL, in which case
|
|
.Fn fido_dev_info_free
|
|
is a NOP.
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_info_ptr
|
|
function returns a pointer to slot number
|
|
.Fa i
|
|
of
|
|
.Fa devlist .
|
|
It is the caller's responsibility to ensure that
|
|
.Fa i
|
|
is bounded.
|
|
Please note that the first slot has index 0.
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_info_path
|
|
returns the filesystem path or subsystem-specific identification
|
|
string of
|
|
.Fa di .
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_info_product
|
|
function returns the product ID of
|
|
.Fa di .
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_info_vendor
|
|
function returns the vendor ID of
|
|
.Fa di .
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_info_manufacturer_string
|
|
function returns the manufacturer string of
|
|
.Fa di .
|
|
If
|
|
.Fa di
|
|
does not have an associated manufacturer string,
|
|
.Fn fido_dev_info_manufacturer_string
|
|
returns an empty string.
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_info_product_string
|
|
function returns the product string of
|
|
.Fa di .
|
|
If
|
|
.Fa di
|
|
does not have an associated product string,
|
|
.Fn fido_dev_info_product_string
|
|
returns an empty string.
|
|
.Pp
|
|
An example of how to use the functions described in this document
|
|
can be found in the
|
|
.Pa examples/manifest.c
|
|
file shipped with
|
|
.Em libfido2 .
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_info_set
|
|
function initializes an entry in a device list allocated by
|
|
.Fn fido_dev_info_new
|
|
with the specified path, manufacturer, and product strings, and with
|
|
the specified I/O handlers and, optionally, transport functions, as
|
|
described in
|
|
.Xr fido_dev_set_io_functions 3 .
|
|
The
|
|
.Fa io
|
|
argument must be specified; the
|
|
.Fa transport
|
|
argument may be
|
|
.Dv NULL .
|
|
The path, I/O handlers, and transport functions will be used
|
|
automatically by
|
|
.Xr fido_dev_new_with_info 3
|
|
and
|
|
.Xr fido_dev_open_with_info 3 .
|
|
An application can use this, for example, to substitute mock FIDO2
|
|
devices in testing for the real ones that
|
|
.Fn fido_dev_info_manifest
|
|
would discover.
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn fido_dev_info_manifest
|
|
function always returns
|
|
.Dv FIDO_OK .
|
|
If a discovery error occurs, the
|
|
.Fa olen
|
|
pointer is set to 0.
|
|
.Pp
|
|
On success, the
|
|
.Fn fido_dev_info_set
|
|
function returns
|
|
.Dv FIDO_OK .
|
|
On error, a different error code defined in
|
|
.In fido/err.h
|
|
is returned.
|
|
.Pp
|
|
The pointers returned by
|
|
.Fn fido_dev_info_ptr ,
|
|
.Fn fido_dev_info_path ,
|
|
.Fn fido_dev_info_manufacturer_string ,
|
|
and
|
|
.Fn fido_dev_info_product_string
|
|
are guaranteed to exist until
|
|
.Fn fido_dev_info_free
|
|
is called on the corresponding device list.
|