0afa8e065e
git-subtree-dir: contrib/libfido2 git-subtree-mainline: d586c978b9b4216869e589daa5bbcc33225a0e35 git-subtree-split: a58dee945a5da64d0e97f35a508928e0d17c9cc7
144 lines
3.2 KiB
Groff
144 lines
3.2 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
|
|
.Nd FIDO 2 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"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn fido_dev_info_manifest
|
|
function fills
|
|
.Fa devlist
|
|
with up to
|
|
.Fa ilen
|
|
FIDO 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 .
|
|
.Pp
|
|
The
|
|
.Fn fido_dev_info_product_string
|
|
function returns the product string of
|
|
.Fa di .
|
|
.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 .
|
|
.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
|
|
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.
|